@@ -933,7 +933,7 @@ IRI as the encapsulating resource, which SHOULD be considered an error per
933933
934934If 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
11921192When an implementation encounters the reference to "other.json", it resolves
11931193this 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
12721266desired 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
12811275of 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
14081402as a schema. However, this behavior is implementation-specific and MUST NOT be
14091403relied upon for interoperability.
14101404
1411- #### Failure to resolve references
1405+ #### Failure to resolve references {#failed-refs}
14121406
14131407If for any reason a reference cannot be resolved, the evaluation MUST halt and
14141408return 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
22612245Note: The fragment part of the IRI does not make it canonical or non-canonical,
22622246rather, 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]
22662250and direct you to read the CREF located in the [ JSON Pointer fragments and
22672251embedded 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
22712277Various tools have been created to rearrange schema documents based on how and
0 commit comments