Skip to content

Explain referenced/referring schemas #609

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 2 commits into from
Jun 27, 2018
Merged

Explain referenced/referring schemas #609

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a6af98a
Explain refereced/referring schemas
handrews Jun 17, 2018
7e40945
Merge branch 'master' into referenced
handrews Jun 27, 2018
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
47 changes: 40 additions & 7 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,14 +195,19 @@
<xref target="schema-document">schema document</xref> begins by applying
the <xref target="root">root schema</xref> to the complete instance
document. From there, keywords known as applicators are used to determine
which additional subschemas are applied. Subschema may be applied in-place
to the current location, or to a child location. The subschemas may be all
or part of the keyword's value, or the keyword's value may identify one
or more schemas in a way defined by the keyword.
which additional schemas are applied. Such schemas may be applied in-place
to the current location, or to a child location.
</t>
<t>
Applicator keywords also define how subschema boolean
<xref target="assertions">assertion</xref>
The schemas to be applied may be present as subschemas comprising all or
part of the keyword's value. Alternatively, an applicator may refer to
a schema elsewhere in the same schema document, or in a different one.
The mechanism for identifying such referred schemas is defined by the
keyword.
</t>
<t>
Applicator keywords also define how subschema or referred schema
boolean <xref target="assertions">assertion</xref>
results are modified and/or combined to produce the boolean result
of the applicator. Applicators may apply any boolean logic operation
to the assertion results of subschemas, but MUST NOT introduce new
Expand Down Expand Up @@ -562,6 +567,34 @@
As with the root schema, a subschema is either an object or a boolean.
</t>
</section>
<section title="Referred and Referring Schemas" anchor="referred">
<t>
As noted in <xref target="applicators" />, an applicator keyword may
refer to a schema to be applied, rather than including it as a
subschema in the applicator's value. In such situations, the
schema being applied is known as the referred schema, while
the schema containing the applicator keyword is the referring schema.
</t>
<t>
While root schemas and subschemas are static concepts based on a
schema's position within a schema document, referred and referring
schemas are dynamic. Different pairs of schemas may find themselves
in various referred and referring arrangements during the evaluation
of an instance against a schema.
</t>
<t>
For some by-reference applicators, such as
<xref target="ref">"$ref"</xref>, the referred schema can be determined
by static analysis of the schema document. Others may take evaluation
context into account, and only be resolvable in the process of evaluating
with an instance.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great! Really adds clarity.

<cref>
Assuming some form of dynamic reference keyword is introduced
related to GitHub issue #558, this section will be updated
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to specify the repo here? If it's specified elsewhere in the doc, then probably not.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's linked in the "Note to Readers" section near the very top. In past CREFs we have just used issue numbers. I only reference issues in CREFs, and I don't worry about the formality of those as much as they're intended as asides that will be removed.

to make a concrete reference to that keyword for clarification.
</cref>
</t>
</section>
</section>

</section>
Expand Down Expand Up @@ -884,7 +917,7 @@
</section>
</section>

<section title='Schema References With "$ref"'>
<section title='Schema References With "$ref"' anchor="ref">
<t>
The "$ref" keyword is used to reference a schema, and provides the ability to
validate recursive structures through self-reference.
Expand Down