Skip to content

Commit a5beb33

Browse files
handrewshandrews
authored
Merge pull request #424 from handrews/applicability
Define "applicability" and "attachment"
2 parents 0d16c05 + abc40aa commit a5beb33

File tree

2 files changed

+186
-126
lines changed

2 files changed

+186
-126
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 11 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -175,32 +175,6 @@
175175
relations for the instance, with URIs incorporating values from the instance.
176176
</postamble>
177177
</figure>
178-
179-
<section title="Interaction with validation">
180-
<t>
181-
Hyper-schema keywords can be applied when the instance is valid against
182-
the schema that includes those keywords.
183-
</t>
184-
<t>
185-
Hyper-schemas MUST NOT be applied to an instance if the instance fails to
186-
validate against the validation keywords within or containing the hyper-schema.
187-
Hyper-schema keywords in branches of an "anyOf", "oneOf", or "if"/"then"/"else"
188-
that do not validate, or in a "dependencies" subschema that is not relevant
189-
to the instance, MUST be ignored.
190-
</t>
191-
<t>
192-
Hyper-schema keywords in a subschema contained within a "not", at any depth,
193-
including any number of intervening additional "not" subschemas, MUST be
194-
ignored.
195-
</t>
196-
<t>
197-
If the subschema for a "contains" keyword contains hyper-schema keywords they
198-
MUST be applied to all array elements that validate against the schema. While
199-
finding a single validating element is sufficient to determine the validation
200-
outcome, when hyper-schema keywords are present, the subschema MUST be evaluated
201-
against all array elements.
202-
</t>
203-
</section>
204178
</section>
205179

206180
<section title="Meta-schema">
@@ -211,6 +185,17 @@
211185
</section>
212186

213187
<section title="Schema keywords">
188+
<t>
189+
Hyper-schema keywords can be applied when the instance is valid against
190+
the schema that includes those keywords, as outlined in
191+
<xref target="json-schema-validation">Section 10.1 of JSON Schema validation</xref>.
192+
</t>
193+
<t>
194+
When multiple subschemas are applicable to a given sub-instance, all "link"
195+
arrays MUST be concatenated, in any order, into a single array. Each object
196+
in the resulting array MUST retain its own list of applicable "base" values,
197+
in resolution order, from the same schema and any parent schemas.
198+
</t>
214199
<section title="base">
215200
<t>
216201
If present, this keyword is resolved against the current URI base that the

‎jsonschema-validation.xml

Lines changed: 175 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -770,106 +770,6 @@
770770
</section>
771771
</section>
772772

773-
<section title="Metadata keywords">
774-
<section title="definitions">
775-
<t>
776-
This keyword's value MUST be an object.
777-
Each member value of this object MUST be a valid JSON Schema.
778-
</t>
779-
<t>
780-
This keyword plays no role in validation per se. Its role is to provide
781-
a standardized location for schema authors to inline JSON Schemas into a
782-
more general schema.
783-
</t>
784-
785-
<t>
786-
As an example, here is a schema describing an array of positive
787-
integers, where the positive integer constraint is a subschema in
788-
"definitions":
789-
790-
<figure>
791-
<artwork>
792-
<![CDATA[
793-
{
794-
"type": "array",
795-
"items": { "$ref": "#/definitions/positiveInteger" },
796-
"definitions": {
797-
"positiveInteger": {
798-
"type": "integer",
799-
"exclusiveMinimum": 0
800-
}
801-
}
802-
}
803-
]]>
804-
</artwork>
805-
</figure>
806-
</t>
807-
</section>
808-
809-
<section title='"title" and "description"'>
810-
<t>
811-
The value of both of these keywords MUST be a string.
812-
</t>
813-
<t>
814-
Both of these keywords can be used to decorate a user interface with
815-
information about the data produced by this user interface. A title will
816-
preferably be short, whereas a description will provide explanation about
817-
the purpose of the instance described by this schema.
818-
</t>
819-
</section>
820-
821-
<section title='"default"'>
822-
<t>
823-
There are no restrictions placed on the value of this keyword.
824-
</t>
825-
<t>
826-
This keyword can be used to supply a default JSON value associated with a
827-
particular schema. It is RECOMMENDED that a default value be valid against
828-
the associated schema.
829-
</t>
830-
</section>
831-
832-
<section title='"readOnly"'>
833-
<t>
834-
The value of this keyword MUST be a boolean.
835-
</t>
836-
<t>
837-
If it has a value of boolean true, this keyword indicates that the value of the
838-
instance is managed exclusively by the owning authority, and attempts by an
839-
application to modify the value of this property are expected to be ignored or
840-
rejected by that owning authority.
841-
</t>
842-
<t>
843-
For example, this property would be used to mark a database-generated serial
844-
number as read-only.
845-
</t>
846-
<t>
847-
This keyword can be used to assist in user interface instance generation.
848-
</t>
849-
<t>
850-
Omitting this keyword has the same behavior as a value of false.
851-
</t>
852-
</section>
853-
854-
<section title='"examples"'>
855-
<t>
856-
The value of this keyword MUST be an array.
857-
There are no restrictions placed on the values within the array.
858-
</t>
859-
<t>
860-
This keyword can be used to provide sample JSON values associated with a
861-
particular schema, for the purpose of illustrating usage. It is
862-
RECOMMENDED that these values be valid against the associated schema.
863-
</t>
864-
<t>
865-
Implementations MAY use the value of "default", if present, as
866-
an additional example. If "examples" is absent, "default"
867-
MAY still be used in this manner.
868-
</t>
869-
</section>
870-
871-
</section>
872-
873773
<section title='Semantic validation with "format"'>
874774

875775
<section title="Foreword">
@@ -1210,6 +1110,181 @@
12101110

12111111
</section>
12121112

1113+
<section title='Schema re-use with "definitions"'>
1114+
<t>
1115+
The "definitions" keywords provides a standardized location for schema
1116+
authors to inline re-usable JSON Schemas into a more general schema.
1117+
The keyword does not directly affect the validation result.
1118+
</t>
1119+
<t>
1120+
This keyword's value MUST be an object.
1121+
Each member value of this object MUST be a valid JSON Schema.
1122+
</t>
1123+
<t>
1124+
As an example, here is a schema describing an array of positive
1125+
integers, where the positive integer constraint is a subschema in
1126+
"definitions":
1127+
1128+
<figure>
1129+
<artwork>
1130+
<![CDATA[
1131+
{
1132+
"type": "array",
1133+
"items": { "$ref": "#/definitions/positiveInteger" },
1134+
"definitions": {
1135+
"positiveInteger": {
1136+
"type": "integer",
1137+
"exclusiveMinimum": 0
1138+
}
1139+
}
1140+
}
1141+
]]>
1142+
</artwork>
1143+
</figure>
1144+
</t>
1145+
</section>
1146+
1147+
<section title="Schema annotations and extension vocabularies">
1148+
<t>
1149+
Schema validation is a useful mechanism for annotating instance data
1150+
with additional information. This section describes the rules for
1151+
determining when and how annotations apply to an instance, and specifies
1152+
a small general-purpose annotation vocabulary.
1153+
</t>
1154+
<t>
1155+
Additional vocabularies SHOULD make use of this mechanism for applying
1156+
their keywords to instances.
1157+
</t>
1158+
<section title="Applicability and attachment">
1159+
<t>
1160+
Annotations can be applied to an instance when it is valid against
1161+
the schema that includes the annotation keywords. For any given location
1162+
in the instance (referred to as a sub-instance), each (sub)schema against
1163+
which it successfully validates is considered to be <spanx>applicable</spanx>
1164+
to that sub-instance. The (sub)schema is said to be <spanx>attached</spanx>
1165+
to each sub-instance to which it applies.
1166+
</t>
1167+
<t>
1168+
A validation implementation MAY choose to implement determining subschema
1169+
applicability and providing access to the value(s) of applicable annotation
1170+
keywords. Implementation of this feature MAY instead be done separately.
1171+
</t>
1172+
<t>
1173+
Since many subschemas can be applicable to any single sub-instance, each
1174+
annotation keyword or vocabulary needs to specify how to handle multiple
1175+
occurrences with different values. In the absence of keyword-specific
1176+
handling rules, an implementation MUST collect all values and make them
1177+
available as a data structure in which order is not significant and items
1178+
need not be unique.
1179+
</t>
1180+
<section title="Combinatoric and conditional schemas">
1181+
<t>
1182+
Annotations in branches of an "anyOf", "oneOf", or "if"/"then"/"else"
1183+
that do not validate, or in a "dependencies" subschema that is not relevant
1184+
to the instance, MUST be ignored.
1185+
</t>
1186+
<t>
1187+
Annotations in a subschema contained within a "not", at any depth,
1188+
including any number of intervening additional "not" subschemas, MUST be
1189+
ignored.
1190+
</t>
1191+
</section>
1192+
<section title="Annotations and short-circuit validation">
1193+
<t>
1194+
Schema keywords MUST be applied to all possible sub-instances when
1195+
considering annotations, even if such application can be short-circuited
1196+
when only the overall validation result is needed.
1197+
</t>
1198+
<t>
1199+
An example of this is the "contains" keyword, which need only be evaluated
1200+
against array elements until it produces at least one successful outcome
1201+
in order to be implemented. However, when annotations are considered,
1202+
it must be checked against every array element, and the annotations MUST
1203+
be applied to every element that successfully validates against the
1204+
"contains" susbschema.
1205+
</t>
1206+
</section>
1207+
</section>
1208+
1209+
<section title="Basic annotation keywords">
1210+
<t>
1211+
These general-purpose annotation keywords provide commonly used information
1212+
for documentation and user interface display purposes. They are not intended
1213+
to form a comprehensive set of features. Rather, additional vocabularies
1214+
can be defined for more complex annotation-based applications.
1215+
</t>
1216+
<section title='"title" and "description"'>
1217+
<t>
1218+
The value of both of these keywords MUST be a string.
1219+
</t>
1220+
<t>
1221+
Both of these keywords can be used to decorate a user interface with
1222+
information about the data produced by this user interface. A title will
1223+
preferably be short, whereas a description will provide explanation about
1224+
the purpose of the instance described by this schema.
1225+
</t>
1226+
</section>
1227+
1228+
<section title='"default"'>
1229+
<t>
1230+
There are no restrictions placed on the value of this keyword. When
1231+
multiple occurrences of this keyword are applicable to a single
1232+
sub-instance, implementations SHOULD remove duplicates.
1233+
</t>
1234+
<t>
1235+
This keyword can be used to supply a default JSON value associated with a
1236+
particular schema. It is RECOMMENDED that a default value be valid against
1237+
the associated schema.
1238+
</t>
1239+
</section>
1240+
1241+
<section title='"readOnly"'>
1242+
<t>
1243+
The value of this keyword MUST be a boolean. When multiple occurrences
1244+
of this keyword are applicable to a single sub-instance, the resulting
1245+
value MUST be true if any occurrence specifies a true value, and MUST
1246+
be false otherwise.
1247+
</t>
1248+
<t>
1249+
If it has a value of boolean true, this keyword indicates that the value
1250+
of the instance is managed exclusively by the owning authority, and
1251+
attempts by an application to modify the value of this property are
1252+
expected to be ignored or rejected by that owning authority.
1253+
</t>
1254+
<t>
1255+
For example, this property would be used to mark a database-generated serial
1256+
number as read-only.
1257+
</t>
1258+
<t>
1259+
This keyword can be used to assist in user interface instance generation.
1260+
</t>
1261+
<t>
1262+
Omitting this keyword has the same behavior as a value of false.
1263+
</t>
1264+
</section>
1265+
1266+
<section title='"examples"'>
1267+
<t>
1268+
The value of this keyword MUST be an array.
1269+
There are no restrictions placed on the values within the array.
1270+
When multiple occurrences of this keyword are applicable to a single
1271+
sub-instance, implementations MUST provide a flat array of all
1272+
values rather than an array of arrays.
1273+
</t>
1274+
<t>
1275+
This keyword can be used to provide sample JSON values associated with a
1276+
particular schema, for the purpose of illustrating usage. It is
1277+
RECOMMENDED that these values be valid against the associated schema.
1278+
</t>
1279+
<t>
1280+
Implementations MAY use the value(s) of "default", if present, as
1281+
an additional example. If "examples" is absent, "default"
1282+
MAY still be used in this manner.
1283+
</t>
1284+
</section>
1285+
</section>
1286+
</section>
1287+
12131288
<section title="Security considerations">
12141289
<t>
12151290
JSON Schema validation defines a vocabulary for JSON Schema core and concerns all

0 commit comments

Comments
 (0)