Skip to content

Commit 62b9c21

Browse files
gregsdennisgregsdennis
committed
issue-1020-separate-format-vocabularies
1 parent e8d37e1 commit 62b9c21

File tree

1 file changed

+46
-63
lines changed

1 file changed

+46
-63
lines changed

‎jsonschema-validation.xml‎

Lines changed: 46 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -514,18 +514,12 @@
514514
<section title="Foreword">
515515
<t>
516516
Structural validation alone may be insufficient to allow an application to correctly
517-
utilize certain values. The "format" annotation keyword is defined to allow schema
517+
utilize certain values. The "format" annotation keyword is defined to allow schema
518518
authors to convey semantic information for a fixed subset of values which are
519519
accurately described by authoritative resources, be they RFCs or other external
520520
specifications.
521521
</t>
522522

523-
<t>
524-
Implementations MAY treat "format" as an assertion in addition to an annotation,
525-
and attempt to validate the value's conformance to the specified semantics.
526-
See the Implementation Requirements below for details.
527-
</t>
528-
529523
<t>
530524
The value of this keyword is called a format attribute. It MUST be a string. A
531525
format attribute can generally only validate a given set of instance types. If
@@ -536,84 +530,66 @@
536530
<xref target="json-schema">core JSON Schema.</xref>
537531
<cref>
538532
Note that the "type" keyword in this specification defines an "integer" type
539-
which is not part of the data model. Therefore a format attribute can be
540-
limited to numbers, but not specifically to integers. However, a numeric
533+
which is not part of the data model. Therefore a format attribute can be
534+
limited to numbers, but not specifically to integers. However, a numeric
541535
format can be used alongside the "type" keyword with a value of "integer",
542536
or could be explicitly defined to always pass if the number is not an integer,
543537
which produces essentially the same behavior as only applying to integers.
544538
</cref>
545539
</t>
546540

547541
<t>
548-
Meta-schemas that do not use "$vocabulary" SHOULD be considered to
549-
utilize this vocabulary as if its URI were present with a value of false.
550-
See the Implementation Requirements below for details.
542+
The current URI for this vocabulary, known as the Format-Annotation vocabulary, is:
543+
&lt;https://json-schema.org/draft/2020-11/vocab/format-annotation&gt;. This vocabulary
544+
is required by this specification.
551545
</t>
552546
<t>
553-
The current URI for this vocabulary, known as the Format vocabulary, is:
554-
&lt;https://json-schema.org/draft/2020-11/vocab/format&gt;.
547+
In addition to the Format-Annotation vocabulary, a secondary vocabulary is available
548+
for custom meta-schemas that defines "format" as an assertion. The URI for the
549+
Format-Assertion vocabulary, is:
550+
&lt;https://json-schema.org/draft/2020-11/vocab/format-assertation&gt;.
555551
</t>
556552
<t>
557553
The current URI for the corresponding meta-schema is:
558-
<eref target="https://json-schema.org/draft/2020-11/meta/format"/>.
554+
<eref target="https://json-schema.org/draft/2020-11/meta/format"/>. Because the
555+
syntactic requirements of "format" do not change between the annotation and assertion
556+
vocabularies, the meta-schema is shared between them.
557+
</t>
558+
<t>
559+
Specifying both the Format-Annotation and the Format-Assertion vocabularies is functionally
560+
equivalent to specifying only the Format-Assertion vocabulary since its requirements
561+
are a superset of the Format-Annotation vocabulary.
559562
</t>
560-
561563
</section>
562564

563565
<section title="Implementation Requirements">
564566
<t>
565-
The "format" keyword functions as an annotation, and optionally as an assertion.
566-
<cref>This is due to the keyword's history, and is not in line with current
567-
keyword design principles.</cref> In order to manage this ambiguity, the
568-
"format" keyword is defined in its own separate vocabulary, as noted above.
569-
The true or false value of the vocabulary declaration governs the implementation
570-
requirements necessary to process a schema that uses "format", and the
571-
behaviors on which schema authors can rely.
567+
The "format" keyword functions as defined by the vocabulary which is referenced.
572568
</t>
573569

574-
<section title="As an annotation">
570+
<section title="Format-Annotation Vocabulary">
575571
<t>
576572
The value of format MUST be collected as an annotation, if the implementation
577-
supports annotation collection. This enables application-level validation when
573+
supports annotation collection. This enables application-level validation when
578574
schema validation is unavailable or inadequate.
579575
</t>
580576
<t>
581-
This requirement is not affected by the boolean value of the vocabulary
582-
declaration, nor by the configuration of "format"'s assertion
583-
behavior described in the next section.
577+
Implementations MAY still treat "format" as an assertion in addition to an
578+
annotation and attempt to validate the value's conformance to the specified
579+
semantics. The implementation MUST provide options to enable and disable such
580+
evaluation and MUST be disabled by default. Implementations SHOULD document
581+
their level of support for such validation.
584582
<cref>
585-
Requiring annotation collection even when the vocabulary is declared with
586-
a value of false is atypical, but necessary to ensure that the best
587-
practice of performing application-level validation is possible even when
588-
assertion evaluation is not implemented. Since "format" has always been
589-
a part of this specification, requiring implementations to be aware of it
590-
even with a false vocabulary declaration is deemed to not be a burden.
583+
Specifying the Format-Annotation vocabulary and enabling validation in an
584+
implementation should not be viewed as being equivalent to specifying
585+
the Format-Assertion vocabulary since implementations are not required to
586+
provide full validation support when the Format-Assertion vocabulary
587+
is not specified.
591588
</cref>
592589
</t>
593-
</section>
594-
595-
<section title="As an assertion">
596-
<t>
597-
Regardless of the boolean value of the vocabulary declaration,
598-
an implementation that can evaluate "format" as an assertion MUST provide
599-
options to enable and disable such evaluation. The assertion evaluation
600-
behavior when the option is not explicitly specified depends on
601-
the vocabulary declaration's boolean value.
602-
</t>
603-
604-
<t>
605-
When implementing this entire specification, this vocabulary MUST
606-
be supported with a value of false (but see details below),
607-
and MAY be supported with a value of true.
608-
</t>
609-
610590
<t>
611-
When the vocabulary is declared with a value of false, an implementation:
591+
When the implementation is configured for assertion behavior, it:
612592
<list>
613-
<t>
614-
MUST NOT evaluate "format" as an assertion unless it is explicitly
615-
configured to do so;
616-
</t>
617593
<t>
618594
SHOULD provide an implementation-specific best effort validation
619595
for each format attribute defined below;
@@ -622,9 +598,6 @@
622598
MAY choose to implement validation of any or all format attributes
623599
as a no-op by always producing a validation result of true;
624600
</t>
625-
<t>
626-
SHOULD document its level of support for validation.
627-
</t>
628601
</list>
629602
<cref>
630603
This matches the current reality of implementations, which provide
@@ -634,14 +607,24 @@
634607
validation in the application, which is the recommended best practice.
635608
</cref>
636609
</t>
610+
</section>
637611

612+
<section title="Format-Assertion Vocabulary">
613+
<t>
614+
When the Format-Assertion vocabulary is declared with a value of false,
615+
implementations MUST provide full validation support for all of the formats
616+
defined by this specificaion. Implementations that cannot provide full
617+
validation support MUST refuse to process the schema.
618+
</t>
638619
<t>
639-
When the vocabulary is declared with a value of true, an implementation
640-
that supports this form of the vocabulary:
620+
An implementation that supports the Format-Assertion vocabulary:
641621
<list>
642622
<t>
643-
MUST evaluate "format" as an assertion unless it is explicitly
644-
configured not to do so;
623+
MUST still collect "format" as an annotation if the implementation
624+
supports annotation collection;
625+
</t>
626+
<t>
627+
MUST evaluate "format" as an assertion;
645628
</t>
646629
<t>
647630
MUST implement syntactic validation for all format attributes defined

0 commit comments

Comments
 (0)