From d078e3009ed63a97986a894075e0e13e55f03485 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Mon, 4 Sep 2023 11:27:34 +1200 Subject: [PATCH 1/9] add guidance for schema authors about locatable IRIs --- jsonschema-core.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 992df3c7..9749c8c3 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -1058,7 +1058,10 @@ IRI. Note that this IRI is an identifier and not necessarily a network locator. In the case of a network-addressable URL, a schema need not be downloadable from -its canonical IRI. +its canonical IRI. However, schema authors SHOULD refrain from creating schemas +that use a locatable `$id` value unless the schema will be available at the +indicated location. Otherwise, an IRI which does not convey location semantics +SHOULD be used. If present, the value for this keyword MUST be a string, and MUST represent a valid [IRI-reference](#rfc3987). This IRI-reference SHOULD be normalized, and From 3627d1276102e4d49d8f25a84df002a8e688bc43 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Mon, 4 Sep 2023 12:12:16 +1200 Subject: [PATCH 2/9] invert recommendation against online access to for offline access --- jsonschema-core.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 9749c8c3..662b5bf7 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -1146,9 +1146,8 @@ 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, and implementations SHOULD NOT assume they -should perform a network operation when they encounter a network-addressable -IRI. +if it is a network-addressable URL. Implementations which can access the network +SHOULD default to operating offline. ##### Direct References with `$ref` {#ref} From 1ba7a151303143219de090abfd0f8536953d94e2 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 6 Sep 2023 09:47:54 +1200 Subject: [PATCH 3/9] provide explicit permission to download schemas --- jsonschema-core.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 662b5bf7..9042b0b0 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -1277,10 +1277,6 @@ The use of IRIs to identify remote schemas does not necessarily mean anything is downloaded, but instead JSON Schema implementations SHOULD understand ahead of time which schemas they will be using, and the IRIs that identify them. -When schemas are downloaded, for example by a generic user-agent that does not -know until runtime which schemas to download, see [Usage for -Hypermedia](#hypermedia). - Implementations SHOULD be able to associate arbitrary IRIs with an arbitrary schema and/or automatically associate a schema's `$id`-given IRI, depending on the trust that the validator has in the schema. Such IRIs and schemas can be @@ -1288,6 +1284,12 @@ supplied to an implementation prior to processing instances, or may be noted within a schema document as it is processed, producing associations as shown in {{idexamples}}. +Implementations MAY provide functionality to automatically fetch schemas based +on location semantics expressed by the URI, however such functionality MUST be +disabled by default to prefer offline operation. When schemas are downloaded, +for example by a generic user-agent that does not know until runtime which +schemas to download, see {{hypermedia}}. + #### Detecting a Meta-Schema Implementations MUST recognize a schema as a meta-schema if it is being examined From 1c7a3366eee635523e5027898e1d1c96821ac214 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Thu, 14 Sep 2023 08:39:03 +1200 Subject: [PATCH 4/9] remove guidance that authors need to consider locatability of URIs --- jsonschema-core.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 9042b0b0..ab18d79e 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -1058,10 +1058,7 @@ IRI. Note that this IRI is an identifier and not necessarily a network locator. In the case of a network-addressable URL, a schema need not be downloadable from -its canonical IRI. However, schema authors SHOULD refrain from creating schemas -that use a locatable `$id` value unless the schema will be available at the -indicated location. Otherwise, an IRI which does not convey location semantics -SHOULD be used. +its canonical IRI. If present, the value for this keyword MUST be a string, and MUST represent a valid [IRI-reference](#rfc3987). This IRI-reference SHOULD be normalized, and From 82041cdefd9ebe84373e994600c352a5965c8df9 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Thu, 14 Sep 2023 08:42:52 +1200 Subject: [PATCH 5/9] update downloading requirement from MUST to SHOULD --- jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index ab18d79e..0d647cfd 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -1282,7 +1282,7 @@ within a schema document as it is processed, producing associations as shown in {{idexamples}}. Implementations MAY provide functionality to automatically fetch schemas based -on location semantics expressed by the URI, however such functionality MUST be +on location semantics expressed by the URI, however such functionality SHOULD be disabled by default to prefer offline operation. When schemas are downloaded, for example by a generic user-agent that does not know until runtime which schemas to download, see {{hypermedia}}. From 76bffb6317f8008327cd9634dd8a56a6a4b708dd Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Thu, 14 Sep 2023 11:59:10 +1200 Subject: [PATCH 6/9] restore requirement to MUST --- jsonschema-core.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 0d647cfd..5f23dfed 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -1144,7 +1144,7 @@ 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. +MUST default to operating offline. ##### Direct References with `$ref` {#ref} @@ -1282,7 +1282,7 @@ within a schema document as it is processed, producing associations as shown in {{idexamples}}. Implementations MAY provide functionality to automatically fetch schemas based -on location semantics expressed by the URI, however such functionality SHOULD be +on location semantics expressed by the URI, however such functionality MUST be disabled by default to prefer offline operation. When schemas are downloaded, for example by a generic user-agent that does not know until runtime which schemas to download, see {{hypermedia}}. From ef5ea07d94d3cfe2fdf7a62fc232ea34d1c21ffe Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Thu, 14 Sep 2023 12:38:17 +1200 Subject: [PATCH 7/9] correct URI usage to IRI --- jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 5f23dfed..8a92a046 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -1282,7 +1282,7 @@ within a schema document as it is processed, producing associations as shown in {{idexamples}}. Implementations MAY provide functionality to automatically fetch schemas based -on location semantics expressed by the URI, however such functionality MUST be +on location semantics expressed by the IRI, however such functionality MUST be disabled by default to prefer offline operation. When schemas are downloaded, for example by a generic user-agent that does not know until runtime which schemas to download, see {{hypermedia}}. From 38b515ae4f9f0acc529ffe9872f5331df66d73ab Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 20 Sep 2023 10:25:45 +1200 Subject: [PATCH 8/9] update back to SHOULD after 'implementation' discussion --- jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 8a92a046..bdf8c53a 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -1282,7 +1282,7 @@ within a schema document as it is processed, producing associations as shown in {{idexamples}}. Implementations MAY provide functionality to automatically fetch schemas based -on location semantics expressed by the IRI, however such functionality MUST be +on location semantics expressed by the IRI, however such functionality SHOULD be disabled by default to prefer offline operation. When schemas are downloaded, for example by a generic user-agent that does not know until runtime which schemas to download, see {{hypermedia}}. From 9920bd8298b9415ad96c42f24aa1013d69da4282 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Thu, 21 Sep 2023 07:26:32 +1200 Subject: [PATCH 9/9] update other MUST to SHOULD --- jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index bdf8c53a..9c013c2a 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -1144,7 +1144,7 @@ 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 -MUST default to operating offline. +SHOULD default to operating offline. ##### Direct References with `$ref` {#ref}