@@ -242,12 +242,15 @@ are using.
242
242
243
243
#### Root Schema and Subschemas and Resources {#root}
244
244
245
- A JSON Schema resource is a schema which is [ canonically] ( https://www.rfc-editor.org/info/rfc6596 ) identified
246
- by an [ absolute IRI] ( https://www.rfc-editor.org/rfc/rfc3987.html#section-2.2 ) . Schema resources MAY also be identified by IRIs,
247
- including IRIs with fragments, if the resulting secondary resource (as defined
248
- by [ section 3.5 of RFC 3986] ( https://www.rfc-editor.org/rfc/rfc3986.html#section-3.5 ) ) is identical to the primary resource.
249
- This can occur with the empty fragment, or when one schema resource is embedded
250
- in another. Any such IRIs with fragments are considered to be non-canonical.
245
+ A JSON Schema resource is a schema which is
246
+ [ canonically] ( https://www.rfc-editor.org/info/rfc6596 ) identified by an
247
+ [ absolute IRI] ( https://www.rfc-editor.org/rfc/rfc3987.html#section-2.2 ) . Schema
248
+ resources MAY also be identified by IRIs, including IRIs with fragments, if the
249
+ resulting secondary resource (as defined by
250
+ [ section 3.5 of RFC 3986] ( https://www.rfc-editor.org/rfc/rfc3986.html#section-3.5 ) )
251
+ is identical to the primary resource. This can occur with the empty fragment, or
252
+ when one schema resource is embedded in another. Any such IRIs with fragments
253
+ are considered to be non-canonical.
251
254
252
255
The root schema is the schema that comprises the entire JSON document in
253
256
question. The root schema is always a schema resource, where the IRI is
@@ -285,10 +288,12 @@ are processed in the same way, with the same available behaviors.
285
288
286
289
## Fragment Identifiers {#fragments}
287
290
288
- In accordance with [ section 3.1 of RFC 6839] ( https://www.rfc-editor.org/rfc/rfc6839.html#section-3.1 ) , the syntax and semantics
289
- of fragment identifiers specified for any +json media type SHOULD be as
290
- specified for ` application/json ` . (At publication of this document, there is no
291
- fragment identification syntax defined for ` application/json ` .)
291
+ In accordance with
292
+ [ section 3.1 of RFC 6839] ( https://www.rfc-editor.org/rfc/rfc6839.html#section-3.1 ) ,
293
+ the syntax and semantics of fragment identifiers specified for any +json media
294
+ type SHOULD be as specified for ` application/json ` . (At publication of this
295
+ document, there is no fragment identification syntax defined for
296
+ ` application/json ` .)
292
297
293
298
Additionally, the ` application/schema+json ` media type supports two fragment
294
299
identifier structures: plain names and JSON Pointers. The
@@ -301,16 +306,17 @@ identifier syntaxes, fragment identifiers matching the JSON Pointer syntax,
301
306
including the empty string, MUST be interpreted as JSON Pointer fragment
302
307
identifiers.
303
308
304
- Per the W3C's [ best practices for fragment
305
- identifiers] ( #w3cwd -fragid-best-practices-20121025) , plain name fragment
306
- identifiers in ` application/schema+json ` are reserved for referencing locally
307
- named schemas.
309
+ Per the W3C's
310
+ [ best practices for fragment identifiers] ( https://www.w3.org/TR/2012/WD -fragid-best-practices-20121025) ,
311
+ plain name fragment identifiers in ` application/schema+json ` are reserved for
312
+ referencing locally named schemas.
308
313
309
- Plain name fragments MUST follow XML's [ ` NCName ` production] ( https://www.w3.org/TR/2006/REC-xml-names11-20060816/#NT-NCName ) , which
310
- allows for compatibility with the recommended [ plain name
311
- syntax] ( https://www.w3.org/TR/2003/REC-xptr-framework-20030325/ ) for XML-based media types. For
312
- convenience, the ` NCName ` syntax is reproduced here in ABNF form, using
313
- a minimal set of rules:
314
+ Plain name fragments MUST follow XML's
315
+ [ ` NCName ` production] ( https://www.w3.org/TR/2006/REC-xml-names11-20060816/#NT-NCName ) ,
316
+ which allows for compatibility with the recommended [ plain name
317
+ syntax] ( https://www.w3.org/TR/2003/REC-xptr-framework-20030325/ ) for XML-based
318
+ media types. For convenience, the ` NCName ` syntax is reproduced here in ABNF
319
+ form, using a minimal set of rules:
314
320
315
321
``` abnf
316
322
NCName = NCNameStartChar *NCNameChar
@@ -653,8 +659,9 @@ behalf of applications.
653
659
654
660
Unless otherwise specified, the value of an annotation keyword is the keyword's
655
661
value. However, other behaviors are possible. For example, [ JSON
656
- Hyper-Schema's] ( https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02 ) ` links ` keyword is a complex annotation that
657
- produces a value based in part on the instance data.
662
+ Hyper-Schema's] ( https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02 )
663
+ ` links ` keyword is a complex annotation that produces a value based in part on
664
+ the instance data.
658
665
659
666
While "short-circuit" evaluation is possible for assertions, collecting
660
667
annotations requires examining all schemas that apply to an instance location,
@@ -880,8 +887,9 @@ applies to the resource in which it is declared as well as any embedded schema
880
887
resources, unless such a resource itself declares a different dialect by
881
888
including the ` $schema ` keyword with a different value.
882
889
883
- The value of this keyword MUST be an [ IRI] ( https://www.rfc-editor.org/info/rfc3987 ) (containing a scheme) and
884
- this IRI MUST be normalized.
890
+ The value of this keyword MUST be an
891
+ [ IRI] ( https://www.rfc-editor.org/info/rfc3987 ) (containing a scheme) and this
892
+ IRI MUST be normalized.
885
893
886
894
If this IRI identifies a retrievable resource, that resource SHOULD be of media
887
895
type ` application/schema+json ` .
@@ -896,10 +904,12 @@ by other parties.
896
904
### Base IRI, Anchors, and Dereferencing
897
905
898
906
To differentiate between schemas in a vast ecosystem, schema resources are
899
- identified by [ absolute IRIs] ( https://www.rfc-editor.org/rfc/rfc3987.html#section-2.2 ) (without fragments). These identifiers
900
- are used to create references between schema resources. When comparing IRIs for
901
- the purposes of resource identification, implementations SHOULD first follow the
902
- IRI normalization procedures defined in [ RFC 3987] [ RFC3987 ] , section 5.3.
907
+ identified by
908
+ [ absolute IRIs] ( https://www.rfc-editor.org/rfc/rfc3987.html#section-2.2 )
909
+ (without fragments). These identifiers are used to create references between
910
+ schema resources. When comparing IRIs for the purposes of resource
911
+ identification, implementations SHOULD first follow the IRI normalization
912
+ procedures defined in [ RFC 3987] [ RFC3987 ] , section 5.3.
903
913
904
914
Several keywords can accept a relative IRI reference, or a value
905
915
used to construct a relative IRI reference. For these keywords, it is necessary
@@ -915,8 +925,10 @@ When the value of this keyword is resolved against the current base IRI, the
915
925
resulting absolute IRI then serves as the identifier for the schema resource and
916
926
as a base IRI for relative IRI references in keywords within that schema
917
927
resource and for embedded schema resources, in accordance with [ RFC 3987 section
918
- 6.5] ( https://www.rfc-editor.org/rfc/rfc3987.html#section-6.5 ) and [ RFC 3986 section 5.1.1] ( https://www.rfc-editor.org/rfc/rfc3986.html#section-5.1.1 ) regarding base IRIs
919
- embedded in content and RFC 3986 section 5.1.2 regarding encapsulating entities.
928
+ 6.5] ( https://www.rfc-editor.org/rfc/rfc3987.html#section-6.5 ) and
929
+ [ RFC 3986 section 5.1.1] ( https://www.rfc-editor.org/rfc/rfc3986.html#section-5.1.1 )
930
+ regarding base IRIs embedded in content and RFC 3986 section 5.1.2 regarding
931
+ encapsulating entities.
920
932
921
933
Note that this IRI is an identifier and not necessarily a network locator. In
922
934
the case of a network-addressable URL, a schema need not be downloadable from
@@ -933,7 +945,8 @@ given in {{initial-base}}.
933
945
##### Identifying the root schema
934
946
935
947
The root schema of a JSON Schema document SHOULD contain an ` $id ` keyword with
936
- an [ absolute IRI] ( https://www.rfc-editor.org/rfc/rfc3987.html#section-2.2 ) (containing a scheme, but no fragment).
948
+ an [ absolute IRI] ( https://www.rfc-editor.org/rfc/rfc3987.html#section-2.2 )
949
+ (containing a scheme, but no fragment).
937
950
938
951
#### Defining location-independent identifiers {#anchors}
939
952
@@ -999,10 +1012,10 @@ Resolved against the current IRI base, it produces the IRI of the schema to
999
1012
apply. This resolution is safe to perform on schema load, as the process of
1000
1013
evaluating an instance cannot change how the reference resolves.
1001
1014
1002
- The resolved IRI produced by ` $ref ` is not necessarily a network
1003
- locator, only an identifier. A schema need not be downloadable from the address
1004
- if it is a network-addressable URL. Implementations which can access the network
1005
- SHOULD default to operating offline.
1015
+ The resolved IRI produced by ` $ref ` is not necessarily a network locator, only
1016
+ an identifier. A schema need not be downloadable from the address if it is a
1017
+ network-addressable URL. Implementations which can access the network SHOULD
1018
+ default to operating offline.
1006
1019
1007
1020
##### Dynamic References with ` $dynamicRef ` {#dynamic-ref}
1008
1021
@@ -1087,8 +1100,10 @@ MUST NOT be collected as an annotation result.
1087
1100
1088
1101
#### Initial Base IRI {#initial-base}
1089
1102
1090
- [ RFC 3987 Section 6.5] ( https://www.rfc-editor.org/rfc/rfc3987.html#section-6.5 ) and [ RFC 3986 Section 5.1] ( https://www.rfc-editor.org/rfc/rfc3986.html#section-5.1 ) defines
1091
- how to determine the default base IRI of a document.
1103
+ [ RFC 3987 Section 6.5] ( https://www.rfc-editor.org/rfc/rfc3987.html#section-6.5 )
1104
+ and
1105
+ [ RFC 3986 Section 5.1] ( https://www.rfc-editor.org/rfc/rfc3986.html#section-5.1 )
1106
+ defines how to determine the default base IRI of a document.
1092
1107
1093
1108
Informatively, the initial base IRI of a schema is the IRI at which it was
1094
1109
found, whether that was a network location, a local filesystem, or any other
@@ -1441,11 +1456,12 @@ Link: <https://example.com/my-hyper-schema>; rel="describedby"
1441
1456
1442
1457
##### Usage Over HTTP
1443
1458
1444
- When used for hypermedia systems over a network, [ HTTP] ( https://www.rfc-editor.org/info/rfc7231 ) is frequently
1445
- the protocol of choice for distributing schemas. Misbehaving clients can pose
1446
- problems for server maintainers if they pull a schema over the network more
1447
- frequently than necessary, when it's instead possible to cache a schema for a
1448
- long period of time.
1459
+ When used for hypermedia systems over a network,
1460
+ [ HTTP] ( https://www.rfc-editor.org/info/rfc7231 ) is frequently the protocol of
1461
+ choice for distributing schemas. Misbehaving clients can pose problems for
1462
+ server maintainers if they pull a schema over the network more frequently than
1463
+ necessary, when it's instead possible to cache a schema for a long period of
1464
+ time.
1449
1465
1450
1466
HTTP servers SHOULD set long-lived caching headers on JSON Schemas. HTTP clients
1451
1467
SHOULD observe caching headers and not re-request documents within their
@@ -1846,9 +1862,9 @@ property values.
1846
1862
1847
1863
The behavior of this keyword depends on all adjacent keywords as well as
1848
1864
keywords in successfully validated subschemas that apply to the same instance
1849
- location by evaluating the instance's property values. This includes, but is not limited
1850
- to, ` properties ` , ` patternProperties ` , and ` additionalProperties ` , itself, and
1851
- all [ in-place applicators] ( #in-place ) defined in this document.
1865
+ location by evaluating the instance's property values. This includes, but is not
1866
+ limited to, ` properties ` , ` patternProperties ` , and ` additionalProperties ` ,
1867
+ itself, and all [ in-place applicators] ( #in-place ) defined in this document.
1852
1868
1853
1869
This keyword applies its subschema to any property values which have not been
1854
1870
deemed "evaluated" per {{unevaluated}}. Validation passes if the keyword's
0 commit comments