diff --git a/_format/1.1/index.md b/_format/1.1/index.md index cca72d398..be49c5270 100644 --- a/_format/1.1/index.md +++ b/_format/1.1/index.md @@ -631,6 +631,26 @@ The following characters **MUST NOT** be used in member names: - U+007F DELETE - U+0000 to U+001F (C0 Controls) +#### @-Members + +Member names **MAY** also begin with an at sign (U+0040 COMMERCIAL AT, "@"). +Members named this way are called "@-Members". @-Members **MAY** appear +anywhere in a JSON API document. + +However, JSON API processors **MUST** completely ignore @-Members (i.e. not +treat them as JSON API data). + +Moreover, the existence of @-Members **MUST** be ignored when interpreting all +JSON API definitions and processing instructions given outside of this +subsection. For example, an [attribute][attributes] is defined above as any +member of the attributes object. However, because @-Members must be ignored +when interpreting that definition, an @-Member that occurs in an attributes +object is not an attribute. + +> Note: Among other things, "@" members can be used to add JSON-LD data to a +JSON API document. Such documents should be served with [an extra header](http://www.w3.org/TR/json-ld/#interpreting-json-as-json-ld) +to convey to JSON-LD clients that they contain JSON-LD data. + ## Fetching Data Data, including resources and relationships, can be fetched by sending a diff --git a/_format/1.1/normative-statements.json b/_format/1.1/normative-statements.json index d05f78c6c..c645e8c93 100644 --- a/_format/1.1/normative-statements.json +++ b/_format/1.1/normative-statements.json @@ -89,7 +89,11 @@ layout: null { "id": "member-name-globally-allowed", "type": "normative-statements" }, { "id": "member-name-url-safe", "type": "normative-statements" }, { "id": "member-name-allowed-characters", "type": "normative-statements" }, - { "id": "member-name-reserved-characters", "type": "normative-statements" } + { "id": "member-name-reserved-characters", "type": "normative-statements" }, + { "id": "member-name-at-members-definition", "type": "normative-statements" }, + { "id": "member-name-at-members-where", "type": "normative-statements" }, + { "id": "member-name-at-members-no-process", "type": "normative-statements" }, + { "id": "member-name-at-members-ignore-for-definitions", "type": "normative-statements" } ] } } @@ -1002,6 +1006,58 @@ layout: null } } }, + { + "id": "member-name-at-members-definition", + "type": "normative-statements", + "attributes": { + "level": "MAY", + "description": "Member names **MAY** also begin with an at sign (U+0040 COMMERCIAL AT, \"@\"). Members named this way are called \"@-Members\"." + }, + "relationships": { + "section": { + "data": { "id": "document-structure", "type": "sections" } + } + } + }, + { + "id": "member-name-at-members-where", + "type": "normative-statements", + "attributes": { + "level": "MAY", + "description": "@-Members **MAY** appear anywhere in a JSON API document." + }, + "relationships": { + "section": { + "data": { "id": "document-structure", "type": "sections" } + } + } + }, + { + "id": "member-name-at-members-no-process", + "type": "normative-statements", + "attributes": { + "level": "MUST", + "description": "JSON API processors **MUST** completely ignore @-Members (i.e. not treat them as JSON API data)." + }, + "relationships": { + "section": { + "data": { "id": "document-structure", "type": "sections" } + } + } + }, + { + "id": "member-name-at-members-ignore-for-definitions", + "type": "normative-statements", + "attributes": { + "level": "MUST", + "description": "Moreover, the existence of @-Members **MUST** be ignored when interpreting all JSON API definitions and processing instructions given outside of the @-Members subsection." + }, + "relationships": { + "section": { + "data": { "id": "document-structure", "type": "sections" } + } + } + }, { "id": "fetch-url-support", "type": "normative-statements",