Skip to content

Commit 2ce4968

Browse files
RelequestualRelequestual
authored
Merge pull request #1027 from json-schema-org/separate-format-vocabularies
`format` as a annotation by default - separate vocabs (option 3)
2 parents d8c66e2 + 242cfd0 commit 2ce4968

File tree

3 files changed

+66
-71
lines changed

3 files changed

+66
-71
lines changed

‎jsonschema-validation.xml

+49-68
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,65 @@
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;. The current
544+
URI for the corresponding meta-schema is:
545+
<eref target="https://json-schema.org/draft/2020-11/meta/format-annotation"/>.
546+
Implementing support for this vocabulary is REQUIRED.
551547
</t>
552548
<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;.
549+
In addition to the Format-Annotation vocabulary, a secondary vocabulary is available
550+
for custom meta-schemas that defines "format" as an assertion. The URI for the
551+
Format-Assertion vocabulary, is:
552+
&lt;https://json-schema.org/draft/2020-11/vocab/format-assertion&gt;. The current
553+
URI for the corresponding meta-schema is:
554+
<eref target="https://json-schema.org/draft/2020-11/meta/format-assertion"/>.
555+
Implementing support for the Format-Assertion vocabulary is OPTIONAL.
555556
</t>
556557
<t>
557-
The current URI for the corresponding meta-schema is:
558-
<eref target="https://json-schema.org/draft/2020-11/meta/format"/>.
558+
Specifying both the Format-Annotation and the Format-Assertion vocabularies is functionally
559+
equivalent to specifying only the Format-Assertion vocabulary since its requirements
560+
are a superset of the Format-Annotation vocabulary.
559561
</t>
560-
561562
</section>
562563

563564
<section title="Implementation Requirements">
564565
<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.
566+
The "format" keyword functions as defined by the vocabulary which is referenced.
572567
</t>
573568

574-
<section title="As an annotation">
569+
<section title="Format-Annotation Vocabulary">
575570
<t>
576571
The value of format MUST be collected as an annotation, if the implementation
577-
supports annotation collection. This enables application-level validation when
572+
supports annotation collection. This enables application-level validation when
578573
schema validation is unavailable or inadequate.
579574
</t>
580575
<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.
576+
Implementations MAY still treat "format" as an assertion in addition to an
577+
annotation and attempt to validate the value's conformance to the specified
578+
semantics. The implementation MUST provide options to enable and disable such
579+
evaluation and MUST be disabled by default. Implementations SHOULD document
580+
their level of support for such validation.
584581
<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.
582+
Specifying the Format-Annotation vocabulary and enabling validation in an
583+
implementation should not be viewed as being equivalent to specifying
584+
the Format-Assertion vocabulary since implementations are not required to
585+
provide full validation support when the Format-Assertion vocabulary
586+
is not specified.
591587
</cref>
592588
</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-
604589
<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:
590+
When the implementation is configured for assertion behavior, it:
612591
<list>
613-
<t>
614-
MUST NOT evaluate "format" as an assertion unless it is explicitly
615-
configured to do so;
616-
</t>
617592
<t>
618593
SHOULD provide an implementation-specific best effort validation
619594
for each format attribute defined below;
@@ -622,9 +597,6 @@
622597
MAY choose to implement validation of any or all format attributes
623598
as a no-op by always producing a validation result of true;
624599
</t>
625-
<t>
626-
SHOULD document its level of support for validation.
627-
</t>
628600
</list>
629601
<cref>
630602
This matches the current reality of implementations, which provide
@@ -634,14 +606,24 @@
634606
validation in the application, which is the recommended best practice.
635607
</cref>
636608
</t>
609+
</section>
637610

611+
<section title="Format-Assertion Vocabulary">
612+
<t>
613+
When the Format-Assertion vocabulary is declared with a value of true,
614+
implementations MUST provide full validation support for all of the formats
615+
defined by this specificaion. Implementations that cannot provide full
616+
validation support MUST refuse to process the schema.
617+
</t>
638618
<t>
639-
When the vocabulary is declared with a value of true, an implementation
640-
that supports this form of the vocabulary:
619+
An implementation that supports the Format-Assertion vocabulary:
641620
<list>
642621
<t>
643-
MUST evaluate "format" as an assertion unless it is explicitly
644-
configured not to do so;
622+
MUST still collect "format" as an annotation if the implementation
623+
supports annotation collection;
624+
</t>
625+
<t>
626+
MUST evaluate "format" as an assertion;
645627
</t>
646628
<t>
647629
MUST implement syntactic validation for all format attributes defined
@@ -685,10 +667,9 @@
685667
<t>
686668
Implementations MAY support custom format attributes. Save for agreement between
687669
parties, schema authors SHALL NOT expect a peer implementation to support such
688-
custom format attributes. An implementation MUST NOT fail
689-
validation or cease processing due to an unknown format attribute.
690-
When treating "format" as an annotation, implementations SHOULD collect both
691-
known and unknown format attribute values.
670+
custom format attributes. An implementation MUST NOT fail to collect unknown formats
671+
as annotations. When the Format-Assertion vocabulary is specified, implementations
672+
MUST fail upon encountering unknown formats.
692673
</t>
693674
<t>
694675
Vocabularies do not support specifically declaring different value sets for keywords.

‎meta/format-annotation.json

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2019-09/schema",
3+
"$id": "https://json-schema.org/draft/2019-09/meta/format-annotation",
4+
"$vocabulary": {
5+
"https://json-schema.org/draft/2019-09/vocab/format-annotation": true
6+
},
7+
"$dynamicAnchor": "meta",
8+
9+
"title": "Format vocabulary meta-schema for annotation results",
10+
"type": ["object", "boolean"],
11+
"properties": {
12+
"format": { "type": "string" }
13+
}
14+
}

‎meta/format.json renamed to ‎meta/format-assertion.json

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
{
22
"$schema": "https://json-schema.org/draft/2019-09/schema",
3-
"$id": "https://json-schema.org/draft/2019-09/meta/format",
3+
"$id": "https://json-schema.org/draft/2019-09/meta/format-assertion",
44
"$vocabulary": {
5-
"https://json-schema.org/draft/2019-09/vocab/format": true
5+
"https://json-schema.org/draft/2019-09/vocab/format-assertion": true
66
},
77
"$dynamicAnchor": "meta",
88

9-
"title": "Format vocabulary meta-schema",
9+
"title": "Format vocabulary meta-schema for assertion results",
1010
"type": ["object", "boolean"],
1111
"properties": {
1212
"format": { "type": "string" }

0 commit comments

Comments
 (0)