Skip to content

Commit 210ade2

Browse files
handrewshandrews
committed
Move applicability to validation/annotation
Rework the whole applicability/attachement concept from the hyper-schema specification into the validations specification, and establish it as the basis for working with annotation keywords. Update the annotation kewyords with clarifications on how to handle values across multiple applicable schemas. Update the hyper-schema specification to reference the now more generic description of validation interaction in the validation spec itself, with additional clarifications about how to handle combinign keywords from multiple applicable schemas. Split the "Metadata" section into a re-use section for just the "definitions" keyword, and a section on annotation and extensibility which defines applicability/attachement and defines the simple annotation vocabulary that was already present in the validation spec. Move all of that after "format" and "String-encoding non-JSON data" as those sections are both more closely aligned with validation than with either re-use or annotations.
1 parent d622fbb commit 210ade2

File tree

2 files changed

+186
-131
lines changed

2 files changed

+186
-131
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 11 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -174,37 +174,6 @@
174174
relations for the instance, with URIs incorporating values from the instance.
175175
</postamble>
176176
</figure>
177-
178-
<section title="Interaction with validation">
179-
<t>
180-
Hyper-schema keywords can be applied when the instance is valid against
181-
the schema that includes those keywords. For any given location in the
182-
instance, each (sub)schema against which it successfully validates is
183-
considered to be <spanx>applicable</spanx> to that location in the
184-
instance. The location is said to be the (sub)schema's point of
185-
<spanx>attachment</spanx>. This section provides the specific
186-
rules for determining applicabiity.
187-
</t>
188-
<t>
189-
Hyper-schemas MUST NOT be applied to an instance if the instance fails to
190-
validate against the validation keywords within or containing the hyper-schema.
191-
Hyper-schema keywords in branches of an "anyOf", "oneOf", or "if"/"then"/"else"
192-
that do not validate, or in a "dependencies" subschema that is not relevant
193-
to the instance, MUST be ignored.
194-
</t>
195-
<t>
196-
Hyper-schema keywords in a subschema contained within a "not", at any depth,
197-
including any number of intervening additional "not" subschemas, MUST be
198-
ignored.
199-
</t>
200-
<t>
201-
If the subschema for a "contains" keyword contains hyper-schema keywords they
202-
MUST be applied to all array elements that validate against the schema. While
203-
finding a single validating element is sufficient to determine the validation
204-
outcome, when hyper-schema keywords are present, the subschema MUST be evaluated
205-
against all array elements.
206-
</t>
207-
</section>
208177
</section>
209178

210179
<section title="Meta-schema">
@@ -215,6 +184,17 @@
215184
</section>
216185

217186
<section title="Schema keywords">
187+
<t>
188+
Hyper-schema keywords can be applied when the instance is valid against
189+
the schema that includes those keywords, as outlined in
190+
<xref target="json-schema-validation">Section 10.1 of JSON Schema validation</xref>.
191+
</t>
192+
<t>
193+
When multiple subschemas are applicable to a given sub-instance, all "link"
194+
arrays MUST be concatenated, in any order, into a single array. Each object
195+
in the resulting array MUST retain its own list of applicable "base" values
196+
from the same schema and any parent schemas.
197+
</t>
218198
<section title="base">
219199
<t>
220200
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
@@ -765,106 +765,6 @@
765765
</section>
766766
</section>
767767

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

870770
<section title="Foreword">
@@ -1163,6 +1063,181 @@
11631063

11641064
</section>
11651065

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

0 commit comments

Comments
 (0)