From 044298c72372ed562dc06e79cd6aff340e4d389c Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Mon, 4 Sep 2023 11:01:13 +1200 Subject: [PATCH 01/10] require `$schema` in schemas --- jsonschema-core.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 607e35fc..b41c777d 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -886,7 +886,7 @@ The `$schema` keyword is both used as a JSON Schema dialect identifier and as the identifier of a resource which is itself a JSON Schema, which describes the set of valid schemas written for this particular dialect. -The value of this keyword MUST be a [IRI](#rfc3987) (containing a scheme) and +The value of this keyword MUST be an [IRI](#rfc3987) (containing a scheme) and this IRI MUST be normalized. The current schema MUST be valid against the meta-schema identified by this IRI. @@ -895,14 +895,22 @@ type `application/schema+json`. The `$schema` keyword SHOULD be used in the document root schema object, and MAY be used in the root schema objects of embedded schema resources. It MUST NOT -appear in non-resource root schema objects. If absent from the document root -schema, the resulting behavior is implementation-defined, but MUST fall within -the following options: - -- Refuse to process the schema, as with unsupported required vocabularies -- Assume a specific, documented meta-schema -- Document the process by which it examines the schema and determines which of a - specific set of meta-schemas to assume +appear in non-resource root schema objects. + +If present in the document root schema, an implementation MUST process the +schema in accordance with the associated dialect. + +If absent from the document root schema, and an `application/schema+json` media +type with a `schema` parameter is available, then the schema MUST be processed +in accordance with the dialect indicated by the `schema` parameter. + +For cases where the `$schema` keyword is absent from the document root, no media +type is provided, and/or the media type has no `schema` parameter, an +implementation MAY offer a mechanism for the user to explicitly set the +dialect. + +If the dialect is not specified through one of these methods, the implementation +MUST refuse to process the schema, as with unsupported required vocabularies. Values for this property are defined elsewhere in this and other documents, and by other parties. From b5c7bfb5767088ecb5763fe0470d7c4caf98a6b1 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 6 Sep 2023 12:05:44 +1200 Subject: [PATCH 02/10] add $schema inheritance details; rework and add that implemnetations are not required to support media type parameter inputs --- jsonschema-core.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index b41c777d..efdf5be1 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -884,7 +884,10 @@ meta-schema features emphasizes flexibility over simplicity. The `$schema` keyword is both used as a JSON Schema dialect identifier and as the identifier of a resource which is itself a JSON Schema, which describes the -set of valid schemas written for this particular dialect. +set of valid schemas written for this particular dialect. The identified dialect +applies to the resource in which it is declared as well as any embedded schema +resources, unless such a resource itself declares a different dialect by +including the `$schema` keyword with a different value. The value of this keyword MUST be an [IRI](#rfc3987) (containing a scheme) and this IRI MUST be normalized. The current schema MUST be valid against the @@ -894,20 +897,21 @@ If this IRI identifies a retrievable resource, that resource SHOULD be of media type `application/schema+json`. The `$schema` keyword SHOULD be used in the document root schema object, and MAY -be used in the root schema objects of embedded schema resources. It MUST NOT -appear in non-resource root schema objects. +be used in the root schema objects of embedded schema resources. When the +keyword appears in non-resource root schema object, the behavior is undefined. -If present in the document root schema, an implementation MUST process the +If present in the resource root schema, an implementation MUST process the schema in accordance with the associated dialect. -If absent from the document root schema, and an `application/schema+json` media -type with a `schema` parameter is available, then the schema MUST be processed -in accordance with the dialect indicated by the `schema` parameter. +If absent from the resource root schema, and no parent dialect is defined, the +schema MUST be processed with the following priorities: -For cases where the `$schema` keyword is absent from the document root, no media -type is provided, and/or the media type has no `schema` parameter, an -implementation MAY offer a mechanism for the user to explicitly set the -dialect. +1. If the implementation accepts media type parameter inputs, and an + `application/schema+json` media type with a `schema` parameter is available, + then the schema MUST be processed in accordance with the dialect indicated by + the `schema` parameter. +2. An implementation MAY offer a mechanism for the user to explicitly set the + dialect. If the dialect is not specified through one of these methods, the implementation MUST refuse to process the schema, as with unsupported required vocabularies. From abed799388f6371d051530438e050cc8f73c9be0 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 8 Sep 2023 11:23:42 +1200 Subject: [PATCH 03/10] create new dialect determination section --- jsonschema-core.md | 44 +++++++++++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index efdf5be1..4571358e 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -862,7 +862,9 @@ The meta-schema serves two purposes: Declaring the vocabularies in use: The `$vocabulary` keyword, when it appears in a meta-schema, declares which vocabularies are available to be used in schemas that refer to that meta-schema. Vocabularies define keyword semantics, as well -as their general syntax. +as their general syntax. By combining various vocabularies, distinct +sets of keywords can be made available for use in a schema. This collection of +vocabularies defines a dialect. Describing valid schema syntax: A schema MUST successfully validate against its meta-schema, which constrains the syntax of the available keywords. The syntax @@ -880,6 +882,30 @@ vocabulary's keywords. Meta-schema authoring is an advanced usage of JSON Schema, so the design of meta-schema features emphasizes flexibility over simplicity. +### Dialect Determination + +When the schema evaluation process begins, the first task is to determine the +dialect used by the schema. To do this, implementations MUST determine the +dialect using the following prioritized steps. + +1. The `$schema` keyword - Implementations MUST process the schema according to + the dialect it declares. +2. `application/schema+json` media type with a `schema` parameter - + Implementations which support media type parameter inputs MUST process the + schema according to the dialect the parameter declares. A media type will + generally only be available if the schema has been retrieved and only applies + to the document root. +3. Parent dialect - An embedded schema resource which does not itself contain a + `$schema` keyword MUST be processed using the same dialect as the schema + which contains it. +4. User configuration - Implementations MAY provide means for the user to + configure the dialect under which a schema should be processed. + +(Note that steps 2 and 3 are mutually exclusive.) + +If the dialect is not specified through one of these methods, the implementation +MUST refuse to process the schema, as with unsupported required vocabularies. + #### The `$schema` Keyword {#keyword-schema} The `$schema` keyword is both used as a JSON Schema dialect identifier and as @@ -900,22 +926,6 @@ The `$schema` keyword SHOULD be used in the document root schema object, and MAY be used in the root schema objects of embedded schema resources. When the keyword appears in non-resource root schema object, the behavior is undefined. -If present in the resource root schema, an implementation MUST process the -schema in accordance with the associated dialect. - -If absent from the resource root schema, and no parent dialect is defined, the -schema MUST be processed with the following priorities: - -1. If the implementation accepts media type parameter inputs, and an - `application/schema+json` media type with a `schema` parameter is available, - then the schema MUST be processed in accordance with the dialect indicated by - the `schema` parameter. -2. An implementation MAY offer a mechanism for the user to explicitly set the - dialect. - -If the dialect is not specified through one of these methods, the implementation -MUST refuse to process the schema, as with unsupported required vocabularies. - Values for this property are defined elsewhere in this and other documents, and by other parties. From 1bbbecf7a8a8d4fab5355827acd7d340d1f5d826 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 8 Sep 2023 11:25:41 +1200 Subject: [PATCH 04/10] fix grammar Co-authored-by: Jason Desrosiers --- jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 4571358e..c9f787a5 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -924,7 +924,7 @@ type `application/schema+json`. The `$schema` keyword SHOULD be used in the document root schema object, and MAY be used in the root schema objects of embedded schema resources. When the -keyword appears in non-resource root schema object, the behavior is undefined. +keyword appears in a non-resource root schema object, the behavior is undefined. Values for this property are defined elsewhere in this and other documents, and by other parties. From 617d358df95b6448966c84514a25d1783cf9081e Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 8 Sep 2023 11:34:28 +1200 Subject: [PATCH 05/10] dialect determination should be a subsection of meta-schemas and vocabs --- jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 4571358e..4c265f3c 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -882,7 +882,7 @@ vocabulary's keywords. Meta-schema authoring is an advanced usage of JSON Schema, so the design of meta-schema features emphasizes flexibility over simplicity. -### Dialect Determination +#### Dialect Determination When the schema evaluation process begins, the first task is to determine the dialect used by the schema. To do this, implementations MUST determine the From 03d78a7cd126d7bd44bc8c920726e2cd13ab87c0 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 8 Sep 2023 11:37:29 +1200 Subject: [PATCH 06/10] use more common language; be more explicit about retrieval source --- jsonschema-core.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index b6bc2d49..7875975b 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -884,17 +884,18 @@ meta-schema features emphasizes flexibility over simplicity. #### Dialect Determination -When the schema evaluation process begins, the first task is to determine the -dialect used by the schema. To do this, implementations MUST determine the -dialect using the following prioritized steps. +When the evaluation encounters a new schema resource (i.e. the lexical scope +changes), the first task is to determine the dialect used by the schema. To do +this, implementations MUST determine the dialect using the following prioritized +steps. 1. The `$schema` keyword - Implementations MUST process the schema according to the dialect it declares. 2. `application/schema+json` media type with a `schema` parameter - Implementations which support media type parameter inputs MUST process the schema according to the dialect the parameter declares. A media type will - generally only be available if the schema has been retrieved and only applies - to the document root. + generally only be available if the schema has been retrieved from an external + source and only applies to the document root. 3. Parent dialect - An embedded schema resource which does not itself contain a `$schema` keyword MUST be processed using the same dialect as the schema which contains it. From 1114dc6e23e10cda5c16496f640ac46cb9f0d7eb Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 8 Sep 2023 11:38:02 +1200 Subject: [PATCH 07/10] remove extra word --- jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 7875975b..6461f00a 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -884,7 +884,7 @@ meta-schema features emphasizes flexibility over simplicity. #### Dialect Determination -When the evaluation encounters a new schema resource (i.e. the lexical scope +When evaluation encounters a new schema resource (i.e. the lexical scope changes), the first task is to determine the dialect used by the schema. To do this, implementations MUST determine the dialect using the following prioritized steps. From 3628e11a9ecc37396c7eb905e438f3c22d00b3e6 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sun, 10 Sep 2023 08:16:35 +1200 Subject: [PATCH 08/10] clarify "against" Co-authored-by: Karen Etheridge --- jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 6461f00a..1bc440c5 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -917,7 +917,7 @@ resources, unless such a resource itself declares a different dialect by including the `$schema` keyword with a different value. The value of this keyword MUST be an [IRI](#rfc3987) (containing a scheme) and -this IRI MUST be normalized. The current schema MUST be valid against the +this IRI MUST be normalized. The current schema MUST be valid when evaluated against the meta-schema identified by this IRI. If this IRI identifies a retrievable resource, that resource SHOULD be of media From a30157926a88056b782a454ad956a5b03bbc3daf Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Mon, 11 Sep 2023 10:40:44 +1200 Subject: [PATCH 09/10] remove redundant `$schema` validation statement --- jsonschema-core.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 6461f00a..9ced4c79 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -917,8 +917,7 @@ resources, unless such a resource itself declares a different dialect by including the `$schema` keyword with a different value. The value of this keyword MUST be an [IRI](#rfc3987) (containing a scheme) and -this IRI MUST be normalized. The current schema MUST be valid against the -meta-schema identified by this IRI. +this IRI MUST be normalized. If this IRI identifies a retrievable resource, that resource SHOULD be of media type `application/schema+json`. From 6645f38108854c6e4e29a0159316a42a42f218bd Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Mon, 11 Sep 2023 10:47:53 +1200 Subject: [PATCH 10/10] add text about schemas contained in non-schema documents --- jsonschema-core.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 9ced4c79..42b6bf71 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -885,8 +885,8 @@ meta-schema features emphasizes flexibility over simplicity. #### Dialect Determination When evaluation encounters a new schema resource (i.e. the lexical scope -changes), the first task is to determine the dialect used by the schema. To do -this, implementations MUST determine the dialect using the following prioritized +changes), the first task is to determine the dialect used by the schema. +Implementations MUST determine the dialect using the following prioritized steps. 1. The `$schema` keyword - Implementations MUST process the schema according to @@ -898,7 +898,9 @@ steps. source and only applies to the document root. 3. Parent dialect - An embedded schema resource which does not itself contain a `$schema` keyword MUST be processed using the same dialect as the schema - which contains it. + which contains it. If the schema is embedded in a non-schema document, the + semantics for determining the dialect MAY be determined by any specification + which applies to that document. 4. User configuration - Implementations MAY provide means for the user to configure the dialect under which a schema should be processed.