I'm working on a project to implement JSON API. It's written in PHP and I just had to change the code, because in the next version of the language new reserved keywords will be introduced ("resource", "object" and so on). This made me think about reserved keywords in JSON API, future version compatibility and the extensibility in general.

I see the following problems here:

1. A new version of the spec could introduce new reserved keywords that could conflict with existing custom attributes. So a little change in the spec could break APIs and prevent one from switching to the new version. Also if the API would be changed to resolve these conflicts, this would break all clients.

2. I thought about an extension for JSON API, which would require a new member at the top level. This member could also conflict with existing attributes in some APIs, so that one isn't able to use it.

Suggestion:

I would change the rules for the naming of members. I thought about namespaces (like in HAL), but I think this would make thinks unnecessarily difficult for clients. So I'd prefer the idea from #558 and extend it a bit (based on my suggestions for the naming of members, #567):

• All reserved keywords will be prefixed with an underscore (or another special character, that isn't allowed at the first position of custom members).
• All members, added by extensions, will we prefixed with an underscore, the extension name and a second underscore.

Example:

Current format:

{
  "data": {
    "type": "articles",
    "id": "1",
    "links": {
      "author": {
        "linkage": { 
          "type": "people", 
          "id": "1" 
        }
      }
    },
    "title": "This is my article",
    "status": "online"
  },
  "status": "status from extension 'myextension'"
}

Suggested format:

{
  "_data": {
    "_type": "articles",
    "_id": "1",
    "_links": {
      "author": {
        "_linkage": { 
          "_type": "people", 
          "_id": "1" 
        }
      }
    },
    "title": "This is my article",
    "status": "online"
  },
  "_myextension_status": "status from extension 'myextension'"
}

If "status" gets a reserved keyword in a future version and the extension wants to add a "status" member to the top level and to resources, this would be possible now, without any conflict, although the custom member "status" already exists:

{
  "_data": {
    "_type": "articles",
    "_id": "1",
    "_links": {
      "author": {
        "_linkage": { 
          "_type": "people", 
          "_id": "1" 
        }
      }
    },
    "_status": "general status information of the API",
    "title": "This is my article",
    "status": "online",
    "_myextension_status": "status from extension 'myextension'"
  }
  "_status": "general status information of the API",
  "_myextension_status": "status from extension 'myextension'"
}

Advantages:

• The API can be easily ported to a new version without any conflicts and without breaking clients.
• You can activate new extensions without having to change the API.

Required changes:

• Add a prefix for all predefined members - suggestion: underscore (U+005F LOW LINE, "_").
• Add a prefix for all extension members - suggestion: underscore (U+005F LOW LINE, "") + extension name + underscore (U+005F LOW LINE, "").
• Extension names must not contain an underscore (U+005F LOW LINE, "_").