Skip to content

s/resolution scope/base URI/ #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 28, 2015
Merged

s/resolution scope/base URI/ #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
83a7a1b
s/resolution scope/base URI/
awwright Jun 24, 2015
851daec
Update/clean up wording for "id" section
awwright Aug 19, 2015
f3f6171
Merge branch 'master' of github.com:json-schema-org/json-schema-spec …
awwright Aug 19, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 32 additions & 39 deletions jsonschema-core.xml
View file
Open in desktop
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
Open in desktop
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