Skip to content

Commit 7e09ca0

Browse files
gregsdennisgregsdennis
committed
resolves #1020 - format is an annotation by default
1 parent e8d37e1 commit 7e09ca0

File tree

1 file changed

+31
-60
lines changed

1 file changed

+31
-60
lines changed

‎jsonschema-validation.xml

+31-60
Original file line numberDiff line numberDiff line change
@@ -566,90 +566,61 @@
566566
<cref>This is due to the keyword's history, and is not in line with current
567567
keyword design principles.</cref> In order to manage this ambiguity, the
568568
"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.
569+
</t>
570+
<t>
571+
Regardless of the boolean value of the vocabulary declaration,
572+
an implementation that can evaluate "format" as an assertion MUST provide
573+
options to enable and disable such evaluation. The default behavior MUST be
574+
to collect annotations by default.
572575
</t>
573576

574577
<section title="As an annotation">
575578
<t>
576579
The value of format MUST be collected as an annotation, if the implementation
577580
supports annotation collection. This enables application-level validation when
578581
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.
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+
This requirement is not affected by the boolean value of the vocabulary
584+
declaration.
585+
For a vocabulary value of true, the implementation MUST halt if it doesn't
586+
understand the vocabulary. If the implementation does understand the
587+
vocabulary, annotations are collected. This halt-on-non-understanding
588+
behavior may be desired by an application, so it is considered. However,
589+
this is the result of the behavior of the "$vocabulary" keyword exclusively
590+
and is not affected by the definition of "format".
591+
For a vocabulary value of false, the implementation MAY proceed without
592+
understanding the keyword, meaning that the implementation will collect
593+
its value as an annotation anyway.
591594
</cref>
592595
</t>
593596
</section>
594597

595598
<section title="As an assertion">
596599
<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.
600+
When configured to process "format" as an assertion, an implementation MUST
601+
implement syntactic validation for all format attributes defined
602+
in this specification, and for any additional format attributes that
603+
it recognizes, such that there exist possible instance values
604+
of the correct type that will fail validation.
602605
</t>
603-
604606
<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:
612-
<list>
613-
<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;
620-
</t>
621-
<t>
622-
MAY choose to implement validation of any or all format attributes
623-
as a no-op by always producing a validation result of true;
624-
</t>
625-
<t>
626-
SHOULD document its level of support for validation.
627-
</t>
628-
</list>
607+
It is understood that, due to computing limitations and other concerns,
608+
it is improbable that an implementation will be able to perfectly cover
609+
all of the requirements set forth by these formats. As such, it is
610+
strongly RECOMMENDED for implementations to document their level of
611+
support for validation.
629612
<cref>
630613
This matches the current reality of implementations, which provide
631614
widely varying levels of validation, including no validation at all,
632615
for some or all format attributes. It is also designed to encourage
633616
relying only on the annotation behavior and performing semantic
634617
validation in the application, which is the recommended best practice.
618+
Furthermore, the more support an implementation has, the more users
619+
it is likely to attract. This should encourage implementors to
620+
provide the most comprehensive support they can.
635621
</cref>
636622
</t>
637-
638623
<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
@@ -676,7 +647,7 @@
676647
The <xref target="meta-schema">standard core and validation meta-schema</xref>
677648
includes this vocabulary in its "$vocabulary" keyword with a value of false,
678649
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
650+
as an assertion. Supporting the format vocabulary as an assertion is
680651
understood to greatly increase code size and in some cases execution time,
681652
and will not be appropriate for all implementations.
682653
</t>

0 commit comments

Comments
 (0)