Skip to content

Commit bd2b330

Browse files
handrewshandrews
committed
Review feedback on canonical $id
$id cannot contain a fragment except for an empty one, mostly because a lot of people do that out of habit it seems. This also reworks the wording around non-canonical URIs to avoid an overly broad "undefined behavior." This still doesn't feel ideal but is hopefully an improvement.
1 parent 7656e94 commit bd2b330

File tree

1 file changed

+41
-12
lines changed

1 file changed

+41
-12
lines changed

‎jsonschema-core.xml

Lines changed: 41 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1515,7 +1515,21 @@
15151515
If present, the value for this keyword MUST be a string, and MUST represent a
15161516
valid <xref target="RFC3986">URI-reference</xref>. This URI-reference
15171517
SHOULD be normalized, and MUST resolve to an
1518-
<xref target="RFC3986">absolute-URI</xref> (without a fragment).
1518+
<xref target="RFC3986">absolute-URI</xref> (without a fragment). Therefore,
1519+
"$id" MUST NOT contain a non-empty fragment, and SHOULD NOT contain an
1520+
empty fragment.
1521+
</t>
1522+
<t>
1523+
Since an empty fragment in the context of the application/schema+json media
1524+
type refers to the same resource as the base URI without a fragment,
1525+
an implementation MAY normalize a URI ending with an empty fragment by removing
1526+
the fragment. However, schema authors SHOULD NOT rely on this behavior
1527+
across implementations.
1528+
<cref>
1529+
This is primarily allowed because older meta-schemas have an empty
1530+
fragment in their $id (or previously, id). A future draft may outright
1531+
forbid even empty fragments in "$id".
1532+
</cref>
15191533
</t>
15201534
<t>
15211535
This URI also serves as the base URI for relative URI-references in keywords
@@ -1543,7 +1557,8 @@
15431557
but no fragment).
15441558
</t>
15451559
</section>
1546-
<section title="JSON Pointer fragments and embedded schema resources">
1560+
<section title="JSON Pointer fragments and embedded schema resources"
1561+
anchor="embedded">
15471562
<t>
15481563
Since JSON Pointer URI fragments are constructed based on the structure
15491564
of the schema document, an embedded schema resource and its subschemas
@@ -1576,12 +1591,24 @@
15761591
schema resource's URI cease to be valid when the embedded schema
15771592
is moved to a separate document and referenced, applications and schemas
15781593
SHOULD NOT use such URIs to identify embedded schema resources or
1579-
locations within them. The effect of using such URIs is undefined.
1580-
Implementations MAY produce an error requiring that the canonical
1581-
URI for the embedded resource be used.
1594+
locations within them.
1595+
</t>
1596+
<t>
1597+
Using such URIs is unreliable, and an implementation MAY choose not to
1598+
support them. If an embedded schema were to be replaced with a reference,
1599+
then the JSON Pointer fragment URI for that schema relative to its
1600+
parent's base URI would then identify the reference, while JSON Pointers
1601+
to locations within the formerly embedded resource would become invalid.
1602+
<cref>
1603+
If the change regarding reference replacement noted in the previous
1604+
CREF were to be implemented, the pointer behavior would be more
1605+
consistent. Really it is the pointers to deeper locations within
1606+
embedded schemas which should be strongly discouraged and
1607+
need not be supported.
1608+
</cref>
15821609
</t>
15831610
<t>
1584-
Examples of such URIs with undefined behavior, as well as the appropriate
1611+
Examples of such non-canonical URIs, as well as the appropriate
15851612
canonical URIs to use instead, are provided in section
15861613
<xref target="idExamples" format="counter"></xref>.
15871614
</t>
@@ -1654,7 +1681,9 @@
16541681
The schemas at the following URI-encoded <xref target="RFC6901">JSON
16551682
Pointers</xref> (relative to the root schema) have the following
16561683
base URIs, and are identifiable by any listed URI in accordance with
1657-
Section <xref target="fragments" format="counter"></xref> above:
1684+
sections <xref target="fragments" format="counter"></xref> and
1685+
<xref target="embedded" format="counter"></xref> above. As previously
1686+
noted, support for non-canonical URIs is OPTIONAL.
16581687
</t>
16591688
<t>
16601689
<list style="hanging">
@@ -1685,7 +1714,7 @@
16851714
<t hangText="canonical URI with pointer fragment">
16861715
https://example.com/other.json#
16871716
</t>
1688-
<t hangText="Fragment relative to root.json (undefined behavior)">
1717+
<t hangText="non-canonical URI with fragment relative to root.json">
16891718
https://example.com/root.json#/$defs/B
16901719
</t>
16911720
</list>
@@ -1699,7 +1728,7 @@
16991728
<t hangText="canonical URI with pointer fragment">
17001729
https://example.com/other.json#/$defs/X
17011730
</t>
1702-
<t hangText="Fragment relative to root.json (undefined behavior)">
1731+
<t hangText="non-canonical URI with fragment relative to root.json">
17031732
https://example.com/root.json#/$defs/B/$defs/X
17041733
</t>
17051734
</list>
@@ -1713,10 +1742,10 @@
17131742
<t hangText="canonical URI with pointer fragment">
17141743
https://example.com/t/inner.json#
17151744
</t>
1716-
<t hangText="Fragment relative to other.json (undefined behavior)">
1745+
<t hangText="non-canonical URI with fragment relative to other.json">
17171746
https://example.com/other.json#/$defs/Y
17181747
</t>
1719-
<t hangText="Fragment relative to root.json (undefined behavior)">
1748+
<t hangText="non-canonical URI with fragment relative to root.json">
17201749
https://example.com/root.json#/$defs/B/$defs/Y
17211750
</t>
17221751
</list>
@@ -1729,7 +1758,7 @@
17291758
<t hangText="canonical URI with pointer fragment">
17301759
urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f#
17311760
</t>
1732-
<t hangText="Fragment relative to root.json (undefined behavior)">
1761+
<t hangText="non-canonical URI with fragment relative to root.json">
17331762
https://example.com/root.json#/$defs/C
17341763
</t>
17351764
</list>

0 commit comments

Comments
 (0)