Skip to content

Commit 9aaa8b5

Browse files
handrewshandrews
committed
Incorporate feedback on annotation collection
* Simplify wording around annotation keywords and names * Remove potentially confusing details about the collection process, particularly regarding applicators such as "not" * Add an example to clarify why the handling of multiple annotation values is deferred to applications, and show how applications might make use of this flexibility.
1 parent c0b8ac6 commit 9aaa8b5

File tree

1 file changed

+136
-39
lines changed

1 file changed

+136
-39
lines changed

‎jsonschema-core.xml

Lines changed: 136 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1158,50 +1158,159 @@
11581158
A collected annotation MUST include the following information:
11591159
<list>
11601160
<t>
1161-
The name of the annotation, which MUST be identical to the keyword
1162-
that defines that annotation.
1161+
The name of the keyword that produces the annotation
11631162
</t>
11641163
<t>
11651164
The instance location to which it is attached, as a JSON Pointer
11661165
</t>
11671166
<t>
1168-
The schema location of the attaching keyword, as a list of URIs
1169-
constructed as described below
1167+
The absolute schema location of the attaching keyword, as a URI
1168+
</t>
1169+
<t>
1170+
The schema location path, indicating how reference keywords
1171+
such as "$ref" were followed to reach the absolute schema location
1172+
<cref>The exact format of this path is TBD, again see issue #396</cref>
11701173
</t>
11711174
<t>
11721175
The attached value(s)
11731176
</t>
11741177
</list>
11751178
</t>
11761179
<t>
1177-
If multiple schema locations attach values to the same instance location,
1178-
and the annotation defines a process for combining such values, then the
1179-
combined value MUST also be associated with the instance location.
1180-
</t>
1181-
<t>
1182-
Applications MAY make decisions on which of multiple annotation values
1183-
to use based on the schema location that contributed the value.
1184-
This is intended to allow flexible usage. Collecting the schema location
1185-
facilites such usage.
1186-
</t>
1187-
<t>
1188-
For example, one application may consider a "description" annotation that is
1189-
in the same schema object as a "$ref" to override any "description" in the
1190-
reference's target schema. A different application may prefer to concatenate
1191-
all "description" annotations based on whatever ordering it defines.
1180+
If the same keyword attaches values from multiple schema locations
1181+
to the same instance location, and the annotation defines a process
1182+
for combining such values, then the combined value MUST also be associated
1183+
with the instance location.
11921184
</t>
1185+
<section title="Distinguishing Among Multiple Values">
1186+
<t>
1187+
Applications MAY make decisions on which of multiple annotation values
1188+
to use based on the schema location that contributed the value.
1189+
This is intended to allow flexible usage. Collecting the schema location
1190+
facilitates such usage.
1191+
</t>
1192+
<t>
1193+
For example, consider this schema, which uses annotations and assertions from
1194+
the <xref target="json-schema-validation">Validation specification</xref>:
1195+
</t>
1196+
<figure>
1197+
<preamble>
1198+
Note that some lines are wrapped for clarity.
1199+
</preamble>
1200+
<artwork>
1201+
<![CDATA[
1202+
{
1203+
"title": "Feature list",
1204+
"type": "array",
1205+
"items": [
1206+
{
1207+
"title": "Feature A",
1208+
"properties": {
1209+
"enabled": {
1210+
"$ref": "#/$defs/enabledToggle",
1211+
"default": true
1212+
}
1213+
}
1214+
},
1215+
{
1216+
"title": "Feature B",
1217+
"properties": {
1218+
"enabled": {
1219+
"description": "If set to null, Feature B
1220+
inherits the enabled
1221+
value from Feature A",
1222+
"$ref": "#/$defs/enabledToggle"
1223+
}
1224+
}
1225+
}
1226+
]
1227+
},
1228+
"$defs": {
1229+
"enabledToggle": {
1230+
"title": "Enabled",
1231+
"description": "Whether the feature is enabled (true),
1232+
disabled (false), or under
1233+
automatic control (null)",
1234+
"type": ["boolean", "null"],
1235+
"default": null
1236+
}
1237+
}
1238+
}
1239+
]]>
1240+
</artwork>
1241+
</figure>
1242+
<t>
1243+
In this example, both Feature A and Feature B make use of the re-usable
1244+
"enabledToggle" schema. That schema uses the "title", "description",
1245+
and "default" annotations, none of which define special behavior for
1246+
handling multiple values. Therefore the application has to decide how
1247+
to handle the additional "default" value for Feature A, and the additional
1248+
"description" value for Feature B.
1249+
</t>
1250+
<t>
1251+
The application programmer and the schema author need to agree on the
1252+
usage. For this example, let's assume that they agree that the most
1253+
specific "default" value will be used, and any additional, more generic
1254+
"default" values will be silently ignored. Let's also assume that they
1255+
agree that all "description" text is to be used, starting with the most
1256+
generic, and ending with the most specific. This requires the schema
1257+
author to write descriptions that work when combined in this way.
1258+
</t>
1259+
<t>
1260+
The application can use the schema location path to determine which
1261+
values are which. The values in the feature's immediate "enabled"
1262+
property schema are more specific, while the values under the re-usable
1263+
schema that is referred to with "$ref" are more generic. The schema
1264+
location path will show whether each value was found by crossing a
1265+
"$ref" or not.
1266+
</t>
1267+
<t>
1268+
Feature A will therefore use a default value of true, while Feature B
1269+
will use the generic default value of null. Feature A will only
1270+
have the generic description from the "enabledToggle" schema, while
1271+
Feature B will use that description, and also append its locally
1272+
defined description that explains how to interpret a null value.
1273+
</t>
1274+
<t>
1275+
Note that there are other reasonable approaches that a different application
1276+
might take. For example, an application may consider the presence of
1277+
two different values for "default" to be an error, regardless of their
1278+
schema locations.
1279+
</t>
1280+
</section>
11931281
<section title="Annotations and Assertions">
11941282
<t>
1195-
If any keyword in a schema object produces a false assertion
1196-
result, then all annotations from all keywords in that schema
1197-
object, and any of its subschemas or referenced schemas, MUST
1198-
be discarded.
1283+
Schema objects that produce a false assertion result MUST NOT
1284+
produce any annotation results, whether from their own keywords
1285+
or from keywords in subschemas.
11991286
</t>
12001287
<t>
1201-
This may be due to an assertion keyword directly producing
1202-
a false result, or an applicator keyword producing a false
1203-
assertion result as the aggregate assertion result of
1204-
its subschema(s).
1288+
Note that the overall schema results may still include annotations
1289+
collected from other schema locations. Given this schema:
1290+
</t>
1291+
<figure>
1292+
<artwork>
1293+
<![CDATA[
1294+
{
1295+
"oneOf": [
1296+
{
1297+
"title": "Integer Value",
1298+
"type": "integer"
1299+
},
1300+
{
1301+
"title": "String Value",
1302+
"type": "string"
1303+
}
1304+
]
1305+
}
1306+
]]>
1307+
</artwork>
1308+
</figure>
1309+
<t>
1310+
And the instance <spanx style="verb">"This is a string"</spanx>, the
1311+
title annotation "Integer Value" is discarded because the type assertion
1312+
in that schema object fails. The title annotation "String Value"
1313+
is kept, as the instance passes the string type assertions.
12051314
</t>
12061315
</section>
12071316
<section title="Annotations and Applicators">
@@ -1213,18 +1322,6 @@
12131322
not directly affected by the logic used for combining assertion
12141323
results.
12151324
</t>
1216-
<t>
1217-
If, in the process of aggregating subscheama results, an applicator
1218-
keyword modifies a subschema's assertion result to be false, all
1219-
annotation keywords from that subschema MUST be discarded.
1220-
</t>
1221-
<t>
1222-
Note that this means that an applicator such as <xref target="not">"not"</xref>
1223-
will never produce annotation results: Either the subschema failed an
1224-
assertion and discarded its annotations before "not" processes them, or if
1225-
the subschema passed all assertions, "not" will invert that to a failure,
1226-
and then discard the annotations before producing its own result.
1227-
</t>
12281325
</section>
12291326
</section>
12301327

0 commit comments

Comments
 (0)