diff --git a/jsonschema-core.xml b/jsonschema-core.xml
index 61162f05..adfa19cf 100644
--- a/jsonschema-core.xml
+++ b/jsonschema-core.xml
@@ -176,6 +176,7 @@
<section title="JSON Schema primitive types">
<t>
JSON Schema defines seven primitive types for JSON values:
+ <!-- TODO integer and number are both the same syntax, integer is just a subset -->
<list style="hanging">
<t hangText="array">A JSON array.</t>
<t hangText="boolean">A JSON boolean.</t>
@@ -221,7 +222,7 @@
</t>
<t>
- An instance may also be referred to as "JSON instance", or "JSON data".
+ An instance may also be referred to as a "JSON instance", "JSON data", or "JSON document".
</t>
</section>
@@ -333,6 +334,7 @@
<section title='The "$schema" keyword'>
<section title="Purpose">
+ <!-- TODO a custom $schema keyword might also be used to enforce minimum required functionality of a validator -->
<t>
The "$schema" keyword is both used as a JSON Schema version identifier and the
location of a resource which is itself a JSON Schema, which describes any schema
@@ -342,9 +344,9 @@
<t>
This keyword SHOULD be located at the root of a JSON Schema. The value of this
keyword MUST be a <xref target="RFC3986">URI</xref> and a valid <xref
- target="json-reference">JSON Reference</xref>; this URI MUST be both absolute
- and normalized. The resource located at this URI MUST successfully describe
- itself. It is RECOMMENDED that schema authors include this keyword in their
+ target="json-reference">JSON Reference</xref>; this URI MUST be normalized.
+ The resource identified by this URI MUST successfully describe the current
+ schema document. It is RECOMMENDED that schema authors include this keyword in their
schemas.
</t>
@@ -375,7 +377,7 @@
</section>
- <section title="URI resolution scopes and dereferencing">
+ <section title="Base URI and dereferencing">
<section title="Definition">
<t>
JSON Schema uses <xref target="json-reference">JSON Reference</xref> as a
@@ -383,54 +385,44 @@
<list>
<t>JSON Schema offers facilities to alter the base URI against which a
- reference must resolve by the means of the "id" keyword;</t>
+ URI reference must resolve by the means of the "id" keyword;</t>
<t>it offers schemas a mechanism to declare their own URIs, placing no limits on the structure of the URI</t>
</list>
</t>
<t>
- Altering the URI within a schema is called defining a new resolution scope.
- The initial resolution scope of a schema is the URI of the schema itself, or a suitable substitute URI if none is known.
+ <!-- TODO: RFC3986 defines exactly how to do this -->
+ The initial base URI of a schema is the URI of the schema itself, or a suitable substitute URI if none is known.
</t>
</section>
- <section title='URI resolution scope alteration with the "id" keyword'>
-
+ <section title='Base URI alteration with the "id" keyword'>
<section title="Valid values">
<t>
- The value for this keyword MUST be a string, and MUST be a valid URI (relative or absolute).
+ The value for this keyword MUST be a string, and MUST be a valid URI-reference [RFC3986].
This URI SHOULD be normalized, and SHOULD NOT be an empty fragment (#) or the empty string.
</t>
</section>
<section title="Usage">
<t>
- The "id" keyword is used to alter the resolution scope.
- When an id is encountered, an implementation MUST resolve this id against
- the most immediate parent scope. The resolved URI will be the new resolution
- scope for this subschema and all its children, until another "id" is
- encountered.
+ The "id" keyword defines the URI of the schema and the base URI that other URI references within
+ the schema are resolved against. The "id" keyword itself is resolved against a base URI as
+ specified in [RFC3986].
</t>
-
<t>
- When using "id" to alter resolution scopes, schema authors SHOULD ensure
- that resolution scopes are unique within the schema.
+ The outermost schema of a JSON Schema document SHOULD be an absolute-URI (containing a scheme, but no fragment)
+ or an absolute-URI with an empty fragment.
</t>
-
<t>
- This schema will be taken as an example:
+ For example:
</t>
-
- <!--
- FIXME: http again as a scheme, maybe another one? It can be any scheme after
- all
- -->
<figure>
<artwork>
<![CDATA[
{
- "id": "http://x.y.z/rootschema.json#",
+ "id": "http://example.com/rootschema.json#",
"schema1": {
"id": "#foo"
},
@@ -444,7 +436,7 @@
}
},
"schema3": {
- "id": "some://where.else/completely#"
+ "id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f"
}
}
]]>
@@ -454,15 +446,15 @@
<t>
Subschemas at the following URI-encoded <xref target="json-pointer">JSON
Pointer</xref>s (starting from the root schema) define the following
- resolution scopes:
-
+ base URIs:
+
<list style="hanging">
- <t hangText="# (document root)">http://x.y.z/rootschema.json#</t>
- <t hangText="#/schema1">http://x.y.z/rootschema.json#foo</t>
- <t hangText="#/schema2">http://x.y.z/otherschema.json#</t>
- <t hangText="#/schema2/nested">http://x.y.z/otherschema.json#bar</t>
- <t hangText="#/schema2/alsonested">http://x.y.z/t/inner.json#a</t>
- <t hangText="#/schema3">some://where.else/completely#</t>
+ <t hangText="# (document root)">http://example.com/rootschema.json#</t>
+ <t hangText="#/schema1">http://example.com/rootschema.json#foo</t>
+ <t hangText="#/schema2">http://example.com/otherschema.json#</t>
+ <t hangText="#/schema2/nested">http://example.com/otherschema.json#bar</t>
+ <t hangText="#/schema2/alsonested">http://example.com/t/inner.json#a</t>
+ <t hangText="#/schema3">urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f</t>
</list>
</t>
@@ -504,7 +496,7 @@
<t>
When an implementation encounters the "schema1" reference, it resolves it
- against the most immediate parent scope, leading to URI
+ against the current base URI, leading to URI
"http://my.site/schema1#". The way to process this URI will differ
according to the chosen dereferencing mode:
@@ -512,7 +504,7 @@
<t>if canonical dereferencing is used, the implementation will
dereference this URI, and fetch the content at this URI;</t>
<t>if inline dereferencing is used, the implementation MAY notice that
- URI scope "http://my.site/schema1#" is already defined within the
+ the base URI "http://my.site/schema1#" is already defined within the
schema, and choose to use the appropriate subschema.</t>
</list>
</t>
@@ -521,7 +513,7 @@
<section title="Inline dereferencing and fragments">
<t>
- When using inline dereferencing, a resolution scope may lead to a URI which
+ When using inline dereferencing, a base URI may lead to a URI which
has a non-empty fragment part which is not a JSON Pointer, as in this
example:
</t>
@@ -576,6 +568,7 @@
</t>
<section title='Correlation by means of the "Link" header'>
+ <!-- HTTP linking is referenced by specs that have nothing to do with HTTP, so this isn't always the case -->
<t>
It is RECOMMENDED that instances be associated with JSON Schemas using the link relation "describedby", as defined by <xref target="RFC5988">RFC 5988, section 5.3</xref>.
</t>
diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml
index 507a706b..1c85feea 100644
--- a/jsonschema-hyperschema.xml
+++ b/jsonschema-hyperschema.xml
@@ -386,7 +386,7 @@
<section title="pathStart">
<t>
This property is a URI that defines what the instance's URI MUST start with in order to validate.
- The value of the "pathStart" property MUST be resolved relative to the closest URI Resolution Scope (as defined in the <xref target="json-schema-core">JSON Schema core specification</xref>), using the rules from <xref target="RFC3986">RFC 3986, Sec 5</xref>.
+ The value of the "pathStart" property MUST be resolved relative to the current URI base (as defined in the <xref target="json-schema-core">JSON Schema core specification</xref>), using the rules from <xref target="RFC3986">RFC 3986, Sec 5</xref>.
</t>
<t>
@@ -416,7 +416,7 @@
<section title="href" anchor="href">
<t>
The value of the "href" link description property is a template used to determine the target URI of the related resource.
- The value of the instance property SHOULD be resolved as a URI-Reference per <xref target="RFC3986">RFC 3986</xref> and MAY be a relative reference to a URI.
+ The value of the instance property SHOULD be resolved as a URI-Reference per <xref target="RFC3986">RFC 3986</xref> and MAY be a URI reference.
The base URI to be used for relative URI resolution SHOULD be the URI used to retrieve the instance object (not the schema).
</t>