Skip to content

Commit 39af765

Browse files
handrewshandrews
authored
Merge pull request #764 from handrews/fmt-vocab
Specify "format" requirements in vocabulary terms
2 parents 728017a + 3ea9e82 commit 39af765

File tree

3 files changed

+164
-28
lines changed

3 files changed

+164
-28
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

+162-26
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,45 @@
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 value's 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. However, a numeric
536+
format can be used alongside the "type" keyword with a value of "integer",
537+
or could be explicitly defined to always pass if the number is not an integer,
538+
which produces essentially the same behavior as only applying to integers.
539+
</cref>
522540
</t>
523541

524542
<t>
525543
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.
544+
utilize this vocabulary as if its URI were present with a value of false.
545+
See the Implementation Requirements below for details.
528546
</t>
529547
<t>
530548
The current URI for this vocabulary, known as the Format vocabulary, is:
@@ -539,27 +557,141 @@
539557

540558
<section title="Implementation Requirements">
541559
<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.
560+
The "format" keyword functions as an annotation, and optionally as an assertion.
561+
<cref>This is due to the keyword's history, and is not in line with current
562+
keyword design principles.</cref> In order to manage this ambiguity, the
563+
"format" keyword is defined in its own separate vocabulary, as noted above.
564+
The true or false value of the vocabulary declaration governs the implementation
565+
requirements necessary to process a schema that uses "format", and the
566+
behaviors on which schema authors can rely.
546567
</t>
547-
<t>
548-
Implementations MAY support the "format" keyword as a validation assertion.
549-
Should they choose to do so:
550568

551-
<list>
552-
<t>they SHOULD implement validation for attributes defined below;</t>
553-
<t>they SHOULD offer an option to disable validation for this keyword.</t>
554-
</list>
569+
<section title="As an annotation">
570+
<t>
571+
The value of format MUST be collected as an annotation, if the implementation
572+
supports annotation collection. This enables application-level validation when
573+
schema validation is unavailable or inadequate.
574+
</t>
575+
<t>
576+
This requirement is not affected by the boolean value of the vocabulary
577+
declaration, nor by the configuration of "format"'s assertion
578+
behavior described in the next section.
579+
<cref>
580+
Requiring annotation collection even when the vocabulary is declared with
581+
a value of false is atypical, but necessary to ensure that the best
582+
practice of performing application-level validation is possible even when
583+
assertion evaluation is not implemented. Since "format" has always been
584+
a part of this specification, requiring implementations to be aware of it
585+
even with a false vocabulary declaration is deemed to not be a burden.
586+
</cref>
587+
</t>
588+
</section>
589+
590+
<section title="As an assertion">
591+
<t>
592+
Regardless of the boolean value of the vocabulary declaration,
593+
an implementation that can evaluate "format" as an assertion MUST provide
594+
options to enable and disable such evaluation. The assertion evaluation
595+
behavior when the option is not explicitly specified depends on
596+
the vocabulary declaration's boolean value.
597+
</t>
555598

556-
</t>
599+
<t>
600+
When implementing this entire specification, this vocabulary MUST
601+
be supported with a value of false (but see details below),
602+
and MAY be supported with a value of true.
603+
</t>
557604

558-
<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.
562-
</t>
605+
<t>
606+
When the vocabulary is declared with a value of false, an implementation:
607+
<list>
608+
<t>
609+
MUST NOT evaluate "format" as an assertion unless it is explicitly
610+
configured to do so;
611+
</t>
612+
<t>
613+
SHOULD provide an implementation-specific best effort validation
614+
for each format attribute defined below;
615+
</t>
616+
<t>
617+
MAY choose to implement validation of any or all format attributes
618+
as a no-op by always producing a validation result of true;
619+
</t>
620+
<t>
621+
SHOULD document its level of support for validation.
622+
</t>
623+
</list>
624+
<cref>
625+
This matches the current reality of implementations, which provide
626+
widely varying levels of validation, including no validation at all,
627+
for some or all format attributes. It is also designed to encourage
628+
relying only on the annotation behavior and performing semantic
629+
validation in the application, which is the recommended best practice.
630+
</cref>
631+
</t>
632+
633+
<t>
634+
When the vocabulary is declared with a value of true, an implementation
635+
that supports this form of the vocabulary:
636+
<list>
637+
<t>
638+
MUST evaluate "format" as an assertion unless it is explicitly
639+
configured not to do so;
640+
</t>
641+
<t>
642+
MUST implement syntactic validation for all format attributes defined
643+
in this specification, and for any additional format attributes that
644+
it recognizes, such that there exist possible instance values
645+
of the correct type that will fail validation.
646+
</t>
647+
</list>
648+
The requirement for minimal validation of format attributes is intentionally
649+
vague and permissive, due to the complexity involved in many of the attributes.
650+
Note in particular that the requirement is limited to syntactic checking; it is
651+
not to be expected that an implementation would send an email, attempt to connect
652+
to a URL, or otherwise check the existence of an entity identified by a format
653+
instance.
654+
<cref>
655+
The expectation is that for simple formats such as date-time, syntactic
656+
validation will be thorough. For a complex format such as email addresses,
657+
which are the amalgamation of various standards and numerous adjustments
658+
over time, with obscure and/or obsolete rules that may or may not be
659+
restricted by other applications making use of the value, a minimal validation
660+
is sufficient. For example, an instance string that does not contain
661+
an "@" is clearly not a valid email address, and an "email" or "hostname"
662+
containing characters outside of 7-bit ASCII is likewise clearly invalid.
663+
</cref>
664+
</t>
665+
<t>
666+
It is RECOMMENDED that implementations use a common parsing library for each format,
667+
or a well-known regular expression. Implementations SHOULD clearly document
668+
how and to what degree each format attribute is validated.
669+
</t>
670+
<t>
671+
The <xref target="meta-schema">standard core and validation meta-schema</xref>
672+
includes this vocabulary in its "$vocabulary" keyword with a value of false,
673+
since by default implementations are not required to support this keyword
674+
as an assertion. Supporting the format vocabulary with a value of true is
675+
understood to greatly increase code size and in some cases execution time,
676+
and will not be appropriate for all implementations.
677+
</t>
678+
</section>
679+
<section title="Custom format attributes">
680+
<t>
681+
Implementations MAY support custom format attributes. Save for agreement between
682+
parties, schema authors SHALL NOT expect a peer implementation to support such
683+
custom format attributes. An implementation MUST NOT fail
684+
validation or cease processing due to an unknown format attribute.
685+
When treating "format" as an annotation, implementations SHOULD collect both
686+
known and unknown format attribute values.
687+
</t>
688+
<t>
689+
Vocabularies do not support specifically declaring different value sets for keywords.
690+
Due to this limitation, and the historically uneven implementation of this keyword,
691+
it is RECOMMENDED to define additional keywords in a custom vocabulary rather than
692+
additional format attributes if interoperability is desired.
693+
</t>
694+
</section>
563695
</section>
564696

565697
<section title="Defined Formats">
@@ -1282,6 +1414,10 @@
12821414
<list style="hanging">
12831415
<t hangText="draft-handrews-json-schema-validation-02">
12841416
<list style="symbols">
1417+
<t>Grouped keywords into formal vocabuarlies</t>
1418+
<t>Update "format" implementation requirements in terms of vocabularies</t>
1419+
<t>By default, "format" MUST NOT be validated, although validation can be enabled</t>
1420+
<t>A vocabulary declaration can be used to require "format" validation</t>
12851421
<t>Moved "definitions" to the core spec as "$defs"</t>
12861422
<t>Moved applicator keywords to the core spec</t>
12871423
<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)