|
1066 | 1066 | </t>
|
1067 | 1067 | </section>
|
1068 | 1068 |
|
| 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 | + |
1069 | 1157 | <section title="A Vocabulary for Applying Subschemas">
|
1070 | 1158 | <t>
|
1071 | 1159 | This section defines a vocabulary of applicator keywords that
|
|
1139 | 1227 | </t>
|
1140 | 1228 | </section>
|
1141 | 1229 |
|
1142 |
| - <section title="not"> |
| 1230 | + <section title="not" anchor="not"> |
1143 | 1231 | <t>
|
1144 | 1232 | This keyword's value MUST be a valid JSON Schema.
|
1145 | 1233 | </t>
|
|
0 commit comments