Skip to content

Commit f548fba

Browse files
committed
use internal links on validation; markdown line length cleanup
1 parent a3ba78a commit f548fba

File tree

2 files changed

+99
-203
lines changed

2 files changed

+99
-203
lines changed

specs/jsonschema-core.md

Lines changed: 60 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -242,12 +242,15 @@ are using.
242242

243243
#### Root Schema and Subschemas and Resources {#root}
244244

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.
251254

252255
The root schema is the schema that comprises the entire JSON document in
253256
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.
285288

286289
## Fragment Identifiers {#fragments}
287290

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`.)
292297

293298
Additionally, the `application/schema+json` media type supports two fragment
294299
identifier structures: plain names and JSON Pointers. The
@@ -301,16 +306,17 @@ identifier syntaxes, fragment identifiers matching the JSON Pointer syntax,
301306
including the empty string, MUST be interpreted as JSON Pointer fragment
302307
identifiers.
303308

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.
308313

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:
314320

315321
```abnf
316322
NCName = NCNameStartChar *NCNameChar
@@ -653,8 +659,9 @@ behalf of applications.
653659

654660
Unless otherwise specified, the value of an annotation keyword is the keyword's
655661
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.
658665

659666
While "short-circuit" evaluation is possible for assertions, collecting
660667
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
880887
resources, unless such a resource itself declares a different dialect by
881888
including the `$schema` keyword with a different value.
882889

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.
885893

886894
If this IRI identifies a retrievable resource, that resource SHOULD be of media
887895
type `application/schema+json`.
@@ -896,10 +904,12 @@ by other parties.
896904
### Base IRI, Anchors, and Dereferencing
897905

898906
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.
903913

904914
Several keywords can accept a relative IRI reference, or a value
905915
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
915925
resulting absolute IRI then serves as the identifier for the schema resource and
916926
as a base IRI for relative IRI references in keywords within that schema
917927
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.
920932

921933
Note that this IRI is an identifier and not necessarily a network locator. In
922934
the case of a network-addressable URL, a schema need not be downloadable from
@@ -933,7 +945,8 @@ given in {{initial-base}}.
933945
##### Identifying the root schema
934946

935947
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).
937950

938951
#### Defining location-independent identifiers {#anchors}
939952

@@ -999,10 +1012,10 @@ Resolved against the current IRI base, it produces the IRI of the schema to
9991012
apply. This resolution is safe to perform on schema load, as the process of
10001013
evaluating an instance cannot change how the reference resolves.
10011014

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.
10061019

10071020
##### Dynamic References with `$dynamicRef` {#dynamic-ref}
10081021

@@ -1087,8 +1100,10 @@ MUST NOT be collected as an annotation result.
10871100

10881101
#### Initial Base IRI {#initial-base}
10891102

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.
10921107

10931108
Informatively, the initial base IRI of a schema is the IRI at which it was
10941109
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"
14411456

14421457
##### Usage Over HTTP
14431458

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.
14491465

14501466
HTTP servers SHOULD set long-lived caching headers on JSON Schemas. HTTP clients
14511467
SHOULD observe caching headers and not re-request documents within their
@@ -1846,9 +1862,9 @@ property values.
18461862

18471863
The behavior of this keyword depends on all adjacent keywords as well as
18481864
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.
18521868

18531869
This keyword applies its subschema to any property values which have not been
18541870
deemed "evaluated" per {{unevaluated}}. Validation passes if the keyword's

0 commit comments

Comments
 (0)