From aad514d5e18b11cc3adb6309e164d46dd3f4e5e6 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 15 Nov 2016 15:39:43 -0800 Subject: [PATCH] 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. --- jsonschema-core.xml | 50 ++++++++++++++++++++++++++++----------------- schema.json | 5 +++++ 2 files changed, 36 insertions(+), 19 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 0000eef2..b47f8823 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -340,23 +340,23 @@ -
+
- 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. If present, the value for this keyword MUST be a string, and MUST represent a valid URI-reference. This value SHOULD be normalized, and SHOULD NOT be an empty fragment <#> or an empty string <>. - 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). 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 ("."). @@ -367,18 +367,18 @@ 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". - 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". @@ -419,14 +419,14 @@ - When an implementation encounters the <#/definitions/single> schema, it resolves the "id" URI reference + When an implementation encounters the <#/definitions/single> schema, it resolves the "$id" URI reference against the current base URI to form <http://example.net/root.json#item>. @@ -451,7 +451,7 @@ 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. @@ -459,6 +459,18 @@ When multiple schemas try to identify with the same URI, validators SHOULD raise an error condition.
+
+ "id" is likely to be deleted from the spec before RFC. + + 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. + + + The behavior when "$id" and "id" are present with different values is undefined. + Implementations MAY issue a warning or error for such schemas. + +
@@ -580,7 +592,7 @@ User-Agent: so-cool-json-schema/1.0.2 curl/7.43.0 Validators MUST NOT fall into an infinite loop. - 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". 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 index 3b9019c8..8cf49486 100644 --- a/schema.json +++ b/schema.json @@ -37,7 +37,12 @@ }, "type": "object", "properties": { + "$id": { + "type": "string", + "format": "uriref" + }, "id": { + "description": "This keyword has been deprecated in favor of \"$id\"", "type": "string", "format": "uriref" },