Skip to content

Commit 1ef7e00

Browse files
handrewshandrews
committed
Specify "format" requirements in vocabulary terms
Use the true vs false values of vocabulary declaration to indicate whether a schema author requires assertion behavior (such as because a keyword such as "oneOf" depends on such validation functioning correctly). Use a false value in the standard core+validation vocabulary, reflecting the historical lack of requirement for this keyword to be implemented. Define annotation behavior when the vocabulary is declared with false, to facilitate the recommended best practice of performing semantic validation in your application. While not the typical false vocabulary behavior, this seems like the best way to reframe the historically unpredictable behavior.
1 parent c12a08b commit 1ef7e00

File tree

3 files changed

+74
-23
lines changed

3 files changed

+74
-23
lines changed

‎hyper-schema.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
"https://json-schema.org/draft/2019-08/vocab/applicator": true,
77
"https://json-schema.org/draft/2019-08/vocab/validation": true,
88
"https://json-schema.org/draft/2019-08/vocab/meta-data": true,
9-
"https://json-schema.org/draft/2019-08/vocab/format": true,
9+
"https://json-schema.org/draft/2019-08/vocab/format": false,
1010
"https://json-schema.org/draft/2019-08/vocab/content": true,
1111
"https://json-schema.org/draft/2019-08/vocab/hyper-schema": true
1212
},

‎jsonschema-validation.xml

+72-21
Original file line numberDiff line numberDiff line change
@@ -174,14 +174,15 @@
174174

175175
</section>
176176

177-
<section title="Meta-Schema">
177+
<section title="Meta-Schema" anchor="meta-schema">
178178
<t>
179179
The current URI for the JSON Schema Validation meta-schema is
180180
<eref target="http://json-schema.org/draft/2019-08/schema#"/>.
181181
For schema author convenience, this meta-schema describes all vocabularies
182182
defined in this specification and the JSON Schema Core specification.
183183
Individual vocabulary and vocabulary meta-schema URIs are given for
184-
each section below.
184+
each section below. Certain vocabularies are optional to support, which
185+
is explained in detail in the relevant sections.
185186
</t>
186187
<t>
187188
Updated vocabulary and meta-schema URIs MAY be published between
@@ -503,28 +504,42 @@
503504
</section>
504505
</section>
505506

506-
<section title='A Vocabulary for Semantic Validation With "format"' anchor="format">
507+
<section title='A Vocabulary for Semantic Content With "format"' anchor="format">
507508

508509
<section title="Foreword">
509510
<t>
510-
Structural validation alone may be insufficient to validate that an instance
511-
meets all the requirements of an application. The "format" keyword is defined to
512-
allow interoperable semantic validation for a fixed subset of values which are
511+
Structural validation alone may be insufficient to allow an application to correctly
512+
utilize certain values. The "format" annotation keyword is defined to allow schema
513+
authors to convey semantic information for a fixed subset of values which are
513514
accurately described by authoritative resources, be they RFCs or other external
514515
specifications.
515516
</t>
516517

518+
<t>
519+
Implementations MAY treat "format" as an assertion in addition to an annotation,
520+
and attempt to validate the values conformance to the specified semantics.
521+
See the Implementation Requirements below for details.
522+
</t>
523+
517524
<t>
518525
The value of this keyword is called a format attribute. It MUST be a string. A
519526
format attribute can generally only validate a given set of instance types. If
520527
the type of the instance to validate is not in this set, validation for this
521-
format attribute and instance SHOULD succeed.
528+
format attribute and instance SHOULD succeed. All format attributes defined
529+
in this section apply to strings, but a format attribute can be specified
530+
to apply to any instance types defined in the data model defined in the
531+
<xref target="json-schema">core JSON Schema.</xref>
532+
<cref>
533+
Note that the "type" keyword in this specification defines an "integer" type
534+
which is not part of the data model. Therefore a format attribute can be
535+
limited to numbers, but not specifically to integers.
536+
</cref>
522537
</t>
523538

524539
<t>
525540
Meta-schemas that do not use "$vocabulary" SHOULD be considered to
526-
require this vocabulary as if its URI were present with a value of true,
527-
although see the Implementation Requirements below for details.
541+
utilize this vocabulary as if its URI were present with a value of false.
542+
See the Implementation Requirements below for details.
528543
</t>
529544
<t>
530545
The current URI for this vocabulary, known as the Format vocabulary, is:
@@ -539,26 +554,60 @@
539554

540555
<section title="Implementation Requirements">
541556
<t>
542-
The "format" keyword functions as both an annotation
543-
and as an assertion. While no special effort is required to
544-
implement it as an annotation conveying semantic meaning, implementing
545-
validation is non-trivial.
546-
</t>
547-
<t>
548-
Implementations MAY support the "format" keyword as a validation assertion.
549-
Should they choose to do so:
550-
557+
The "format" keyword functions as an annotation, and optionally as an assertion.
558+
Declaring the format vocabulary in "$vocabulary" with a value of true indicates
559+
that an implementation MUST treat the keyword as an assertion.
560+
This means that:
551561
<list>
552562
<t>they SHOULD implement validation for attributes defined below;</t>
553563
<t>they SHOULD offer an option to disable validation for this keyword.</t>
554564
</list>
565+
</t>
555566

567+
<t>
568+
Due to the complexity involved in fully validating some format attributes
569+
defined in this specification, implementations MAY provide only limited
570+
validation support for some format attributes. Implementations SHOULD
571+
document any such intentional limitations.
556572
</t>
557573

558574
<t>
559-
Implementations MAY add custom format attributes. Save for agreement between
560-
parties, schema authors SHALL NOT expect a peer implementation to support this
561-
keyword and/or custom format attributes.
575+
The <xref target="meta-schema">standard core and validation meta-schema</xref>
576+
includes this vocabulary in its "$vocabulary" keyword with a value of false,
577+
since by default implementations are not required to support this keyword
578+
as an assertion.
579+
</t>
580+
581+
<t>
582+
When the format vocabulary is declared with a value of false, an implementation
583+
SHOULD treat "format" as an annotation keyword, to facilitate applications which
584+
wish to do their own semantic validation.
585+
<cref>
586+
This is not the normal behavior for a vocabulary declared with false, which is
587+
why the requirement is a SHOULD. Implementations MAY ignore "format" entirely
588+
as is allowed by false vocabulary declarations. However, due to the long history
589+
of this keyword, treating it as something of a special case seems reasonable.
590+
This may be revised in future drafts based on feedback.
591+
</cref>
592+
</t>
593+
<t>
594+
Implementations MAY treat "format" as an assertion when the vocabulary is declared
595+
with false, as false vocabularies are optional rather than forbidden. However,
596+
as noted above, implementations SHOULD provide a way to disable such validation.
597+
</t>
598+
<t>
599+
Implementations MAY support custom format attributes. Save for agreement between
600+
parties, schema authors SHALL NOT expect a peer implementation to support such
601+
custom format attributes. An implementation MUST NOT fail
602+
validation or cease processing due to an unknown format attribute.
603+
If treating "format" as an annotation, implementations SHOULD collect both
604+
known and unknown format attribute values.
605+
</t>
606+
<t>
607+
Vocabularies do not support specifically declaring different value sets for keywords.
608+
Due to this limitation, and the historically uneven implementation of this keyword,
609+
it is RECOMMENDED to define additional keywords in a vocabulary rather than
610+
additional format attributes if interoperability is desired.
562611
</t>
563612
</section>
564613

@@ -1273,6 +1322,8 @@
12731322
<list style="hanging">
12741323
<t hangText="draft-handrews-json-schema-validation-02">
12751324
<list style="symbols">
1325+
<t>Update "format" implementation requirements in terms of vocabularies</t>
1326+
<t>Grouped keywords into formal vocabuarlies</t>
12761327
<t>Moved "definitions" to the core spec as "$defs"</t>
12771328
<t>Moved applicator keywords to the core spec</t>
12781329
<t>Renamed the array form of "dependencies" to "dependentRequired", moved the schema form to the core spec</t>

‎schema.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
"https://json-schema.org/draft/2019-08/vocab/applicator": true,
77
"https://json-schema.org/draft/2019-08/vocab/validation": true,
88
"https://json-schema.org/draft/2019-08/vocab/meta-data": true,
9-
"https://json-schema.org/draft/2019-08/vocab/format": true,
9+
"https://json-schema.org/draft/2019-08/vocab/format": false,
1010
"https://json-schema.org/draft/2019-08/vocab/content": true
1111
},
1212
"$recursiveAnchor": true,

0 commit comments

Comments
 (0)