@@ -933,7 +933,7 @@ IRI as the encapsulating resource, which SHOULD be considered an error per
933
933
934
934
If no parent schema object explicitly identifies itself as a resource with
935
935
` $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}}.
937
937
938
938
##### Identifying the root schema
939
939
@@ -1191,15 +1191,9 @@ automatically.
1191
1191
1192
1192
When an implementation encounters the reference to "other.json", it resolves
1193
1193
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.
1203
1197
1204
1198
#### JSON Pointer fragments and embedded schema resources {#embedded}
1205
1199
@@ -1272,10 +1266,10 @@ the `$id` of the embedded or referenced resource unless it is specifically
1272
1266
desired to identify the object containing the ` $ref ` in the second
1273
1267
(non-embedded) arrangement.
1274
1268
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.
1279
1273
1280
1274
[ ^ 8 ] : This is to avoid requiring implementations to keep track of a whole stack
1281
1275
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
1408
1402
as a schema. However, this behavior is implementation-specific and MUST NOT be
1409
1403
relied upon for interoperability.
1410
1404
1411
- #### Failure to resolve references
1405
+ #### Failure to resolve references {#failed-refs}
1412
1406
1413
1407
If for any reason a reference cannot be resolved, the evaluation MUST halt and
1414
1408
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.
2231
2225
` #/$defs/B ` : canonical (and base) ` IRI: https://example.com/other.json `
2232
2226
- canonical resource IRI plus pointer fragment:
2233
2227
` https://example.com/other.json# `
2234
- - base IRI of enclosing (root.json) resource plus fragment:
2235
- ` https://example.com/root.json#/$defs/B `
2236
2228
2237
2229
` #/$defs/B/$defs/X ` : base IRI: ` https://example.com/other.json `
2238
2230
- canonical resource IRI plus plain fragment:
2239
2231
` https://example.com/other.json#bar `
2240
2232
- canonical resource IRI plus pointer fragment:
2241
2233
` 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 `
2244
2234
2245
2235
` #/$defs/B/$defs/Y ` : canonical (and base) IRI:
2246
2236
` https://example.com/t/inner.json `
2247
2237
- canonical IRI plus plain fragment: ` https://example.com/t/inner.json#bar `
2248
2238
- 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 `
2253
2239
2254
2240
` #/$defs/C ` : canonical (and base) IRI:
2255
2241
` urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f `
2256
2242
- canonical IRI plus pointer fragment:
2257
2243
` 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 `
2260
2244
2261
2245
Note: The fragment part of the IRI does not make it canonical or non-canonical,
2262
2246
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]
2266
2250
and direct you to read the CREF located in the [ JSON Pointer fragments and
2267
2251
embedded schema resources] ( #embedded ) section for further comments.
2268
2252
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
+
2269
2275
## [ Appendix] Manipulating schema documents and references
2270
2276
2271
2277
Various tools have been created to rearrange schema documents based on how and
0 commit comments