JSON Schema: Relax rules to cover all cases

Closes json-api#867 and json-api#851.
ethanresnick · Sep 13, 2015 · d5af3e6 · d5af3e6
1 parent 63e4629
commit d5af3e6
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 27 deletions.
diff --git a/faq/index.md b/faq/index.md
@@ -80,14 +80,23 @@ don’t can be easily [worked around](/recommendations/#patchless-clients).
 
 ## Is there a JSON Schema describing JSON API? <a href="#is-there-a-json-schema-describing-json-api" id="is-there-a-json-schema-describing-json-api" class="headerlink"></a>
 
-Yes, you can find the JSON Schema definition at
-[http://jsonapi.org/schema](http://jsonapi.org/schema). This schema is as
-restrictive as possible, but has flexibility to be extended within your
-documentation. Validation will not yield false negatives, but could yield false
-positives for the sake of flexibility.
-
-You can find more information about the JSON Schema format at
-[http://json-schema.org](http://json-schema.org).
+Yes, you can find the [JSON Schema](http://json-schema.org) definition at
+[http://jsonapi.org/schema](http://jsonapi.org/schema). However, **don’t use
+this schema as your only source of validation**. Some JSON API documents it
+declares valid are only valid in limited situations.
+
+In particular, this schema allows resource objects that don’t contain an `id`,
+because no `id` is necessary on the request to create a resource. However, for
+all other cases, an `id` is required, so you have to check that it’s provided.
+
+Also, this schema allows documents that have unknown JSON keys in
+specification-defined objects (relationship objects, link objects, etc.).
+These documents are allowed because clients or servers that are _reading_
+them must accept them, and simply ignore the unknown keys. However, if you’re
+testing whether your implementation properly _generates_ JSON API documents,
+you must ensure that it does not output any extra keys. (By having recipients
+ignore unknown keys, and senders not include them, JSON API is able to define
+new keys later without breaking existing implementations.)
 
 ## Why are resource collections returned as arrays instead of sets keyed by ID? <a href="#resource-collections-returned-as-arrays" id="resource-collections-returned-as-arrays" class="headerlink"></a>
 

diff --git a/schema b/schema
@@ -13,7 +13,7 @@
       "$ref": "#/definitions/info"
     }
   ],
-  
+
   "definitions": {
     "success": {
       "type": "object",
@@ -50,7 +50,7 @@
           "$ref": "#/definitions/jsonapi"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "failure": {
       "type": "object",
@@ -72,7 +72,7 @@
           "$ref": "#/definitions/jsonapi"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "info": {
       "type": "object",
@@ -90,9 +90,9 @@
           "$ref": "#/definitions/jsonapi"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
-    
+
     "meta": {
       "description": "Non-standard meta-information that can not be represented as an attribute or relationship.",
       "type": "object",
@@ -115,11 +115,10 @@
       ]
     },
     "resource": {
-      "description": "\"Resource objects\" appear in a JSON API document to represent resources.",
+      "description": "\"Resource objects\" appear in a JSON API document to represent resources. Ids are required, except on the creation request.",
       "type": "object",
       "required": [
-        "type",
-        "id"
+        "type"
       ],
       "properties": {
         "type": {
@@ -141,9 +140,9 @@
           "$ref": "#/definitions/meta"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
-    
+
     "links": {
       "description": "A resource object **MAY** contain references to other resource objects (\"relationships\"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.",
       "type": "object",
@@ -181,7 +180,8 @@
             "meta": {
               "$ref": "#/definitions/meta"
             }
-          }
+          },
+          "additionalProperties": true
         }
       ]
     },
@@ -221,7 +221,7 @@
               "$ref": "#/definitions/meta"
             }
           },
-          "additionalProperties": false
+          "additionalProperties": true
         }
       },
       "additionalProperties": false
@@ -267,7 +267,7 @@
           "$ref": "#/definitions/meta"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "pagination": {
       "type": "object",
@@ -300,9 +300,10 @@
             { "type": "null" }
           ]
         }
-      }
+      },
+      additionalProperties: true
     },
-    
+
     "jsonapi": {
       "description": "An object describing the server's implementation",
       "type": "object",
@@ -314,9 +315,9 @@
           "$ref": "#/definitions/meta"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
-    
+
     "error": {
       "type": "object",
       "properties": {
@@ -360,7 +361,7 @@
           "$ref": "#/definitions/meta"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     }
   }
-}
+}