Skip to content

Commit 3365dc3

Browse files
committed
Split Keyword Behaviors in to better subsections
This does not change any text at all. The initial part of the Keyword Behaviors section is too long. Put some of the existing paragraphs into subsections on keyword interactions, and on default behaviors, which are very distinct topics. This left the paragraph on extension keywords orphaned, so I moved it up. The topic of extension keywords will be revisited in detail with the vocabulary changes, so it's best not to worry too much about exactly where this paragraph goes right now.
1 parent 09790c7 commit 3365dc3

File tree

1 file changed

+46
-42
lines changed

1 file changed

+46
-42
lines changed

jsonschema-core.xml

Lines changed: 46 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,13 @@
131131
Applicators apply subschemas to parts of the instance and combine
132132
their results.
133133
</t>
134+
<t>
135+
Extension keywords SHOULD stay within these categories, keeping in mind
136+
that annotations in particular are extremely flexible. Complex behavior
137+
is usually better delegated to applications on the basis of annotation
138+
data than implemented directly as schema keywords. However, extension
139+
keywords MAY define other behaviors for specialized purposes.
140+
</t>
134141
<t>
135142
Evaluating an instance against a schema involves processing all of the
136143
keywords in the schema against the appropriate locations within the instance.
@@ -145,48 +152,45 @@
145152
subschemas have been evaluated, although in some circumstance evaluation
146153
may be short-circuited due to assertion results.
147154
</t>
148-
<t>
149-
Keyword behavior MAY be defined in terms of the annotation results
150-
of <xref target="root">subschemas</xref> and/or adjacent keywords.
151-
Such keywords MUST NOT result in a circular dependency.
152-
Keywords MAY modify their behavior based on the presence or absence
153-
of another keyword in the same
154-
<xref target="schema-document">schema object</xref>.
155-
</t>
156-
<t>
157-
A missing keyword MUST NOT produce a false assertion result, MUST
158-
NOT produce annotation results, and MUST NOT cause any other schema
159-
to be evaluated as part of its own behavioral definition.
160-
However, given that missing keywords do not contribute annotations,
161-
the lack of annotation results may indirectly change the behavior
162-
of other keywords.
163-
</t>
164-
<t>
165-
In some cases, the missing keyword assertion behavior of a keyword is
166-
identical to that produced by a certain value, and keyword definitions
167-
SHOULD note such values where known. However, even if the value which
168-
produces the default behavior would produce annotation results if
169-
present, the default behavior still MUST NOT result in annotations.
170-
</t>
171-
<t>
172-
Because annotation collection can add significant cost in terms of both
173-
computation and memory, implementations MAY opt out of this feature.
174-
Keywords known to an implementation to have assertion or applicator behavior
175-
that depend on annotation results MUST then be treated as errors, unless
176-
an alternate implementation producing the same behavior is available.
177-
Keywords of this sort SHOULD describe reasonable alternate approaches
178-
when appropriate. This approach is demonstrated by the
179-
"<xref target="additionalItems" format="title"/>" and
180-
"<xref target="additionalProperties" format="title"/>" keywords in this
181-
document.
182-
</t>
183-
<t>
184-
Extension keywords SHOULD stay within these categories, keeping in mind
185-
that annotations in particular are extremely flexible. Complex behavior
186-
is usually better delegated to applications on the basis of annotation
187-
data than implemented directly as schema keywords. However, extension
188-
keywords MAY define other behaviors for specialized purposes.
189-
</t>
155+
<section title="Keyword Interactions">
156+
<t>
157+
Keyword behavior MAY be defined in terms of the annotation results
158+
of <xref target="root">subschemas</xref> and/or adjacent keywords.
159+
Such keywords MUST NOT result in a circular dependency.
160+
Keywords MAY modify their behavior based on the presence or absence
161+
of another keyword in the same
162+
<xref target="schema-document">schema object</xref>.
163+
</t>
164+
</section>
165+
<section title="Default Behaviors">
166+
<t>
167+
A missing keyword MUST NOT produce a false assertion result, MUST
168+
NOT produce annotation results, and MUST NOT cause any other schema
169+
to be evaluated as part of its own behavioral definition.
170+
However, given that missing keywords do not contribute annotations,
171+
the lack of annotation results may indirectly change the behavior
172+
of other keywords.
173+
</t>
174+
<t>
175+
In some cases, the missing keyword assertion behavior of a keyword is
176+
identical to that produced by a certain value, and keyword definitions
177+
SHOULD note such values where known. However, even if the value which
178+
produces the default behavior would produce annotation results if
179+
present, the default behavior still MUST NOT result in annotations.
180+
</t>
181+
<t>
182+
Because annotation collection can add significant cost in terms of both
183+
computation and memory, implementations MAY opt out of this feature.
184+
Keywords known to an implementation to have assertion or applicator behavior
185+
that depend on annotation results MUST then be treated as errors, unless
186+
an alternate implementation producing the same behavior is available.
187+
Keywords of this sort SHOULD describe reasonable alternate approaches
188+
when appropriate. This approach is demonstrated by the
189+
"<xref target="additionalItems" format="title"/>" and
190+
"<xref target="additionalProperties" format="title"/>" keywords in this
191+
document.
192+
</t>
193+
</section>
190194
<section title="Applicators" anchor="applicators">
191195
<t>
192196
Applicators allow for building more complex schemas than can be accomplished

0 commit comments

Comments
 (0)