Looking pretty good!

The one thing I'm uncomfortable with is the idiosyncratic usage of the term "mapping".

Usually a mapping (or a map) means a system that maps each element in a source set to an element in a target set. In JSON, an object would be a mapping. In mathematics, a function would be a mapping.

Thus, the object that is now named mappings is really just a single mapping. But rather than calling it mapping (which would be a bit like naming the profile array array), perhaps a more descriptive name like aliases would be in order.

A key inside mappings is already called an "alias", which makes sense and would seem to support naming the container aliases as well.

A key–value pair inside mappings is currently called a "mapping", but this entity doesn't seem to require a name of its own. The definition is there, but it's never used apart from a single non-normative note. If there's a need to call it something, call it an "alias definition".

Great job Ethan. It's a good start to integrate extensions. I'm a bit busy at the moment, but I want to give you a short feedback.

Some notes:

• The mixed used of mapping and alias could be a bit confusing, so I agree to @bintoro.
• Also you use the terms "profile extension", "profile" (in links) and "extension" (in error objects). Perhaps this should be clarified and mentioned, that other types of extensions can be defined later.
• Perhaps it should be noted, that the "non a-z" rule still means that the rules for member names must still be met. Also it wasn't clear for me that this was meant case-sensitive when I read it the first time. (I know this is not final...)

Regarding the missing extensions error:
I previously suggested to return a group (array) of extensions, if one extension of the group is required. This way you avoid the additional member:

{
 "errors": [{
  "missing": {
   "extension": [
    "http://jsonapi.org/ext1",
    ["http://jsonapi.org/ext2", "http://jsonapi.org/ext3"]
   ]
  }
 }
}

A lot of the discussion over at #915 revolved around the naming system, which should, ideally, have the following properties:

• Profile aliases should look like first-class members (no prefixing).
• It should be possible to interleave data from two extensions without causing key collisions.

One obvious approach that I don't think was ever brought up is to prefix a global name whenever it appears inside an extension object:

{
  "aliases": {
    "attribute-validation": "http://jsonapi.org/ext/attribute-validation",
    "common-validators": "http://jsonapi.org/ext/validators",
  },
  "data": {
    "type": "articles", 
    "id": "1",
    "attributes": {"title": "Lorem ipsum"}
  },
  "attribute-validation": { // Appears in global scope -> no prefix
    "articles": {
      "title": {
        "$common-validators": {"string": true} // Nested alias -> prefix "$"
      }
    }
  }
}

This wouldn't treat extension aliases any differently from officially defined members because those, too, would have to be designated somehow if they were to appear within extension data.

Other responses...

Thus, the object that is now named mappings is really just a single mapping. But rather than calling it mapping (which would be a bit like naming the profile array array), perhaps a more descriptive name like aliases would be in order.

First, a heads up that I'm still not sure whether mappings should exist at all—that depends on how far JSON API wants to go down the path of supporting hypermedia. I.e. if we want extended rels and CURIEs, then mappings makes sense, but what if we don't? How much hypermedia we should support natively, vs. how much we should just hand off to JSON-LD (for devs who want to opt into that) is something I've been thinking about a lot lately. It's a bigger question, and I'll open an issue about it soon.

So, since mappings might go altogether, I don't think it makes sense to spend time debating the name now. For context, though... I had named it aliases before, but changed it to mappings because I was imagining some types of key–value mappings (for hypermedia purposes) that wouldn't really make sense to call "aliases". Per the above, though, we may decide that those kind of mappings aren't within the scope of JSON API, so let's figure that out first.

Perhaps this should be clarified and mentioned, that other types of extensions can be defined later.

@ziege Yes, I think that's fair. I'll update the PR accordingly.

Perhaps it should be noted, that the "non a-z" rule still means that the rules for member names must still be met. Also it wasn't clear for me that this was meant case-sensitive when I read it the first time. (I know this is not final...)

Good points. Let's revisit this if we end up sticking with the non a-z rule.

One obvious approach that I don't think was ever brought up is to prefix a global name whenever it appears inside an extension object:

Thanks! I'll add this to the list of possible approaches :) Hopefully I'll have a chance to talk with the other editors soon and we can figure out the priorities (functional and aesthetic) & narrow down the naming options.

I previously suggested to return a group (array) of extensions, if one extension of the group is required.

Right. In my proposal, though, each missing extension get's its own error (which is important because the extensions could be missing at different pointers). So there'd never be a value like:

"extension": ["http://jsonapi.org/ext1", ["http://jsonapi.org/ext2", "http://jsonapi.org/ext3"]]

Instead, the missing ext1 would have its own error object, and the other value would be:

"extension": ["http://jsonapi.org/ext2", "http://jsonapi.org/ext3"]

And that's where I think it's unclear to readers... if there is only one missing extension (i.e. if ext1 isn't missing/necessary, so there's just a choice between adding ext2 or ext3), and the above value is all the user sees, it's a little unclear whether both ext2 and ext3 are missing, or just one of them. That's what I was hoping we could find a better key name/structure for. Not a huge deal, but something to think about...

Quoting myself here...

Profile aliases should look like first-class members (no prefixing).

I'm not so sure about this requirement anymore.

Its origins were in the idea that very common extensions might eventually become kind of de facto standards and, hence, should also look like standard members.

However, at the same time, there's the "once an extension, always an extension" principle that specifically aims to keep (even universally adopted) extensions distinct from base spec additions.

These two ideas seem a bit contradictory. If maintaining an extension-introduced feature is permanently delegated to that extension, is there anything wrong with also permanently denoting the corresponding JSON member as such? Maybe not.

The aversion to "X-prefixing" that resulted in RFC 6648 is about cases where authors unilaterally introduce experimental names that later may become standardized. Neither applies to the situation here, as long as we have a registration requirement and a commitment not to absorb extensions into the base spec.

Given that a global prefixing scheme would immediately resolve the namespace-partitioning predicament, the option shouldn't be dismissed out of hand — except to leave the door open for assimilating extensions as true first-class members of the spec.

Also, I'm thinking it would probably be a good idea to preserve some form of the registered key scheme originally envisaged. Something like:

• A suggested/default key would be a required part of the registration info.
• APIs SHOULD use the suggested key.

Strongly encouraging all APIs to use the same key for the same extension would benefit everyone with no real downsides, so we should absolutely take the opportunity to do so. This is especially crucial in the absence of a global prefixing system. It seems pointless, even counterproductive, to make extension keys look like first-class members if their meaning can vary from server to server.

The core team talked about this PR at today's meeting, so I wanted to give y'all some updates and a chance to weigh in on the new ideas. (These aren't yet reflected in the PRs text, which I'll update once there's consensus on the details.)

1. Naming scheme. Rather than partitioning the key space to prevent naming conflicts, we're currently leaning toward putting extension keys inside meta, where they can be named whatever the user likes without preventing future base spec additions. This is analogous to the approach we took with the attributes and relationships: basically, creating new container objects to avoid prefixing and other schemes. So, an extension (with a nested extension) would look like this:

   {
     "mappings": {
       "attribute-validation": "http://jsonapi.org/ext/attribute-validation",
       "validators": "http://jsonapi.org/ext/validators",
     },
     "data": {
       "type": "articles", 
       "id": "1",
       "meta": {
         "attribute-validation": {
            "title": {
              "meta": {
                "validators": {"string": true}
              }
            }
         }
       },
       "attributes": {"title": "Lorem ipsum"}
     }
   }

   Is it more nesting? Undoubtedly. But it should only be one extra layer of nesting, since I expect extensions used inside of extensions to be a relatively rare case. And it's more consistent with the rest of the spec.

   Ideally, I wish the key were named something more descriptive than "meta"... but meta is something we already have, and we felt that adding a second key alongside it (e.g. an "extensions" key as @ziege proposed long ago) would unnecessarily complicate the spec and implementations.

   We also realizes that this mixes truly opaque custom data (i.e. that not associated with an extension URI) with extension-described data, but we see this as an advantage, as it allows existing APIs to associate the keys that they currently have in meta with an extension they can create now. Going forward, we'd hope that only extension-associated keys get put in meta, but the ability to add an opaque value there with no upfront ceremony (of figuring out, and perhaps defining, an extension) could be nice for prototyping or fast-moving teams.

   As a consequence of the change above, all the rules about non a-z names would go away.

2. Registration. We're also leaning toward removing the normative text requiring extension registration, in part to allow companies to create extensions that they can use internally without registering publicly. However, because extension discoverability and reuse is hugely important, there would still be prominent non-normative notes encouraging registration, and (as in the current PR) we might grant extensions that register a jsonapi.org URI, as a small incentive.

3. The mappings object. We're still trying to figure out the appropriate contours of JSON API hypermedia support, which will factor into the final name for mappings, as I mentioned. For now, though, we haven't had a chance to talk much about this.

4. Open question: can mappings support relative URIs?

@ethanresnick Thanks for updating as per our discussion.

I think we decided to use a top-level extensions object instead of mappings (obviously still open for discussion).

We didn't discuss using extensions within extensions specifically, but I don't see the need to use meta within meta as you've done in your validators example.

I imagine that the canonical home page example with a couple extensions might look like this:

{
  "extensions": {
    "pagination": "http://jsonapi.org/extensions/pagination",
    "revision": "http://jsonapi.org/extensions/revisions"
  },
  "links": {
    "self": "http://example.com/articles",
    "next": "http://example.com/articles?page[offset]=2",
    "last": "http://example.com/articles?page[offset]=10"
  },
  "meta": {
    "pagination": {
      "offset": "1",
      "count": "10"
    }
  }
  "data": [{
    "type": "articles",
    "id": "1",
    "meta": {
      "revision": "123456"
    }, 
    "attributes": {
      "title": "JSON API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    },
    "links": {
      "self": "http://example.com/articles/1"
    }
  }]
}

I think we decided to use a top-level extensions object instead of mappings (obviously still open for discussion).

Yeah, I remember you suggested that, I just wasn't sure whether we'd settled on it. My concern with calling the key extensions was that we may want to add other types of mappings later, and I'd rather not have to add yet more top-level keys to handle those. Tyler's (great) observation that we could express future mappings as extension data largely assuaged this concern, but it's still worth noting that the JSON is messier if we do it this way.

For instance, if we want to support CURIE-like strings as links object keys (to express extended link relations), we end up with:

{
  "extensions": {
    "pagination": "http://jsonapi.org/extensions/pagination",
    "revision": "http://jsonapi.org/extensions/revisions",
    "rel-prefixes": "http://jsonapi.org/extensions/extended-rels"
  },
  "meta": {
    "rel-prefixes": {
      "API": "http://mydomain.com/custom-rels/"
    }
  },
  "links": {
    "API/home": "http://mydomain.com/api/v2"
  }
  // ...
}

(Above, the rel-prefixes extension tells clients how to map links keys to full URIs.)

By contrast, if we called the extensions key aliases in 1.1 (the name I gave it before switching to the even more generic mappings), we'd end up with:

{
  "aliases": {
    "pagination": "http://jsonapi.org/extensions/pagination",
    "revision": "http://jsonapi.org/extensions/revisions",
    "API": "http://mydomain.com/custom-rels/"
  },
  "links": {
    "API/home": "http://mydomain.com/api/v2"
  }
  // ...
}

That's why I've seen the mappings naming decision as somewhat dependent on our hypermedia plans. Tyler's suggestion convinced me that the name mappings is too broad, but something like aliases (or bindings?) still seems sensible if we think we want to support extended relations.
 

We didn't discuss using extensions within extensions specifically, but I don't see the need to use meta within meta as you've done in your validators example.

Just to make sure we're talking about the same model for nesting extensions within extensions, check out this comment, if you haven't already, to see what I have in mind. Do you agree with that basic approach?

(Btw, here's the part of the PR that attempts to codify that model... it could maybe use some clarification.)

So, how would this work without the meta inside meta? I.e., in my example, how would the client know that validators is itself an extension-associated key, and not just a key defined by the attribute-validation extension?

Yeah, I remember you suggested that, I just wasn't sure whether we'd settled on it.

Fair enough. It does seem unsettled after all.

That's why I've seen the mappings naming decision as somewhat dependent on our hypermedia plans. Tyler's suggestion convinced me that the name mappings is too broad, but something like aliases (or bindings?) still seems sensible if we think we want to support extended relations.

We should consider using the top-level jsonapi object for declaring everything about an implementation, including extensions. This seems to fit its described purpose and would eliminate top-level noise.

Just to make sure we're talking about the same model for nesting extensions within extensions, check out this comment, if you haven't already, to see what I have in mind. Do you agree with that basic approach?

I think we're going down the rabbit hole of complexity here. An extension must be defined by the URL associated with it, and its value can be opaque to the base json:api spec. I'm not convinced that we need rules for extension composition in the base spec. If a particular extension wants to yield to other extensions at a particular key, then that's its prerogative. The extension can write the rules of what's allowed for any key under its control.

Big 👍 for using the jsonapi object for extending our hypermedia stuff further!

Using jsonapi to hold extension and/or other hypermedia info sounds fine to me, but it just seems to push the naming problem back a level, right? (I.e. now what do we call the key that holds the users mappings within the jsonapi bucket?)

Re how much control we need to exert over extension composition... I'm not sure... let's talk about it next week?

@ethanresnick can you pull out your @ prefix change to a separate PR so we can land it?

any updates on this and a general 1.1 roadmap? its is 11 months past the milestone in https://github.com/json-api/json-api/milestone/2.

Superseded by #1195 and #1196.