@@ -73,7 +73,7 @@ This can be used anywhere a schema is expected. You will always use ``$ref`` as
73
73
the only key in an object: any other keys you put there will be ignored by the
74
74
validator.
75
75
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
77
77
"fragment" or "named anchor") is in a format called `JSON Pointer
78
78
<https://tools.ietf.org/html/rfc6901> `__.
79
79
@@ -91,7 +91,7 @@ the keys in the objects in the document. Therefore, in our example
91
91
2) find the value of the key ``"definitions" ``
92
92
3) within that object, find the value of the key ``"address" ``
93
93
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
95
95
include your definitions in separate files, you can also do that. For
96
96
example::
97
97
@@ -143,12 +143,12 @@ schema for a customer:
143
143
144
144
.. note ::
145
145
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.
152
152
153
153
Recursion
154
154
`````````
@@ -236,16 +236,16 @@ infinite loop in the resolver, and is explicitly disallowed.
236
236
The $id property
237
237
----------------
238
238
239
- The ``$id `` property is a URI that serves two purposes:
239
+ The ``$id `` property is a URI-reference that serves two purposes:
240
240
241
241
- It declares a unique identifier for the schema.
242
242
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.
244
244
245
245
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:
249
249
250
250
.. schema_example ::
251
251
@@ -255,17 +255,20 @@ This provides a unique identifier for the schema, as well as, in most
255
255
cases, indicating where it may be downloaded.
256
256
257
257
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.
259
259
For example, if you had:
260
260
261
261
.. schema_example ::
262
262
263
263
{ "$ref": "person.json" }
264
264
265
265
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
267
267
``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
+
269
272
270
273
|draft6 |
271
274
0 commit comments