Skip to content

Commit f3cf2ba

Browse files
gregsdennisgregsdennis
committed
resolves #1020 - reworked 'format' to default to annotation except when configured for assertion
1 parent e8d37e1 commit f3cf2ba

File tree

1 file changed

+41
-70
lines changed

1 file changed

+41
-70
lines changed

Diff for: ‎jsonschema-validation.xml

+41-70
Original file line numberDiff line numberDiff line change
@@ -549,6 +549,11 @@
549549
utilize this vocabulary as if its URI were present with a value of false.
550550
See the Implementation Requirements below for details.
551551
</t>
552+
<t>
553+
The <xref target="meta-schema">standard core and validation meta-schema</xref>
554+
includes this vocabulary in its "$vocabulary" keyword with a value of false
555+
since implementations are not required to provide support for this keyword.
556+
</t>
552557
<t>
553558
The current URI for this vocabulary, known as the Format vocabulary, is:
554559
&lt;https://json-schema.org/draft/2020-11/vocab/format&gt;.
@@ -563,60 +568,50 @@
563568
<section title="Implementation Requirements">
564569
<t>
565570
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
571+
<cref>This is due to the keyword's history, this is not in line with current
567572
keyword design principles.</cref> In order to manage this ambiguity, the
568573
"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.
574+
</t>
575+
<t>
576+
Regardless of the boolean value of the vocabulary declaration,
577+
an implementation that can evaluate "format" as an assertion MUST provide
578+
options to enable and disable such evaluation. By default, these options
579+
MUST default to annotation collection. The manifestation of options is
580+
implemenation-specific and not covered by this specification.
581+
</t>
582+
<t>
583+
An implementation MUST adhere to its configured behavior at all times. There
584+
is currently no mechanism defined by this specification which allows this
585+
configuration to be defined by the schema.
572586
</t>
573587

574588
<section title="As an annotation">
575589
<t>
576-
The value of format MUST be collected as an annotation, if the implementation
577-
supports annotation collection. This enables application-level validation when
590+
The value of "format" MUST be collected as an annotation (if the implementation
591+
supports annotation collection). This enables application-level validation when
578592
schema validation is unavailable or inadequate.
579-
</t>
580-
<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.
584593
<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.
594+
Together with the requirement of collecting unknown keywords as annotations
595+
and the "format" vocabulary being declared with a "false" value, the
596+
net effect is that the behavior of this keyword is unchanged whether the
597+
implementation understands the "format" vocabulary or not. If a meta-schema
598+
were to declare this vocabulary with a "true" value and the implementation
599+
doesn't understand it, the "$vocabulary" rule would be invoked and the
600+
implementation would be required halt validation.
591601
</cref>
592602
</t>
593603
</section>
594604

595605
<section title="As an assertion">
596606
<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-
610-
<t>
611-
When the vocabulary is declared with a value of false, an implementation:
607+
When the implementation is configured to treat the "format" keyword as an
608+
assertion, it:
612609
<list>
613610
<t>
614-
MUST NOT evaluate "format" as an assertion unless it is explicitly
615-
configured to do so;
616-
</t>
617-
<t>
618-
SHOULD provide an implementation-specific best effort validation
619-
for each format attribute defined below;
611+
MUST implement syntactic validation for all format attributes defined
612+
in this specification, and for any additional format attributes that
613+
it recognizes, such that there exist possible instance values
614+
of the correct type that will fail validation.
620615
</t>
621616
<t>
622617
MAY choose to implement validation of any or all format attributes
@@ -626,30 +621,6 @@
626621
SHOULD document its level of support for validation.
627622
</t>
628623
</list>
629-
<cref>
630-
This matches the current reality of implementations, which provide
631-
widely varying levels of validation, including no validation at all,
632-
for some or all format attributes. It is also designed to encourage
633-
relying only on the annotation behavior and performing semantic
634-
validation in the application, which is the recommended best practice.
635-
</cref>
636-
</t>
637-
638-
<t>
639-
When the vocabulary is declared with a value of true, an implementation
640-
that supports this form of the vocabulary:
641-
<list>
642-
<t>
643-
MUST evaluate "format" as an assertion unless it is explicitly
644-
configured not to do so;
645-
</t>
646-
<t>
647-
MUST implement syntactic validation for all format attributes defined
648-
in this specification, and for any additional format attributes that
649-
it recognizes, such that there exist possible instance values
650-
of the correct type that will fail validation.
651-
</t>
652-
</list>
653624
The requirement for minimal validation of format attributes is intentionally
654625
vague and permissive, due to the complexity involved in many of the attributes.
655626
Note in particular that the requirement is limited to syntactic checking; it is
@@ -666,20 +637,20 @@
666637
an "@" is clearly not a valid email address, and an "email" or "hostname"
667638
containing characters outside of 7-bit ASCII is likewise clearly invalid.
668639
</cref>
640+
<cref>
641+
This matches the current reality of implementations, which provide
642+
widely varying levels of validation, including no validation at all,
643+
for some or all format attributes. It is also designed to encourage
644+
relying only on the annotation behavior and performing semantic
645+
validation in the application, which is the recommended best practice.
646+
</cref>
669647
</t>
648+
670649
<t>
671650
It is RECOMMENDED that implementations use a common parsing library for each format,
672651
or a well-known regular expression. Implementations SHOULD clearly document
673652
how and to what degree each format attribute is validated.
674653
</t>
675-
<t>
676-
The <xref target="meta-schema">standard core and validation meta-schema</xref>
677-
includes this vocabulary in its "$vocabulary" keyword with a value of false,
678-
since by default implementations are not required to support this keyword
679-
as an assertion. Supporting the format vocabulary with a value of true is
680-
understood to greatly increase code size and in some cases execution time,
681-
and will not be appropriate for all implementations.
682-
</t>
683654
</section>
684655
<section title="Custom format attributes">
685656
<t>

0 commit comments

Comments
 (0)