Skip to content

Commit 86647d1

Browse files
committed
reorganize the $id section and remove redundancies
1 parent 76505b9 commit 86647d1

File tree

1 file changed

+27
-23
lines changed

1 file changed

+27
-23
lines changed

jsonschema-core.md

Lines changed: 27 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -895,41 +895,34 @@ by other parties.
895895
### Base IRI, Anchors, and Dereferencing
896896

897897
To differentiate between schemas in a vast ecosystem, schemas are identified by
898-
[IRI](#rfc3987), and can embed references to other schemas by specifying their
899-
IRI.
898+
[absolute IRIs](#rfc3987) (without fragments), and can embed references to other
899+
schemas by specifying their IRI. When comparing IRIs, implementations SHOULD
900+
interpret them using the normalization procedures defined in
901+
[RFC 3987](#rfc3987), section 5.3.
900902

901903
Several keywords can accept a relative [IRI reference](#rfc3987), or a value
902904
used to construct a relative IRI reference. For these keywords, it is necessary
903905
to establish a base IRI in order to resolve the reference.
904906

905907
#### The `$id` Keyword {#id-keyword}
906908

907-
The `$id` keyword identifies a schema resource with its [canonical](#rfc6596)
908-
IRI.
909+
The `$id` keyword identifies a schema resource. The value for this keyword MUST
910+
be a string, and MUST represent a valid [IRI reference](#rfc3987) (without a
911+
fragment).
912+
913+
When the value of this keyword is resolved against the current base IRI, the
914+
resulting absolute IRI then serves as the identifier for the schema resource and
915+
as a base IRI for relative IRI references in keywords within that schema
916+
resource, in accordance with [RFC 3987 section 6.5](#rfc3987) and
917+
[RFC 3986 section 5.1.1](#rfc3986) regarding base IRIs embedded in content.
909918

910919
Note that this IRI is an identifier and not necessarily a network locator. In
911920
the case of a network-addressable URL, a schema need not be downloadable from
912921
its canonical IRI.
913922

914-
If present, the value for this keyword MUST be a string, and MUST represent a
915-
valid [IRI reference](#rfc3987). This IRI reference SHOULD be normalized per RFC
916-
3987, section 5.3, and MUST resolve to an [absolute IRI](#rfc3987) (without a
917-
fragment).
918-
919-
The resulting absolute IRI serves as the base IRI for relative IRI references in
920-
keywords within the schema resource, in accordance with [RFC 3987 section
921-
6.5](#rfc3987) and [RFC 3986 section 5.1.1](#rfc3986) regarding base IRIs
922-
embedded in content.
923-
924-
The presence of `$id` in a subschema indicates that the subschema constitutes a
925-
distinct schema resource within a single schema document. Furthermore, in
926-
accordance with [RFC 3987 section 6.5](#rfc3987) and [RFC 3986 section
927-
5.1.2](#rfc3986) regarding encapsulating entities, if an `$id` in a subschema is
928-
a relative IRI reference, the base IRI for resolving that reference is the IRI
929-
of the parent schema resource. Note that an `$id` consisting of an empty IRI or
930-
of the empty fragment only will result in the embedded resource having the same
931-
IRI as the encapsulating resource, which SHOULD be considered an error per
932-
{{duplicate-iris}}.
923+
Also note that an `$id` consisting of an empty IRI only will result in the
924+
embedded resource having the same IRI as the encapsulating resource, which
925+
SHOULD be considered an error per {{duplicate-iris}}.
933926

934927
If no parent schema object explicitly identifies itself as a resource with
935928
`$id`, the base IRI is that of the entire document, as established by the steps
@@ -1387,6 +1380,17 @@ behave correctly under implementations that attempt to use any reference target
13871380
as a schema. However, this behavior is implementation-specific and MUST NOT be
13881381
relied upon for interoperability.
13891382

1383+
A reference target under a keyword for which the value is known not to be a
1384+
schema results in undefined behavior in order to avoid burdening implementations
1385+
with the need to detect such targets.[^10]
1386+
1387+
[^10]: These scenarios are analogous to fetching a schema over HTTP but
1388+
receiving a response with a Content-Type other than `application/schema+json`.
1389+
An implementation can certainly try to interpret it as a schema, but the origin
1390+
server offered no guarantee that it actually is any such thing. Therefore,
1391+
interpreting it as such has security implication and may produce unpredictable
1392+
results.
1393+
13901394
#### Failure to resolve references {#failed-refs}
13911395

13921396
If for any reason a reference cannot be resolved, the evaluation MUST halt and

0 commit comments

Comments
 (0)