From c53747f8ddc4df590d35bf81fbd0f7781e5aa577 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sat, 9 Nov 2024 11:43:34 +1300 Subject: [PATCH 01/13] clean up $dyanmic* --- specs/jsonschema-core.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 350e45ba..10031a27 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -1012,21 +1012,19 @@ resolution until runtime, at which point it is resolved each time it is encountered while evaluating an instance. Together with `$dynamicAnchor`, `$dynamicRef` implements a cooperative extension -mechanism that is primarily useful with recursive schemas (schemas that -reference themselves). The extension point is defined with `$dynamicAnchor` and -only exhibits runtime dynamic behavior when referenced with `$dynamicRef`. +mechanism that is primarily useful to extend recursive schemas. The extension +point is defined with `$dynamicAnchor` and only exhibits runtime dynamic +behavior when referenced with `$dynamicRef`. -The value of the `$dynamicRef` property MUST be a string which is a -IRI reference that contains a valid [plain name fragment](#anchors). Resolved -against the current IRI base, it indicates the schema resource used as the -starting point for runtime resolution. This initial resolution is safe to -perform on schema load. +The value of the `$dynamicRef` property MUST be a valid +[plain name fragment](#anchors). -The schema to apply is the outermost schema resource in the [dynamic -scope](#scopes) that defines a `$dynamicAnchor` that matches the plain name -fragment in the initially resolved IRI. +Resolution of `$dynamicRef` begins by identifying the the outermost schema +resource in the [dynamic scope](#scopes) which defines a matching +`$dynamicAnchor`. The schema to apply is the subschema of this resource which +contains the matching `$dynamicAnchor`. -For a full example using these keyword, see {{recursive-example}}.[^6] +For a full example using these keywords, see {{recursive-example}}.[^6] [^6]: The difference between the hyper-schema meta-schema in pre-2019 drafts and an this draft dramatically demonstrates the utility of these keywords. From b0ece6ea3b964eb343c7075feb7369afeac98205 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sun, 10 Nov 2024 19:00:26 +1300 Subject: [PATCH 02/13] clarfication around $dynamicAnchor and its separation from $ref semantics --- specs/jsonschema-core.md | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 10031a27..cc664405 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -946,17 +946,18 @@ The `$anchor` and `$dynamicAnchor` keywords are used to specify such fragments. They are identifier keywords that can only be used to create plain name fragments, rather than absolute IRIs as seen with `$id`. -The base IRI to which the resulting fragment is appended is the canonical IRI of -the schema resource containing the `$anchor` or `$dynamicAnchor` in question. -As discussed in the previous section, this is either the nearest `$id` in the -same or parent schema object, or the base IRI for the document as determined -according to [RFC 3987](#rfc3987) and [RFC 3986](#rfc3986). - -Separately from the usual usage of IRIs, `$dynamicAnchor` indicates that the -fragment is an extension point when used with the `$dynamicRef` keyword. This -low-level, advanced feature makes it easier to extend recursive schemas such as -the meta-schemas, without imposing any particular semantics on that extension. -See the section on [`$dynamicRef`](#dynamic-ref) for details. +`$anchor` defines a reference target for `$ref`. The fragment defined by this +keyword is appended is the IRI of the schema resource containing it. As +discussed in {{id-keyword}}, this is either the nearest `$id` in the same or an +ancestor schema object, or the base IRI for the document as determined according +to [RFC 3987](#rfc3987) and [RFC 3986](#rfc3986). + +In contrast, `$dynamicAnchor` operates independently of resource IRIs and is +instead dependent on the dynamic scope of the evaluation. `$dynamicAnchor` +defines a reference target for the `$dynamicRef` keyword. This advanced feature +makes it easier to extend recursive schemas such as the meta-schemas, without +imposing any particular semantics on that extension. See {{dynamic-ref}} for +details. In most cases, the normal fragment behavior both suffices and is more intuitive. Therefore it is RECOMMENDED that `$anchor` be used to create plain name @@ -1012,12 +1013,15 @@ resolution until runtime, at which point it is resolved each time it is encountered while evaluating an instance. Together with `$dynamicAnchor`, `$dynamicRef` implements a cooperative extension -mechanism that is primarily useful to extend recursive schemas. The extension -point is defined with `$dynamicAnchor` and only exhibits runtime dynamic -behavior when referenced with `$dynamicRef`. +mechanism that is primarily useful to extend recursive schemas, where +`$dynamicRef` defines the extension point, and `$dynamicAnchor` defines the +target. The value of the `$dynamicRef` property MUST be a valid -[plain name fragment](#anchors). +[plain name fragment](#anchors).[^3] + +[^3]: `$dynamicAnchor` defines the anchor with plain text, e.g. `foo`; the +`$dynamicRef` that references it uses a URI fragment syntax, e.g. `#foo`. Resolution of `$dynamicRef` begins by identifying the the outermost schema resource in the [dynamic scope](#scopes) which defines a matching From dcb6ee443b32154591776fe3bde405291aaa1149 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Tue, 12 Nov 2024 06:25:36 +1300 Subject: [PATCH 03/13] Update specs/jsonschema-core.md Co-authored-by: Juan Cruz Viotti --- specs/jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index cc664405..1865c1c2 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -947,7 +947,7 @@ They are identifier keywords that can only be used to create plain name fragments, rather than absolute IRIs as seen with `$id`. `$anchor` defines a reference target for `$ref`. The fragment defined by this -keyword is appended is the IRI of the schema resource containing it. As +keyword is appended to the IRI of the schema resource containing it. As discussed in {{id-keyword}}, this is either the nearest `$id` in the same or an ancestor schema object, or the base IRI for the document as determined according to [RFC 3987](#rfc3987) and [RFC 3986](#rfc3986). From 0ab9b7ad70d079f4971ee114f8a5744b5c4e39a4 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Tue, 12 Nov 2024 06:26:01 +1300 Subject: [PATCH 04/13] Update specs/jsonschema-core.md Co-authored-by: Juan Cruz Viotti --- specs/jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 1865c1c2..9d5a7f55 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -1023,7 +1023,7 @@ The value of the `$dynamicRef` property MUST be a valid [^3]: `$dynamicAnchor` defines the anchor with plain text, e.g. `foo`; the `$dynamicRef` that references it uses a URI fragment syntax, e.g. `#foo`. -Resolution of `$dynamicRef` begins by identifying the the outermost schema +Resolution of `$dynamicRef` begins by identifying the outermost schema resource in the [dynamic scope](#scopes) which defines a matching `$dynamicAnchor`. The schema to apply is the subschema of this resource which contains the matching `$dynamicAnchor`. From 5899a3efc1d232a3c34d7069b4d52a7235f2419b Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 27 Nov 2024 19:10:13 +1300 Subject: [PATCH 05/13] Update specs/jsonschema-core.md Co-authored-by: Jason Desrosiers --- specs/jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 9d5a7f55..7b405e58 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -1018,7 +1018,7 @@ mechanism that is primarily useful to extend recursive schemas, where target. The value of the `$dynamicRef` property MUST be a valid -[plain name fragment](#anchors).[^3] +[plain name fragment](#fragments).[^3] [^3]: `$dynamicAnchor` defines the anchor with plain text, e.g. `foo`; the `$dynamicRef` that references it uses a URI fragment syntax, e.g. `#foo`. From a75cbcebdf0f23a78c50145fb3965c89e1561df4 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 27 Nov 2024 19:59:45 +1300 Subject: [PATCH 06/13] Update specs/jsonschema-core.md Co-authored-by: Jason Desrosiers --- specs/jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 7b405e58..85cfa13d 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -1014,7 +1014,7 @@ encountered while evaluating an instance. Together with `$dynamicAnchor`, `$dynamicRef` implements a cooperative extension mechanism that is primarily useful to extend recursive schemas, where -`$dynamicRef` defines the extension point, and `$dynamicAnchor` defines the +`$dynamicRef` defines the extension point and `$dynamicAnchor` defines the target. The value of the `$dynamicRef` property MUST be a valid From 8dbcd119d8bfb3b6d3a18a8fc530f1fe1087d82a Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 27 Nov 2024 20:01:05 +1300 Subject: [PATCH 07/13] update note about hyper-schema as an example --- specs/jsonschema-core.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 85cfa13d..f67bf4be 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -1030,8 +1030,8 @@ contains the matching `$dynamicAnchor`. For a full example using these keywords, see {{recursive-example}}.[^6] -[^6]: The difference between the hyper-schema meta-schema in pre-2019 drafts and -an this draft dramatically demonstrates the utility of these keywords. +[^6]: The differences in the hyper-schema meta-schemas from draft-07 and draft +2019-09 dramatically demonstrates the utility of these keywords. #### Schema Re-Use With `$defs` {#defs} From 5cddc41f0bbae4e298090ca90c4c81b55c85e645 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 27 Nov 2024 20:08:15 +1300 Subject: [PATCH 08/13] update format adr --- adr/2024-11-2-assertion-format.md | 105 ++++++++++++++++++------------ 1 file changed, 63 insertions(+), 42 deletions(-) diff --git a/adr/2024-11-2-assertion-format.md b/adr/2024-11-2-assertion-format.md index 22a36010..a73f2f67 100644 --- a/adr/2024-11-2-assertion-format.md +++ b/adr/2024-11-2-assertion-format.md @@ -1,78 +1,99 @@ # [short title of solved problem and solution] -* Status: proposed +- Status: proposed -* Deciders: @gregsdennis @jdesrosiers @julian @jviotti @mwadams @karenetheridge @relequestual -* Date: 2024-11-02 -* Technical Story: https://github.com/json-schema-org/json-schema-spec/issues/1520 -* Voting issue: https://github.com/json-schema-org/TSC/issues/19 - For - @gregsdennis @jdesrosiers @jviotti @mwadams @karenetheridge - Neutral - @relequestual - Against - @julian +- Deciders: @gregsdennis @jdesrosiers @julian @jviotti @mwadams @karenetheridge + @relequestual +- Date: 2024-11-02 +- Technical Story: https://github.com/json-schema-org/json-schema-spec/issues/1520 +- Voting issue: https://github.com/json-schema-org/TSC/issues/19 + - For - @gregsdennis @jdesrosiers @jviotti @mwadams @karenetheridge + - Neutral - @relequestual + - Against - @julian ## Context and Problem Statement There's a long and sticky history around format. 1. Going back all the way to Draft 01, format has never required validation. -2. Whether to support format validation has always been the decision of the implementation. -3. The extent to which formats are validated has also been the decision of the implementation. - -The result of all of this is that implementation support for validation has been spotty at best. Despite the JSON Schema specs referencing very concretely defined formats (by referencing other specs), implementations that do support validation don't all support each format equally. This has been the primary driving force behind keeping format as an opt-in validation. - -With 2019-09, we decided that it was time to give the option of format validation to the schema author. They could enable validation by using a meta-schema which listed the Format Vocabulary with a true value, which meant, "format validation is required to process this schema." - -In 2020-12, we further refined this by offering two separate vocabularies, one that treats the keyword as an annotation and one that treats it as an assertion. The argument was that the behavior of a keyword shouldn't change based on whether the vocabulary was required or not. - -However, the fact remains that our users consistently report (via questions in Slack, GitHub, and StackOverflow) that they expect format to validate. (The most recent case I can think of was only last week, in .Net's effort to build a short-term solution for schema generation from types.) +2. Whether to support format validation has always been the decision of the + implementation. +3. The extent to which formats are validated has also been the decision of the + implementation. + +The result of all of this is that implementation support for validation has been +spotty at best. Despite the JSON Schema specs referencing very concretely +defined formats (by referencing other specs), implementations that do support +validation don't all support each format equally. This has been the primary +driving force behind keeping format as an opt-in validation. + +With 2019-09, we decided that it was time to give the option of format +validation to the schema author. They could enable validation by using a +meta-schema which listed the Format Vocabulary with a true value, which meant, +"format validation is required to process this schema." + +In 2020-12, we further refined this by offering two separate vocabularies, one +that treats the keyword as an annotation and one that treats it as an assertion. +The argument was that the behavior of a keyword shouldn't change based on +whether the vocabulary was required or not. + +However, the fact remains that our users consistently report (via questions in +Slack, GitHub, and StackOverflow) that they expect format to validate. (The most +recent case I can think of was only last week, in .Net's effort to build a +short-term solution for schema generation from types.) Due to this consistency in user expectations, we have decided to: 1. make format an assertion keyword, and -2. strictly enforce it by moving the appropriate tests into the required section of the Test Suite and building them more completely. +2. strictly enforce it by moving the appropriate tests into the required section + of the Test Suite and building them more completely. ## Decision Drivers -* User expectation -* Current behavior -* Historical context -* Disparity of current implementation support vs the proposed requirements +- User expectation +- Current behavior +- Historical context +- Disparity of current implementation support vs the proposed requirements ## Considered Options ### `format` remains an annotation keyword by default -This is the current state. The primary benefit is that we don't need to make a breaking change. +This is the current state. The primary benefit is that we don't need to make a +breaking change. -The primary downside is that the current system of (1) configuring the tool or (2) incluing the `format-assertion` vocab[^1] is confusing for many and doesn't align with user expectations. +The primary downside is that the current system of (1) configuring the tool or +(2) incluing the `format-assertion` vocab[^1] is confusing for many and doesn't +align with user expectations. -[^1] The `format-assertion` vocabulary will no longer be an option since we have demoted vocabularies to a proposal for the stable release. This leaves tool configuration as the only option to enable `format` validation. +[^1] The `format-assertion` vocabulary will no longer be an option since we have +demoted vocabularies to a proposal for the stable release. This leaves tool +configuration as the only option to enable `format` validation. ### `format` becomes an assertion keyword by default -We change the spec to require `format` validation. Furthermore: +We change the spec to require `format` validation. Furthermore: -* Implementations SHOULD support `format` with the defined values -* Implementations MAY support others, but only by explicit config -* Implementations MUST refuse to process a schema that contains an unsupported format +- Implementations SHOULD support `format` with the defined values +- Implementations MAY support others, but only by explicit config +- Implementations MUST refuse to process a schema that contains an unsupported format ## Decision Outcome -The TSC has decided via vote (see voting issue above) that we should change `format` to act as an assertion by default, in line with option (2). +The TSC has decided via vote (see voting issue above) that we should change +`format` to act as an assertion by default, in line with option (2). ### Positive Consequences -* Aligns with user expectations. -* Users are still able to have purely annotative behavior through use of something like `x-format`. -* Increased consistency for `format` validation across implementations. +- Aligns with user expectations. +- Users are still able to have purely annotative behavior through use of something like `x-format`. +- Increased consistency for `format` validation across implementations. ### Negative Consequences -* This is a breaking change, which means that we will likely have to re-educate the users who correctly treat it as an annotation. -* Older schemas which do not specify a version (`$schema`) may change their validation outcome. -* The burden on implementations will be greater since format validation was previously optional. - -## Links - -* [Link type] [Link to ADR] -* … +- This is a breaking change, which means that we will likely have to re-educate + the users who correctly treat it as an annotation. +- Older schemas which do not specify a version (`$schema`) may change their + validation outcome. +- The burden on implementations will be greater since format validation was + previously optional. From f2c98cb4bb59e87f078be74f4099e4c9a8cf2e77 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 27 Nov 2024 20:12:41 +1300 Subject: [PATCH 09/13] update adr formatting again --- adr/2024-11-2-assertion-format.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/adr/2024-11-2-assertion-format.md b/adr/2024-11-2-assertion-format.md index a73f2f67..7f45c23c 100644 --- a/adr/2024-11-2-assertion-format.md +++ b/adr/2024-11-2-assertion-format.md @@ -1,12 +1,12 @@ -# [short title of solved problem and solution] +# `format` as an assertion - Status: proposed - Deciders: @gregsdennis @jdesrosiers @julian @jviotti @mwadams @karenetheridge @relequestual - Date: 2024-11-02 -- Technical Story: https://github.com/json-schema-org/json-schema-spec/issues/1520 -- Voting issue: https://github.com/json-schema-org/TSC/issues/19 +- Technical Story: +- Voting issue: - For - @gregsdennis @jdesrosiers @jviotti @mwadams @karenetheridge - Neutral - @relequestual - Against - @julian @@ -16,9 +16,9 @@ There's a long and sticky history around format. 1. Going back all the way to Draft 01, format has never required validation. -2. Whether to support format validation has always been the decision of the +1. Whether to support format validation has always been the decision of the implementation. -3. The extent to which formats are validated has also been the decision of the +1. The extent to which formats are validated has also been the decision of the implementation. The result of all of this is that implementation support for validation has been @@ -45,7 +45,7 @@ short-term solution for schema generation from types.) Due to this consistency in user expectations, we have decided to: 1. make format an assertion keyword, and -2. strictly enforce it by moving the appropriate tests into the required section +1. strictly enforce it by moving the appropriate tests into the required section of the Test Suite and building them more completely. ## Decision Drivers @@ -63,8 +63,8 @@ This is the current state. The primary benefit is that we don't need to make a breaking change. The primary downside is that the current system of (1) configuring the tool or -(2) incluing the `format-assertion` vocab[^1] is confusing for many and doesn't -align with user expectations. +(2) incluing the `format-assertion` vocab is confusing for many and doesn't +align with user expectations.[^1] [^1] The `format-assertion` vocabulary will no longer be an option since we have demoted vocabularies to a proposal for the stable release. This leaves tool @@ -76,7 +76,8 @@ We change the spec to require `format` validation. Furthermore: - Implementations SHOULD support `format` with the defined values - Implementations MAY support others, but only by explicit config -- Implementations MUST refuse to process a schema that contains an unsupported format +- Implementations MUST refuse to process a schema that contains an unsupported + format ## Decision Outcome @@ -86,7 +87,8 @@ The TSC has decided via vote (see voting issue above) that we should change ### Positive Consequences - Aligns with user expectations. -- Users are still able to have purely annotative behavior through use of something like `x-format`. +- Users are still able to have purely annotative behavior through use of + something like `x-format`. - Increased consistency for `format` validation across implementations. ### Negative Consequences From 54f15de77aab80ee9a7fdd527afcf386cb58e7b8 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 27 Nov 2024 20:14:45 +1300 Subject: [PATCH 10/13] footnotes need a colon --- adr/2024-11-2-assertion-format.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/adr/2024-11-2-assertion-format.md b/adr/2024-11-2-assertion-format.md index 7f45c23c..9941de2a 100644 --- a/adr/2024-11-2-assertion-format.md +++ b/adr/2024-11-2-assertion-format.md @@ -63,10 +63,10 @@ This is the current state. The primary benefit is that we don't need to make a breaking change. The primary downside is that the current system of (1) configuring the tool or -(2) incluing the `format-assertion` vocab is confusing for many and doesn't -align with user expectations.[^1] +(2) incluing the `format-assertion` vocab[^1] is confusing for many and doesn't +align with user expectations. -[^1] The `format-assertion` vocabulary will no longer be an option since we have +[^1]: The `format-assertion` vocabulary will no longer be an option since we have demoted vocabularies to a proposal for the stable release. This leaves tool configuration as the only option to enable `format` validation. From 48b346be8603aa064f814d9f7fc01b83aac6175e Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 27 Nov 2024 20:17:24 +1300 Subject: [PATCH 11/13] apparently the footnote needs to be at the end for this file --- adr/2024-11-2-assertion-format.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/adr/2024-11-2-assertion-format.md b/adr/2024-11-2-assertion-format.md index 9941de2a..9546197d 100644 --- a/adr/2024-11-2-assertion-format.md +++ b/adr/2024-11-2-assertion-format.md @@ -66,10 +66,6 @@ The primary downside is that the current system of (1) configuring the tool or (2) incluing the `format-assertion` vocab[^1] is confusing for many and doesn't align with user expectations. -[^1]: The `format-assertion` vocabulary will no longer be an option since we have -demoted vocabularies to a proposal for the stable release. This leaves tool -configuration as the only option to enable `format` validation. - ### `format` becomes an assertion keyword by default We change the spec to require `format` validation. Furthermore: @@ -99,3 +95,7 @@ The TSC has decided via vote (see voting issue above) that we should change validation outcome. - The burden on implementations will be greater since format validation was previously optional. + +[^1]: The `format-assertion` vocabulary will no longer be an option since we +have demoted vocabularies to a proposal for the stable release. This leaves tool +configuration as the only option to enable `format` validation. From 1edbad0f903328b61581a58189407abe47031945 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 3 Jan 2025 12:18:02 +1300 Subject: [PATCH 12/13] removed IRI language from $dynamicRef passages --- specs/jsonschema-core.md | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index f67bf4be..c3ac02b7 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -547,8 +547,8 @@ determined at runtime. While custom identifier keywords are possible, extension designers should take care not to disrupt the functioning of core keywords. For example, the -`$dynamicAnchor` keyword in this specification limits its IRI resolution effects -to the matching `$dynamicRef` keyword, leaving the behavior of `$ref` +`$dynamicAnchor` keyword in this specification limits its resolution behavior +to matching `$dynamicRef` keywords, leaving the behavior of `$ref` undisturbed. ### Applicators {#applicators} @@ -980,18 +980,9 @@ result is undefined, and even if documented will not be interoperable. #### Schema References {#references} -Several keywords can be used to reference a schema which is to be applied to the -current instance location. `$ref` and `$dynamicRef` are applicator keywords, -applying the referenced schema to the instance. - -As the values of `$ref` and `$dynamicRef` are IRI References, this allows the -possibility to externalise or divide a schema across multiple files, and -provides the ability to validate recursive structures through self-reference. - -The resolved IRI produced by these keywords is not necessarily a network -locator, only an identifier. A schema need not be downloadable from the address -if it is a network-addressable URL. Implementations which can access the network -SHOULD default to operating offline. +`$ref` and `$dynamicRef` can be used to reference a schema which is to be +applied to the current instance location. As such, they are considered +applicators, applying the referenced schema to the instance. ##### Direct References with `$ref` {#ref} @@ -1006,6 +997,11 @@ Resolved against the current IRI base, it produces the IRI of the schema to apply. This resolution is safe to perform on schema load, as the process of evaluating an instance cannot change how the reference resolves. +The resolved IRI produced by `$ref` is not necessarily a network +locator, only an identifier. A schema need not be downloadable from the address +if it is a network-addressable URL. Implementations which can access the network +SHOULD default to operating offline. + ##### Dynamic References with `$dynamicRef` {#dynamic-ref} The `$dynamicRef` keyword is an applicator that allows for deferring the full @@ -1013,15 +1009,16 @@ resolution until runtime, at which point it is resolved each time it is encountered while evaluating an instance. Together with `$dynamicAnchor`, `$dynamicRef` implements a cooperative extension -mechanism that is primarily useful to extend recursive schemas, where +mechanism that is primarily useful to to create open schemas, where `$dynamicRef` defines the extension point and `$dynamicAnchor` defines the target. -The value of the `$dynamicRef` property MUST be a valid -[plain name fragment](#fragments).[^3] +The value of the `$dynamicRef` property MUST be formatted as a valid +[IRI plain name fragment](#fragments).[^3] -[^3]: `$dynamicAnchor` defines the anchor with plain text, e.g. `foo`; the -`$dynamicRef` that references it uses a URI fragment syntax, e.g. `#foo`. +[^3]: `$dynamicAnchor` defines the anchor with plain text, e.g. `foo`. Although +the value of `$dynamicRef` is not an IRI fragment, for historical reasons, the +value still uses an IRI fragment syntax, e.g. `#foo`. Resolution of `$dynamicRef` begins by identifying the outermost schema resource in the [dynamic scope](#scopes) which defines a matching From eec2c4c56daec0bf61c9ddf509073fe78f3b4c95 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 3 Jan 2025 12:20:43 +1300 Subject: [PATCH 13/13] update year on ietf specs --- specs/jsonschema-use-cases.xml | 2 +- specs/relative-json-pointer.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/jsonschema-use-cases.xml b/specs/jsonschema-use-cases.xml index ce2dc1fe..7269533d 100644 --- a/specs/jsonschema-use-cases.xml +++ b/specs/jsonschema-use-cases.xml @@ -23,7 +23,7 @@ - + JSON Schema JSON Schema diff --git a/specs/relative-json-pointer.xml b/specs/relative-json-pointer.xml index 5d3d7b20..f00cb1ee 100644 --- a/specs/relative-json-pointer.xml +++ b/specs/relative-json-pointer.xml @@ -40,7 +40,7 @@ - + Internet Engineering Task Force JSON JavaScript