Change "id" to "$id", retain "id" for compatibility.

This addresses issue #20. "$id" matches "$schema" and "$ref", establishing a clear naming pattern for all keywords defined in the core specification. This also reduces confusion in the very common case where objects described by the schema have an "id" property. The current plan is to continue to allow for "id" until a migration tool can be provided.
json-schema-org · Dec 28, 2016 · aaf9afd · aaf9afd
1 parent cd171f5
commit aaf9afd
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 19 deletions.
diff --git a/jsonschema-core.xml b/jsonschema-core.xml
@@ -347,23 +347,23 @@
                 </t>
             </section>
 
-            <section title='The "id" keyword'>
+            <section title='The "$id" keyword'>
                 <t>
-                    The "id" keyword defines a URI for the schema,
+                    The "$id" keyword defines a URI for the schema,
                     and the base URI that other URI references within the schema are resolved against.
-                    The "id" keyword itself is resolved against the base URI that the object as a whole appears in.
+                    The "$id" keyword itself is resolved against the base URI that the object as a whole appears in.
                 </t>
                 <t>
                     If present, the value for this keyword MUST be a string, and MUST represent a valid <xref target="RFC3986">URI-reference</xref>.
                     This value SHOULD be normalized, and SHOULD NOT be an empty fragment &lt;#&gt; or an empty string &lt;&gt;.
                 </t>
                 <t>
-                    The root schema of a JSON Schema document SHOULD contain an "id" keyword with an absolute-URI (containing a scheme, but no fragment).
+                    The root schema of a JSON Schema document SHOULD contain an "$id" keyword with an absolute-URI (containing a scheme, but no fragment).
                 </t>
                 <t>
                     To name subschemas in a JSON Schema document,
-                    subschemas can use "id" to give themselves a document-local identifier.
-                    This form of "id" keyword MUST begin with a hash ("#") to identify it as a fragment URI reference,
+                    subschemas can use "$id" to give themselves a document-local identifier.
+                    This form of "$id" keyword MUST begin with a hash ("#") to identify it as a fragment URI reference,
                     followed by a letter ([A-Za-z]), followed by any number of
                     letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), or periods (".").
                     <!-- This restriction is the same one defined by XML -->
@@ -374,18 +374,18 @@
                         <artwork>
 <![CDATA[
 {
-    "id": "http://example.com/root.json",
+    "$id": "http://example.com/root.json",
     "definitions": {
-        "A": { "id": "#foo" },
+        "A": { "$id": "#foo" },
         "B": {
-            "id": "other.json",
+            "$id": "other.json",
             "definitions": {
-                "X": { "id": "#bar" },
-                "Y": { "id": "t/inner.json" }
+                "X": { "$id": "#bar" },
+                "Y": { "$id": "t/inner.json" }
             }
         },
         "C": {
-            "id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f"
+            "$id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f"
         }
     }
 }
@@ -411,10 +411,10 @@
                 <section title="Internal references">
                     <t>
                         Schemas can be identified by any URI that has been given to them, including a JSON Pointer or
-                        their URI given directly by "id".
+                        their URI given directly by "$id".
                     </t>
                     <t>
-                        Tools SHOULD take note of the URIs that schemas, including subschemas, provide for themselves using "id".
+                        Tools SHOULD take note of the URIs that schemas, including subschemas, provide for themselves using "$id".
                         This is known as "Internal referencing".
                     </t>
 
@@ -426,14 +426,14 @@
                         <artwork>
 <![CDATA[
 {
-    "id": "http://example.net/root.json",
+    "$id": "http://example.net/root.json",
     "items": {
         "type": "array",
         "items": { "$ref": "#item" }
     },
     "definitions": {
         "single": {
-            "id": "#item",
+            "$id": "#item",
             "type": "integer"
         },
     }
@@ -442,7 +442,7 @@
                         </artwork>
                     </figure>
                     <t>
-                        When an implementation encounters the &lt;#/definitions/single&gt; schema, it resolves the "id" URI reference
+                        When an implementation encounters the &lt;#/definitions/single&gt; schema, it resolves the "$id" URI reference
                         against the current base URI to form &lt;http://example.net/root.json#item&gt;.
                     </t>
                     <t>
@@ -458,14 +458,26 @@
                     </t>
                     <t>
                         Implementations SHOULD be able to associate arbitrary URIs with an arbitrary schema and/or
-                        automatically associate a schema's "id"-given URI, depending on the trust that the the validator
+                        automatically associate a schema's "$id"-given URI, depending on the trust that the the validator
                         has in the schema.
                     </t>
                     <t>
                         A schema MAY (and likely will) have multiple URIs, but there is no way for a URI to identify more than one schema.
                         When multiple schemas try to identify with the same URI, validators SHOULD raise an error condition.
                     </t>
                 </section>
+                <section title='Compatibility with "id"'>
+                    <t><cref>"id" is likely to be deleted from the spec before RFC.</cref></t>
+                    <t>
+                        Implementations MAY support "id" as a synonym for "$id" to aid
+                        in migrating schemas from older drafts, however schema authors
+                        SHOULD NOT make use of "id" and MUST NOT assume it is supported.
+                    </t>
+                    <t>
+                        The behavior when "$id" and "id" are present with different values is undefined.
+                        Implementations MAY issue a warning or error for such schemas.
+                    </t>
+                </section>
             </section>
         </section>
 
@@ -587,7 +599,7 @@ User-Agent: so-cool-json-schema/1.0.2 curl/7.43.0
                 Validators MUST NOT fall into an infinite loop.
             </t>
             <t>
-                Servers need to take care that malicious parties can't change the functionality of existing schemas by uploading a schema with an pre-existing or very similar "id".
+                Servers need to take care that malicious parties can't change the functionality of existing schemas by uploading a schema with an pre-existing or very similar "$id".
             </t>
             <t>
                 Individual JSON Schema vocabularies are liable to also have their own security considerations. Consult the respective specifications for more information.

diff --git a/schema.json b/schema.json
@@ -37,7 +37,12 @@
     },
     "type": ["object", "boolean"],
     "properties": {
+        "$id": {
+            "type": "string",
+            "format": "uriref"
+        },
         "id": {
+            "description": "This keyword has been deprecated in favor of \"$id\"",
             "type": "string",
             "format": "uriref"
         },