diff --git a/applicator.json b/applicator.json new file mode 100644 index 00000000..de770dd2 --- /dev/null +++ b/applicator.json @@ -0,0 +1,61 @@ +{ + "$schema": "http://json-schema.org/draft-08/schema#", + "$id": "https://json-schema.org/draft-08/applicator", + "$recursiveAnchor": true, + "$vocabulary": { + "https://json-schema.org/draft-08/vocabularies/core": true, + "https://json-schema.org/draft-08/vocabularies/applicator": true + }, + + "title": "Applicator vocabulary meta-schema", + "$defs": { + "schemaArray": { + "type": "array", + "minItems": 1, + "items": { "$recursiveRef": "#" } + } + }, + "properties": { + "additionalItems": { "$recursiveRef": "#" }, + "unevaluatedItems": { "$recursiveRef": "#" }, + "items": { + "anyOf": [ + { "$recursiveRef": "#" }, + { "$ref": "#/$defs/schemaArray" } + ] + }, + "contains": { "$recursiveRef": "#" }, + "additionalProperties": { "$recursiveRef": "#" }, + "unevaluatedProperties": { + "type": "object", + "additionalProperties": { + "$recursiveRef": "#" + } + }, + "properties": { + "type": "object", + "additionalProperties": { "$recursiveRef": "#" }, + "default": {} + }, + "patternProperties": { + "type": "object", + "additionalProperties": { "$recursiveRef": "#" }, + "propertyNames": { "format": "regex" }, + "default": {} + }, + "dependentSchemas": { + "type": "object", + "additionalProperties": { + "$recursiveRef": "#" + } + }, + "propertyNames": { "$recursiveRef": "#" }, + "if": { "$recursiveRef": "#" }, + "then": { "$recursiveRef": "#" }, + "else": { "$recursiveRef": "#" }, + "allOf": { "$ref": "#/$defs/schemaArray" }, + "anyOf": { "$ref": "#/$defs/schemaArray" }, + "oneOf": { "$ref": "#/$defs/schemaArray" }, + "not": { "$recursiveRef": "#" } + } +} diff --git a/core.json b/core.json new file mode 100644 index 00000000..d845b3dd --- /dev/null +++ b/core.json @@ -0,0 +1,52 @@ +{ + "$schema": "http://json-schema.org/draft-08/schema#", + "$id": "https://json-schema.org/draft-08/core", + "$recursiveAnchor": true, + "$vocabulary": { + "https://json-schema.org/draft-08/vocabularies/core": true + }, + + "title": "Core vocabulary meta-schema", + "type": ["object", "boolean"], + "properties": { + "$id": { + "type": "string", + "format": "uri-reference" + }, + "$schema": { + "type": "string", + "format": "uri" + }, + "$ref": { + "type": "string", + "format": "uri-reference" + }, + "$recursiveRef": { + "type": "string", + "format": "uri-reference" + }, + "$recursiveAnchor": { + "type": "boolean", + "const": true, + "default": false + }, + "$vocabulary": { + "type": "object", + "propertyNames": { + "type": "string", + "format": "uri" + }, + "additionalProperties": { + "type": "boolean" + } + }, + "$comment": { + "type": "string" + }, + "$defs": { + "type": "object", + "additionalProperties": { "$recursiveRef": "#" }, + "default": {} + } + } +} diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 637e587d..b4e50e9b 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -790,7 +790,7 @@ A schema that itself describes a schema is called a meta-schema. Meta-schemas are used to validate JSON Schemas and specify which vocabulary - it is using. + they are using. Authors of extensions to JSON Schema are encouraged to write their own @@ -807,49 +807,306 @@ -
- +
- The "$schema" keyword is both used as a JSON Schema version identifier and the - location of a resource which is itself a JSON Schema, which describes any schema - written for this particular version. + Two concepts, meta-schemas and vocabularies, are used to inform an implementation + how to interpret a schema. A schema S declares its meta-schema M with the "$schema" + keyword, and meta-schemas declare vocabularies with the "$vocabulary" keyword. + The vocabularies declared in M are those that are expected to be used in S. + The meta-schema M may itself use a different set of vocabularies, which are + declared in its own meta-schema, M'. - The value of this keyword MUST be a URI - (containing a scheme) and this URI MUST be normalized. - The current schema MUST be valid against the meta-schema identified by this URI. + The role of the meta-schema is to constrain the structure of conforming schemas, + as well as simplify the process of composing multiple vocabularies into a usable + feature set. Schema authoring is expected to be a common activity, so + schema authors need only understand how to reference a single meta-schema. - If this URI identifies a retrievable resource, that resource SHOULD be of - media type "application/schema+json". + Meta-schema authoring is an advanced usage of JSON Schema, so the design of + meta-schema features emphasizes flexibility over simplicity. - The "$schema" keyword SHOULD be used in a root schema. - It MUST NOT appear in subschemas. + The role of a vocabulary is to declare which keywords (including sub-keywords + such as those in JSON Hyper-Schema's Link Description Object) are in use, + and with which semantics. The semantics are indicated by the document + that publicizes the vocabulary URI. At this time, there is no machine-readable + description of keywords other than validation rules, which appear in the + meta-schema. - - Using multiple "$schema" keywords in the same document would imply that the - vocabulary and therefore behavior can change within a document. This would - necessitate resolving a number of implementation concerns that have not yet - been clearly defined. So, while the pattern of using "$schema" only in root - schemas is likely to remain the best practice for schema authoring, - implementation behavior is subject to be revised or liberalized in - future drafts. - - - - - Values for this property are defined in other documents and by other parties. - JSON Schema implementations SHOULD implement support for current and previous - published drafts of JSON Schema vocabularies as deemed reasonable. + Meta-schemas are separate from vocabularies to allow for the same sets of + vocabularies to be combined in different ways, and for meta-schema authors + to impose additional constraints such as forbidding certain keywords, or + performing unusually strict syntactical validation, as might be done + during a development and testing cycle. +
+ + The "$schema" keyword is both used as a JSON Schema feature set identifier and + the location of a resource which is itself a JSON Schema, which describes any + schema written for this particular feature set. + + + The value of this keyword MUST be a URI + (containing a scheme) and this URI MUST be normalized. + The current schema MUST be valid against the meta-schema identified by this URI. + + + If this URI identifies a retrievable resource, that resource SHOULD be of + media type "application/schema+json". + + + The "$schema" keyword SHOULD be used in a root schema. + It MUST NOT appear in subschemas. + + + + Using multiple "$schema" keywords in the same document would imply that the + feature set and therefore behavior can change within a document. This would + necessitate resolving a number of implementation concerns that have not yet + been clearly defined. So, while the pattern of using "$schema" only in root + schemas is likely to remain the best practice for schema authoring, + implementation behavior is subject to be revised or liberalized in + future drafts. + + + + + Values for this property are defined elsewhere in this and other documents, + and by other parties. + +
+
+ + The "$vocabulary" keyword, which appears in a meta-schema, identifies + what sets of keywords are expected to be used in schemas described + by that meta-schema, and with what semantics. This is conceptually + analogous to how most other keywords used in meta-schemas describe + the syntax of keywords used in schemas described by that meta-schema. + + + The value of this keyword MUST be an object. The property names in the + object MUST be URIs (containing a scheme) and this URI MUST be normalized. + Each URI that appears as a property name identifies a specific set of + keywords and their semantics. + + + The URI MAY be a URL, but the nature of the retrievable resources is + currently undefined, and reserved for future use. Vocabulary authors + SHOULD NOT serve a document at that URL. A server MAY respond with + the relevant protocol's successful "no content" message, such as + an HTTP 204 status. + + Vocabulary documents may be added shortly, or in the next draft. + For now, identifying the keyword set is deemed sufficient as that, + along with meta-schema validation, is how the current "vocabularies" + work today. + + + + The values of the object properties MUST be booleans. + If the value is true, then implementations that do not recognize + the vocabulary MUST refuse to process any schemas that declare + this meta-schema with "$schema". If the value is false, implementations + that do not recognize the vocabulary MAY choose to proceed with processing + such schemas. + + + When processing a schema that uses unrecognized vocabularies, keywords + declared by those vocabularies are treated like any other unrecognized + keyword, and ignored. + + + The "$vocabulary" keyword SHOULD be used in the root schema of any schema + document intended for use as a meta-schema. It MUST NOT appear in subschemas. + + + The "$vocabulary" keyword MUST be ignored in schema documents that + are not being processed as a meta-schema. This allows validating + a meta-schema M against its own meta-schema M' without requiring + the validator to understand the vocabularies declared by M. + + + Note that the processing restrictions on "$vocabulary" mean that + meta-schemas that reference other meta-schemas using "$ref" or + similar keywords do not automatically inherit the vocabulary + declarations of those other meta-schemas. All such declarations + must be repeated in the root of each schema document intended + for use as a meta-schema. This is demonstrated in + the example meta-schema. + + + If "$vocabulary" is absent, an implementation MAY determine + behavior based on the meta-schema if it is recognized from the + URI value of the referring schema's "$schema" keyword. + If the meta-schema, as referenced by the schema, is not recognized, + then implementations MUST assume the use of the core vocabulary, + and SHOULD assume the use of all vocabularies in this + specification and the companion Validation specification. + +
+
+ + Implementations MUST recognize a schema as a meta-schema if it + is being examined because it was identified as such by another + schema's "$schema" keyword. This means that a single schema + document might sometimes be considered a regular schema, and + other times be considered a meta-schema. + + + In the case of examining a schema which is its own meta-schema, + when an implementation begins processing it as a regular schema, + it is processed under those rules. However, when loaded a second + time as a result of checking its own "$schema" value, it is treated + as a meta-schema. So the same document is processed both ways in + the course of one session. + + + Implementations MAY allow a schema to be passed as a meta-schema, + for implementation-specific purposes, such as pre-loading a commonly + used meta-schema and checking its vocabulary support requirements + up front. Meta-schema authors MUST NOT expect such features to be + interoperable across implementations. + +
+
+ + Meta-schema authors SHOULD NOT use "$vocabulary" to combine multiple + vocabularies that define conflicting syntax or semantics for the same + keyword. As semantic conflicts are not generally detectable through + schema validation, implementations are not expected to detect such + conflicts. If conflicting vocabularies are declared, the resulting + behavior is undefined. + + + Vocabulary authors SHOULD provide a meta-schema that validates the + expected usage of the vocabulary's keywords. Such meta-schemas + SHOULD NOT forbid additional keywords, and MUST NOT forbid + the "$id", "$schema", or "$vocabulary" keywords in the root schema. + + + It is RECOMMENDED that meta-schema authors reference each vocabulary's + meta-schema using the "allOf" keyword, + although other mechanisms for constructing the meta-schema may be + appropriate for certain use cases. + + + Meta-schemas MAY impose additional constraints, including describing + keywords not present in any vocabulary, beyond what the meta-schemas + associated with the declared vocabularies describe. This allows for + restricting usage to a subset of a vocabulary, and for validating + locally defined keywords not intended for re-use. + + + However, meta-schemas SHOULD NOT contradict any vocabularies that + they declare, such as by requiring a different JSON type than + the vocabulary expects. The resulting behavior is undefined. + + + Meta-schemas intended for local use, with no need to test for + vocabulary support in arbitrary implementations, can safely omit + "$vocabulary" entirely. + +
+
+ + Keywords declared in in this specification that begin with "$" make up + the JSON Schema Core vocabulary. These keywords are either required in + order process any schema or meta-schema, including those split across + multiple documents, or exist to reserve keywords for purposes that + require guaranteed interoperability. + + + The Core vocabulary MUST be considered mandatory at all times, in order + to bootstrap the processing of further vocabularies. Meta-schemas + that use "$vocabulary" MUST explicitly list the Core vocabulary, + which MUST have a value of true indicating that it is required. + + + The behavior of a false value for this vocabulary (and only this + vocabulary) is undefined, as is the behavior when "$vocabulary" + is present but the Core vocabulary is not included. However, it + is RECOMMENDED that implementations detect these cases and raise + an error when they occur. + + + Meta-schemas that do not use "$vocabulary" MUST be considered to + require the Core vocabulary as if its URI were present with a value of true. + + + The current URI for the Core vocabulary is: + . + + + The current URI for the corresponding meta-schema is: + . + +
+
+
+ + This meta-schema explicitly declares both the Core and Applicator + vocabularies, and combines their meta-schemas with an "allOf". + It additionally restricts the usage of the Applicator vocabulary + by forbidding the keyword prefixed with "unevaluated". It also + describes a keyword, "localKeyword", that is not part of either + vocabulary. Note that it is its own meta-schema, + as it relies on both the Core vocabulary (as all schemas do) + and the Applicator vocabulary (for "allOf"). + + + + + + As shown above, even though each of the referenced standard + meta-schemas declares its corresponding vocabulary, this new + meta-schema must re-declare them for itself. It would be + valid to leave the core vocabulary out of the "$vocabulary" keyword, + but it needs to be referenced through the "allOf" keyword in order + for its terms to be validated. There is no special case for + validation of core keywords. + +
+ + The standard meta-schemas that combine all vocabularies defined by + the Core and Validation specification, and that combine all vocabularies + defined by those specifications as well as the Hyper-Schema specification, + demonstrate additional complex combinations. These URIs for these + meta-schemas may be found in the Validation and Hyper-Schema specifications, + respectively. + +
@@ -1615,6 +1872,18 @@ This section defines a vocabulary of applicator keywords that are RECOMMENDED for use as the basis of other vocabularies. + + The current URI for this vocabulary, known as the Applicator vocabulary, is: + . + + + The current URI for the corresponding meta-schema is: + . + + + Meta-schemas that do not use "$vocabulary" SHOULD be considered to + require this vocabulary as if its URI were present with a value of true. +
Schema keywords typically operate independently, without @@ -1659,7 +1928,7 @@ keyword to be applied to an instance location with different values. Annotation keywords define their own rules for combining such values. -
+
This keyword's value MUST be a non-empty array. Each item of the array MUST be a valid JSON Schema. @@ -2155,7 +2424,7 @@ Link: ; rel="describedby" When using the media type application/schema+json, the "schema" parameter - MAY be supplied, If supplied, it SHOULD contain the same URI as identified + MAY be supplied. If supplied, it SHOULD contain the same URI as identified by the "$schema" keyword, and MAY contain additional URIs. The "$schema" URI MUST be considered the schema's canonical meta-schema, regardless of the presence of alternative or additional meta-schemas as a media type @@ -2295,7 +2564,7 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 Type name: application Subtype name: schema+json - >Required parameters: N/A + Required parameters: N/A Optional parameters: diff --git a/schema.json b/schema.json index 85cbe9b3..281912c6 100644 --- a/schema.json +++ b/schema.json @@ -2,8 +2,9 @@ "$schema": "http://json-schema.org/draft-08/schema#", "$id": "http://json-schema.org/draft-08/schema#", "$recursiveAnchor": true, + "$recursiveRef": "core", - "title": "Core schema meta-schema", + "title": "Core and Validation specifications meta-schema", "$defs": { "schemaArray": { "type": "array", @@ -38,34 +39,6 @@ }, "type": ["object", "boolean"], "properties": { - "$id": { - "type": "string", - "format": "uri-reference" - }, - "$schema": { - "type": "string", - "format": "uri" - }, - "$ref": { - "type": "string", - "format": "uri-reference" - }, - "$recursiveRef": { - "type": "string", - "format": "uri-reference" - }, - "$recursiveAnchor": { - "const": true, - "default": false - }, - "$comment": { - "type": "string" - }, - "$defs": { - "type": "object", - "additionalProperties": { "$recursiveRef": "#" }, - "default": {} - }, "definitions": { "$comment": "While no longer an official keyword as it is replaced by $defs, this keyword is retained in the meta-schema to prevent incompatible extensions as it remains in common use.", "type": "object",