Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit d8ea3c7

Browse files
committedJun 17, 2018
Initial description of annotation collection
This covers the basics of annotation collection, and its interaction with assertions and applicators. It does not get into the exact output structure for annotation results, which is intentional. The goal is to establish the process, and then nail down the format once the process is solid.
1 parent bc2a042 commit d8ea3c7

File tree

1 file changed

+89
-1
lines changed

1 file changed

+89
-1
lines changed
 

‎jsonschema-core.xml

Lines changed: 89 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1066,6 +1066,94 @@
10661066
</t>
10671067
</section>
10681068

1069+
<section title="Collecting Annotations">
1070+
<t>
1071+
<cref>
1072+
The exact structure and format of the information collected is TBD,
1073+
but will be defined before the next draft. Some details of this
1074+
section may change as a result, but the overall process is expected
1075+
to remain the same. See GitHub issue #396 to track progress.
1076+
</cref>
1077+
</t>
1078+
<t>
1079+
Annotations are collected by keywords that explicitly define
1080+
annotation-collecting behavior. Note that boolean schemas cannot
1081+
produce annotations as they do not make use of keywords.
1082+
</t>
1083+
<t>
1084+
A collected annotation MUST include the following information:
1085+
<list>
1086+
<t>
1087+
The name of the annotation, which MUST be identical to the keyword
1088+
that defines that annotation.
1089+
</t>
1090+
<t>
1091+
The instance location to which it is attached, as a JSON Pointer
1092+
</t>
1093+
<t>
1094+
The schema location of the attaching keyword, as a list of URIs
1095+
constructed as described below
1096+
</t>
1097+
<t>
1098+
The attached value(s)
1099+
</t>
1100+
</list>
1101+
</t>
1102+
<t>
1103+
If multiple schema locations attach values to the same instance location,
1104+
and the annotation defines a process for combining such values, then the
1105+
combined value MUST also be associated with the instance location.
1106+
</t>
1107+
<t>
1108+
Applications MAY make decisions on which of multiple annotation values
1109+
to use based on the schema location that contributed the value.
1110+
This is intended to allow flexible usage. Collecting the schema location
1111+
facilites such usage.
1112+
</t>
1113+
<t>
1114+
For example, one application may consider a "description" annotation that is
1115+
in the same schema object as a "$ref" to override any "description" in the
1116+
reference's target schema. A different application may prefer to concatenate
1117+
all "description" annotations based on whatever ordering it defines.
1118+
</t>
1119+
<section title="Annotations and Assertions">
1120+
<t>
1121+
If any keyword in a schema object produces a false assertion
1122+
result, then all annotations from all keywords in that schema
1123+
object, and any of its subschemas or referenced schemas, MUST
1124+
be discarded.
1125+
</t>
1126+
<t>
1127+
This may be due to an assertion keyword directly producing
1128+
a false result, or an applicator keyword producing a false
1129+
assertion result as the aggregate assertion result of
1130+
its subschema(s).
1131+
</t>
1132+
</section>
1133+
<section title="Annotations and Applicators">
1134+
<t>
1135+
In addition to possibly defining annotation results of their own,
1136+
applicator keywords aggregate the annotations collected in their
1137+
subschema(s) or referenced schema(s). The rules for aggregating
1138+
annotation values are defined by each annotation keyword, and are
1139+
not directly affected by the logic used for combining assertion
1140+
results.
1141+
</t>
1142+
<t>
1143+
If, in the process of aggregating subscheama results, an applicator
1144+
keyword modifies a subschema's assertion result to be false, all
1145+
annotation keywords from that subschema MUST be discarded.
1146+
</t>
1147+
<t>
1148+
Note that this means that an applicator such as <xref target="not">"not"</xref>
1149+
will never produce annotation results: Either the subschema failed an
1150+
assertion and discarded its annotations before "not" processes them, or if
1151+
the subschema passed all assertions, "not" will invert that to a failure,
1152+
and then discard the annotations before producing its own result.
1153+
</t>
1154+
</section>
1155+
</section>
1156+
10691157
<section title="A Vocabulary for Applying Subschemas">
10701158
<t>
10711159
This section defines a vocabulary of applicator keywords that
@@ -1139,7 +1227,7 @@
11391227
</t>
11401228
</section>
11411229

1142-
<section title="not">
1230+
<section title="not" anchor="not">
11431231
<t>
11441232
This keyword's value MUST be a valid JSON Schema.
11451233
</t>

0 commit comments

Comments
 (0)
Please sign in to comment.