Skip to content
This repository was archived by the owner on Nov 3, 2023. It is now read-only.

Commit ecb32a5

Browse files
authored
Merge pull request #105 from AdamWill/uri-reference
Correct some uses of 'URI' to 'URI reference' in structuring
2 parents e404f65 + 1c5fb9a commit ecb32a5

File tree

1 file changed

+19
-16
lines changed

1 file changed

+19
-16
lines changed

source/structuring.rst

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ This can be used anywhere a schema is expected. You will always use ``$ref`` as
7373
the only key in an object: any other keys you put there will be ignored by the
7474
validator.
7575

76-
The value of ``$ref`` is a URI, and the part after ``#`` sign (the
76+
The value of ``$ref`` is a URI-reference, and the part after ``#`` sign (the
7777
"fragment" or "named anchor") is in a format called `JSON Pointer
7878
<https://tools.ietf.org/html/rfc6901>`__.
7979

@@ -91,7 +91,7 @@ the keys in the objects in the document. Therefore, in our example
9191
2) find the value of the key ``"definitions"``
9292
3) within that object, find the value of the key ``"address"``
9393

94-
``$ref`` can also be a relative or absolute URI, so if you prefer to
94+
``$ref`` can resolve to a URI that references another file, so if you prefer to
9595
include your definitions in separate files, you can also do that. For
9696
example::
9797

@@ -143,12 +143,12 @@ schema for a customer:
143143

144144
.. note::
145145

146-
Even though the value of a ``$ref`` is a URI, it is not a network locator,
147-
only an identifier. This means that the schema doesn't need to be accessible
148-
at that URI, but it may be. It is basically up to the validator
149-
implementation how external schema URIs will be handled, but one should not
150-
assume the validator will fetch network resources indicated in ``$ref``
151-
values.
146+
Even though the value of a ``$ref`` is a URI-reference, it is not a network
147+
locator, only an identifier. This means that the schema doesn't need to be
148+
accessible at the resolved URI, but it may be. It is basically up to the
149+
validator implementation how external schema URIs will be handled, but one
150+
should not assume the validator will fetch network resources indicated in
151+
``$ref`` values.
152152

153153
Recursion
154154
`````````
@@ -236,16 +236,16 @@ infinite loop in the resolver, and is explicitly disallowed.
236236
The $id property
237237
----------------
238238

239-
The ``$id`` property is a URI that serves two purposes:
239+
The ``$id`` property is a URI-reference that serves two purposes:
240240

241241
- It declares a unique identifier for the schema.
242242

243-
- It declares a base URI against which ``$ref`` URIs are resolved.
243+
- It declares a base URI against which ``$ref`` URI-references are resolved.
244244

245245
It is best practice that every top-level schema should set ``$id`` to an
246-
absolute URI, with a domain that you control. For example, if you own the
247-
``foo.bar`` domain, and you had a schema for addresses, you may set its ``$id``
248-
as follows:
246+
absolute-URI (not a relative reference), with a domain that you control. For
247+
example, if you own the ``foo.bar`` domain, and you had a schema for addresses,
248+
you may set its ``$id`` as follows:
249249

250250
.. schema_example::
251251

@@ -255,17 +255,20 @@ This provides a unique identifier for the schema, as well as, in most
255255
cases, indicating where it may be downloaded.
256256

257257
But be aware of the second purpose of the ``$id`` property: that it
258-
declares a base URL for relative ``$ref`` URLs elsewhere in the file.
258+
declares a base URI for ``$ref`` URI-references elsewhere in the file.
259259
For example, if you had:
260260

261261
.. schema_example::
262262

263263
{ "$ref": "person.json" }
264264

265265
in the same file, a JSON schema validation library that supported network
266-
fetching would fetch ``person.json`` from
266+
fetching may fetch ``person.json`` from
267267
``http://foo.bar/schemas/person.json``, even if ``address.json`` was loaded from
268-
somewhere else, such as the local filesystem.
268+
somewhere else, such as the local filesystem. The drafts do not define this
269+
area of behaviour very clearly, and validator implementations may vary in
270+
exactly how they try to locate the referenced schema.
271+
269272

270273
|draft6|
271274

0 commit comments

Comments
 (0)