Skip to content

Commit

Permalink
Merge pull request #1 from Acubed/aaa-uri-fix
Browse files Browse the repository at this point in the history 
s/resolution scope/base URI/
  • Loading branch information
@awwright
awwright committed Oct 28, 2015
2 parents 0ad7320 + f3f6171 commit d62538f
Show file tree
Hide file tree
Showing 2 changed files with 34 additions and 41 deletions.
71 changes: 32 additions & 39 deletions jsonschema-core.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>

Expand Down Expand Up @@ -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
Expand All @@ -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>

Expand Down Expand Up @@ -375,62 +377,52 @@

</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
mechanism for schema addressing. It extends this specification in two ways:

<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"
},
Expand All @@ -444,7 +436,7 @@
}
},
"schema3": {
"id": "some://where.else/completely#"
"id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f"
}
}
]]>
Expand All @@ -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>

Expand Down Expand Up @@ -504,15 +496,15 @@

<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:

<list>
<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>
Expand All @@ -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>
Expand Down Expand Up @@ -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>
Expand Down
4 changes: 2 additions & 2 deletions jsonschema-hyperschema.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>

Expand Down

0 comments on commit d62538f

Please sign in to comment.