Skip to content

Commit aaf9afd

Browse files
committed
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.
1 parent cd171f5 commit aaf9afd

File tree

2 files changed

+36
-19
lines changed

2 files changed

+36
-19
lines changed

jsonschema-core.xml

+31-19
Original file line numberDiff line numberDiff line change
@@ -347,23 +347,23 @@
347347
</t>
348348
</section>
349349

350-
<section title='The "id" keyword'>
350+
<section title='The "$id" keyword'>
351351
<t>
352-
The "id" keyword defines a URI for the schema,
352+
The "$id" keyword defines a URI for the schema,
353353
and the base URI that other URI references within the schema are resolved against.
354-
The "id" keyword itself is resolved against the base URI that the object as a whole appears in.
354+
The "$id" keyword itself is resolved against the base URI that the object as a whole appears in.
355355
</t>
356356
<t>
357357
If present, the value for this keyword MUST be a string, and MUST represent a valid <xref target="RFC3986">URI-reference</xref>.
358358
This value SHOULD be normalized, and SHOULD NOT be an empty fragment &lt;#&gt; or an empty string &lt;&gt;.
359359
</t>
360360
<t>
361-
The root schema of a JSON Schema document SHOULD contain an "id" keyword with an absolute-URI (containing a scheme, but no fragment).
361+
The root schema of a JSON Schema document SHOULD contain an "$id" keyword with an absolute-URI (containing a scheme, but no fragment).
362362
</t>
363363
<t>
364364
To name subschemas in a JSON Schema document,
365-
subschemas can use "id" to give themselves a document-local identifier.
366-
This form of "id" keyword MUST begin with a hash ("#") to identify it as a fragment URI reference,
365+
subschemas can use "$id" to give themselves a document-local identifier.
366+
This form of "$id" keyword MUST begin with a hash ("#") to identify it as a fragment URI reference,
367367
followed by a letter ([A-Za-z]), followed by any number of
368368
letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), or periods (".").
369369
<!-- This restriction is the same one defined by XML -->
@@ -374,18 +374,18 @@
374374
<artwork>
375375
<![CDATA[
376376
{
377-
"id": "http://example.com/root.json",
377+
"$id": "http://example.com/root.json",
378378
"definitions": {
379-
"A": { "id": "#foo" },
379+
"A": { "$id": "#foo" },
380380
"B": {
381-
"id": "other.json",
381+
"$id": "other.json",
382382
"definitions": {
383-
"X": { "id": "#bar" },
384-
"Y": { "id": "t/inner.json" }
383+
"X": { "$id": "#bar" },
384+
"Y": { "$id": "t/inner.json" }
385385
}
386386
},
387387
"C": {
388-
"id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f"
388+
"$id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f"
389389
}
390390
}
391391
}
@@ -411,10 +411,10 @@
411411
<section title="Internal references">
412412
<t>
413413
Schemas can be identified by any URI that has been given to them, including a JSON Pointer or
414-
their URI given directly by "id".
414+
their URI given directly by "$id".
415415
</t>
416416
<t>
417-
Tools SHOULD take note of the URIs that schemas, including subschemas, provide for themselves using "id".
417+
Tools SHOULD take note of the URIs that schemas, including subschemas, provide for themselves using "$id".
418418
This is known as "Internal referencing".
419419
</t>
420420

@@ -426,14 +426,14 @@
426426
<artwork>
427427
<![CDATA[
428428
{
429-
"id": "http://example.net/root.json",
429+
"$id": "http://example.net/root.json",
430430
"items": {
431431
"type": "array",
432432
"items": { "$ref": "#item" }
433433
},
434434
"definitions": {
435435
"single": {
436-
"id": "#item",
436+
"$id": "#item",
437437
"type": "integer"
438438
},
439439
}
@@ -442,7 +442,7 @@
442442
</artwork>
443443
</figure>
444444
<t>
445-
When an implementation encounters the &lt;#/definitions/single&gt; schema, it resolves the "id" URI reference
445+
When an implementation encounters the &lt;#/definitions/single&gt; schema, it resolves the "$id" URI reference
446446
against the current base URI to form &lt;http://example.net/root.json#item&gt;.
447447
</t>
448448
<t>
@@ -458,14 +458,26 @@
458458
</t>
459459
<t>
460460
Implementations SHOULD be able to associate arbitrary URIs with an arbitrary schema and/or
461-
automatically associate a schema's "id"-given URI, depending on the trust that the the validator
461+
automatically associate a schema's "$id"-given URI, depending on the trust that the the validator
462462
has in the schema.
463463
</t>
464464
<t>
465465
A schema MAY (and likely will) have multiple URIs, but there is no way for a URI to identify more than one schema.
466466
When multiple schemas try to identify with the same URI, validators SHOULD raise an error condition.
467467
</t>
468468
</section>
469+
<section title='Compatibility with "id"'>
470+
<t><cref>"id" is likely to be deleted from the spec before RFC.</cref></t>
471+
<t>
472+
Implementations MAY support "id" as a synonym for "$id" to aid
473+
in migrating schemas from older drafts, however schema authors
474+
SHOULD NOT make use of "id" and MUST NOT assume it is supported.
475+
</t>
476+
<t>
477+
The behavior when "$id" and "id" are present with different values is undefined.
478+
Implementations MAY issue a warning or error for such schemas.
479+
</t>
480+
</section>
469481
</section>
470482
</section>
471483

@@ -587,7 +599,7 @@ User-Agent: so-cool-json-schema/1.0.2 curl/7.43.0
587599
Validators MUST NOT fall into an infinite loop.
588600
</t>
589601
<t>
590-
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".
602+
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".
591603
</t>
592604
<t>
593605
Individual JSON Schema vocabularies are liable to also have their own security considerations. Consult the respective specifications for more information.

schema.json

+5
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,12 @@
3737
},
3838
"type": ["object", "boolean"],
3939
"properties": {
40+
"$id": {
41+
"type": "string",
42+
"format": "uriref"
43+
},
4044
"id": {
45+
"description": "This keyword has been deprecated in favor of \"$id\"",
4146
"type": "string",
4247
"format": "uriref"
4348
},

0 commit comments

Comments
 (0)