Skip to content

Commit 9af8b27

Browse files
committed
pointers across resource boundary is undefined
1 parent a260c77 commit 9af8b27

File tree

1 file changed

+31
-25
lines changed

1 file changed

+31
-25
lines changed

jsonschema-core.md

Lines changed: 31 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -933,7 +933,7 @@ IRI as the encapsulating resource, which SHOULD be considered an error per
933933

934934
If no parent schema object explicitly identifies itself as a resource with
935935
`$id`, the base IRI is that of the entire document, as established by the steps
936-
given in the [previous section.](initial-base)
936+
given in {{initial-base}}.
937937

938938
##### Identifying the root schema
939939

@@ -1191,15 +1191,9 @@ automatically.
11911191

11921192
When an implementation encounters the reference to "other.json", it resolves
11931193
this to `https://example.net/other.json`, which is not defined in this document.
1194-
If a schema with that identifier has otherwise been supplied to the
1195-
implementation, it can also be used automatically.[^7]
1196-
1197-
[^7]: What should implementations do when the referenced schema is not known?
1198-
Are there circumstances in which automatic network dereferencing is allowed? A
1199-
same origin policy? A user-configurable option? In the case of an evolving API
1200-
described by Hyper-Schema, it is expected that new schemas will be added to the
1201-
system dynamically, so placing an absolute requirement of pre-loading schema
1202-
documents is not feasible.
1194+
If an implementation has been configured to resolve that identifier to a schema
1195+
via pre-loading or other means, it can be used automatically; otherwise, the
1196+
behavior described in {{failed-refs}} MUST be used.
12031197

12041198
#### JSON Pointer fragments and embedded schema resources {#embedded}
12051199

@@ -1272,10 +1266,10 @@ the `$id` of the embedded or referenced resource unless it is specifically
12721266
desired to identify the object containing the `$ref` in the second
12731267
(non-embedded) arrangement.
12741268

1275-
An implementation MAY choose not to support addressing schema resource contents
1276-
by IRIs using a base other than the resource's canonical IRI, plus a JSON
1277-
Pointer fragment relative to that base. Therefore, schema authors SHOULD NOT
1278-
rely on such IRIs, as using them may reduce interoperability.[^8]
1269+
Due to the potential break in functionality described above, the behavior for
1270+
using JSON Pointer fragments that point to or cross a resource boundary is
1271+
undefined. Schema authors SHOULD NOT rely on such IRIs, as using them may
1272+
reduce interoperability.
12791273

12801274
[^8]: This is to avoid requiring implementations to keep track of a whole stack
12811275
of possible base IRIs and JSON Pointer fragments for each, given that all but
@@ -1408,7 +1402,7 @@ behave correctly under implementations that attempt to use any reference target
14081402
as a schema. However, this behavior is implementation-specific and MUST NOT be
14091403
relied upon for interoperability.
14101404

1411-
#### Failure to resolve references
1405+
#### Failure to resolve references {#failed-refs}
14121406

14131407
If for any reason a reference cannot be resolved, the evaluation MUST halt and
14141408
return an indeterminant result. Specifically, it MUST NOT return a passing or
@@ -2231,32 +2225,22 @@ listed IRI in accordance with {{fragments}} and {{embedded}} above.
22312225
`#/$defs/B`: canonical (and base) `IRI: https://example.com/other.json`
22322226
- canonical resource IRI plus pointer fragment:
22332227
`https://example.com/other.json#`
2234-
- base IRI of enclosing (root.json) resource plus fragment:
2235-
`https://example.com/root.json#/$defs/B`
22362228

22372229
`#/$defs/B/$defs/X`: base IRI: `https://example.com/other.json`
22382230
- canonical resource IRI plus plain fragment:
22392231
`https://example.com/other.json#bar`
22402232
- canonical resource IRI plus pointer fragment:
22412233
`https://example.com/other.json#/$defs/X`
2242-
- base IRI of enclosing (root.json) resource plus fragment:
2243-
`https://example.com/root.json#/$defs/B/$defs/X`
22442234

22452235
`#/$defs/B/$defs/Y`: canonical (and base) IRI:
22462236
`https://example.com/t/inner.json`
22472237
- canonical IRI plus plain fragment: `https://example.com/t/inner.json#bar`
22482238
- canonical IRI plus pointer fragment: `https://example.com/t/inner.json#`
2249-
- base IRI of enclosing (other.json) resource plus fragment:
2250-
`https://example.com/other.json#/$defs/Y`
2251-
- base IRI of enclosing (root.json) resource plus fragment:
2252-
`https://example.com/root.json#/$defs/B/$defs/Y`
22532239

22542240
`#/$defs/C`: canonical (and base) IRI:
22552241
`urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f`
22562242
- canonical IRI plus pointer fragment:
22572243
`urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f#`
2258-
- base IRI of enclosing (root.json) resource plus fragment:
2259-
`https://example.com/root.json#/$defs/C`
22602244

22612245
Note: The fragment part of the IRI does not make it canonical or non-canonical,
22622246
rather, the base IRI used (as part of the full IRI with any fragment) is what
@@ -2266,6 +2250,28 @@ determines the canonical nature of the resulting full IRI.[^18]
22662250
and direct you to read the CREF located in the [JSON Pointer fragments and
22672251
embedded schema resources](#embedded) section for further comments.
22682252

2253+
While the following IRIs do correctly indicate specific schemas, per the reasons outlined in {{embedded}}, they are to be avoided:
2254+
2255+
`#/$defs/B`: canonical (and base) `IRI: https://example.com/other.json`
2256+
- base IRI of enclosing (root.json) resource plus fragment:
2257+
`https://example.com/root.json#/$defs/B`
2258+
2259+
`#/$defs/B/$defs/X`: base IRI: `https://example.com/other.json`
2260+
- base IRI of enclosing (root.json) resource plus fragment:
2261+
`https://example.com/root.json#/$defs/B/$defs/X`
2262+
2263+
`#/$defs/B/$defs/Y`: canonical (and base) IRI:
2264+
`https://example.com/t/inner.json`
2265+
- base IRI of enclosing (other.json) resource plus fragment:
2266+
`https://example.com/other.json#/$defs/Y`
2267+
- base IRI of enclosing (root.json) resource plus fragment:
2268+
`https://example.com/root.json#/$defs/B/$defs/Y`
2269+
2270+
`#/$defs/C`: canonical (and base) IRI:
2271+
`urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f`
2272+
- base IRI of enclosing (root.json) resource plus fragment:
2273+
`https://example.com/root.json#/$defs/C`
2274+
22692275
## [Appendix] Manipulating schema documents and references
22702276

22712277
Various tools have been created to rearrange schema documents based on how and

0 commit comments

Comments
 (0)