Skip to content

Commit d605d04

Browse files
handrewshandrews
authored
Merge pull request #610 from handrews/annot-collect
Initial description of annotation collection
2 parents b2f3409 + 9aaa8b5 commit d605d04

File tree

1 file changed

+186
-1
lines changed

1 file changed

+186
-1
lines changed

‎jsonschema-core.xml

Lines changed: 186 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1140,6 +1140,191 @@
11401140
</t>
11411141
</section>
11421142

1143+
<section title="Collecting Annotations">
1144+
<t>
1145+
<cref>
1146+
The exact structure and format of the information collected is TBD,
1147+
but will be defined before the next draft. Some details of this
1148+
section may change as a result, but the overall process is expected
1149+
to remain the same. See GitHub issue #396 to track progress.
1150+
</cref>
1151+
</t>
1152+
<t>
1153+
Annotations are collected by keywords that explicitly define
1154+
annotation-collecting behavior. Note that boolean schemas cannot
1155+
produce annotations as they do not make use of keywords.
1156+
</t>
1157+
<t>
1158+
A collected annotation MUST include the following information:
1159+
<list>
1160+
<t>
1161+
The name of the keyword that produces the annotation
1162+
</t>
1163+
<t>
1164+
The instance location to which it is attached, as a JSON Pointer
1165+
</t>
1166+
<t>
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>
1173+
</t>
1174+
<t>
1175+
The attached value(s)
1176+
</t>
1177+
</list>
1178+
</t>
1179+
<t>
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.
1184+
</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>
1281+
<section title="Annotations and Assertions">
1282+
<t>
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.
1286+
</t>
1287+
<t>
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.
1314+
</t>
1315+
</section>
1316+
<section title="Annotations and Applicators">
1317+
<t>
1318+
In addition to possibly defining annotation results of their own,
1319+
applicator keywords aggregate the annotations collected in their
1320+
subschema(s) or referenced schema(s). The rules for aggregating
1321+
annotation values are defined by each annotation keyword, and are
1322+
not directly affected by the logic used for combining assertion
1323+
results.
1324+
</t>
1325+
</section>
1326+
</section>
1327+
11431328
<section title="A Vocabulary for Applying Subschemas">
11441329
<t>
11451330
This section defines a vocabulary of applicator keywords that
@@ -1213,7 +1398,7 @@
12131398
</t>
12141399
</section>
12151400

1216-
<section title="not">
1401+
<section title="not" anchor="not">
12171402
<t>
12181403
This keyword's value MUST be a valid JSON Schema.
12191404
</t>

0 commit comments

Comments
 (0)