diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml
index 40e4e256..0a7f3149 100644
--- a/jsonschema-validation.xml
+++ b/jsonschema-validation.xml
@@ -514,18 +514,12 @@
Structural validation alone may be insufficient to allow an application to correctly
- utilize certain values. The "format" annotation keyword is defined to allow schema
+ utilize certain values. The "format" annotation keyword is defined to allow schema
authors to convey semantic information for a fixed subset of values which are
accurately described by authoritative resources, be they RFCs or other external
specifications.
-
- Implementations MAY treat "format" as an assertion in addition to an annotation,
- and attempt to validate the value's conformance to the specified semantics.
- See the Implementation Requirements below for details.
-
-
The value of this keyword is called a format attribute. It MUST be a string. A
format attribute can generally only validate a given set of instance types. If
@@ -536,8 +530,8 @@
core JSON Schema.
Note that the "type" keyword in this specification defines an "integer" type
- which is not part of the data model. Therefore a format attribute can be
- limited to numbers, but not specifically to integers. However, a numeric
+ which is not part of the data model. Therefore a format attribute can be
+ limited to numbers, but not specifically to integers. However, a numeric
format can be used alongside the "type" keyword with a value of "integer",
or could be explicitly defined to always pass if the number is not an integer,
which produces essentially the same behavior as only applying to integers.
@@ -545,75 +539,56 @@
- Meta-schemas that do not use "$vocabulary" SHOULD be considered to
- utilize this vocabulary as if its URI were present with a value of false.
- See the Implementation Requirements below for details.
+ The current URI for this vocabulary, known as the Format-Annotation vocabulary, is:
+ <https://json-schema.org/draft/2020-11/vocab/format-annotation>. The current
+ URI for the corresponding meta-schema is:
+ .
+ Implementing support for this vocabulary is REQUIRED.
- The current URI for this vocabulary, known as the Format vocabulary, is:
- <https://json-schema.org/draft/2020-11/vocab/format>.
+ In addition to the Format-Annotation vocabulary, a secondary vocabulary is available
+ for custom meta-schemas that defines "format" as an assertion. The URI for the
+ Format-Assertion vocabulary, is:
+ <https://json-schema.org/draft/2020-11/vocab/format-assertion>. The current
+ URI for the corresponding meta-schema is:
+ .
+ Implementing support for the Format-Assertion vocabulary is OPTIONAL.
- The current URI for the corresponding meta-schema is:
- .
+ Specifying both the Format-Annotation and the Format-Assertion vocabularies is functionally
+ equivalent to specifying only the Format-Assertion vocabulary since its requirements
+ are a superset of the Format-Annotation vocabulary.
-
- The "format" keyword functions as an annotation, and optionally as an assertion.
- This is due to the keyword's history, and is not in line with current
- keyword design principles. In order to manage this ambiguity, the
- "format" keyword is defined in its own separate vocabulary, as noted above.
- The true or false value of the vocabulary declaration governs the implementation
- requirements necessary to process a schema that uses "format", and the
- behaviors on which schema authors can rely.
+ The "format" keyword functions as defined by the vocabulary which is referenced.
-
+
The value of format MUST be collected as an annotation, if the implementation
- supports annotation collection. This enables application-level validation when
+ supports annotation collection. This enables application-level validation when
schema validation is unavailable or inadequate.
- This requirement is not affected by the boolean value of the vocabulary
- declaration, nor by the configuration of "format"'s assertion
- behavior described in the next section.
+ Implementations MAY still treat "format" as an assertion in addition to an
+ annotation and attempt to validate the value's conformance to the specified
+ semantics. The implementation MUST provide options to enable and disable such
+ evaluation and MUST be disabled by default. Implementations SHOULD document
+ their level of support for such validation.
- Requiring annotation collection even when the vocabulary is declared with
- a value of false is atypical, but necessary to ensure that the best
- practice of performing application-level validation is possible even when
- assertion evaluation is not implemented. Since "format" has always been
- a part of this specification, requiring implementations to be aware of it
- even with a false vocabulary declaration is deemed to not be a burden.
+ Specifying the Format-Annotation vocabulary and enabling validation in an
+ implementation should not be viewed as being equivalent to specifying
+ the Format-Assertion vocabulary since implementations are not required to
+ provide full validation support when the Format-Assertion vocabulary
+ is not specified.
-
-
-
-
- Regardless of the boolean value of the vocabulary declaration,
- an implementation that can evaluate "format" as an assertion MUST provide
- options to enable and disable such evaluation. The assertion evaluation
- behavior when the option is not explicitly specified depends on
- the vocabulary declaration's boolean value.
-
-
- When implementing this entire specification, this vocabulary MUST
- be supported with a value of false (but see details below),
- and MAY be supported with a value of true.
-
-
-
- When the vocabulary is declared with a value of false, an implementation:
+ When the implementation is configured for assertion behavior, it:
-
- MUST NOT evaluate "format" as an assertion unless it is explicitly
- configured to do so;
-
SHOULD provide an implementation-specific best effort validation
for each format attribute defined below;
@@ -622,9 +597,6 @@
MAY choose to implement validation of any or all format attributes
as a no-op by always producing a validation result of true;
-
- SHOULD document its level of support for validation.
-
This matches the current reality of implementations, which provide
@@ -634,14 +606,24 @@
validation in the application, which is the recommended best practice.
+
+
+
+ When the Format-Assertion vocabulary is declared with a value of true,
+ implementations MUST provide full validation support for all of the formats
+ defined by this specificaion. Implementations that cannot provide full
+ validation support MUST refuse to process the schema.
+
- When the vocabulary is declared with a value of true, an implementation
- that supports this form of the vocabulary:
+ An implementation that supports the Format-Assertion vocabulary:
- MUST evaluate "format" as an assertion unless it is explicitly
- configured not to do so;
+ MUST still collect "format" as an annotation if the implementation
+ supports annotation collection;
+
+
+ MUST evaluate "format" as an assertion;
MUST implement syntactic validation for all format attributes defined
@@ -685,10 +667,9 @@
Implementations MAY support custom format attributes. Save for agreement between
parties, schema authors SHALL NOT expect a peer implementation to support such
- custom format attributes. An implementation MUST NOT fail
- validation or cease processing due to an unknown format attribute.
- When treating "format" as an annotation, implementations SHOULD collect both
- known and unknown format attribute values.
+ custom format attributes. An implementation MUST NOT fail to collect unknown formats
+ as annotations. When the Format-Assertion vocabulary is specified, implementations
+ MUST fail upon encountering unknown formats.
Vocabularies do not support specifically declaring different value sets for keywords.
diff --git a/meta/format-annotation.json b/meta/format-annotation.json
new file mode 100644
index 00000000..a4080d69
--- /dev/null
+++ b/meta/format-annotation.json
@@ -0,0 +1,14 @@
+{
+ "$schema": "https://json-schema.org/draft/2019-09/schema",
+ "$id": "https://json-schema.org/draft/2019-09/meta/format-annotation",
+ "$vocabulary": {
+ "https://json-schema.org/draft/2019-09/vocab/format-annotation": true
+ },
+ "$dynamicAnchor": "meta",
+
+ "title": "Format vocabulary meta-schema for annotation results",
+ "type": ["object", "boolean"],
+ "properties": {
+ "format": { "type": "string" }
+ }
+}
diff --git a/meta/format.json b/meta/format-assertion.json
similarity index 50%
rename from meta/format.json
rename to meta/format-assertion.json
index 68ad5b0d..ecac5c1f 100644
--- a/meta/format.json
+++ b/meta/format-assertion.json
@@ -1,12 +1,12 @@
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
- "$id": "https://json-schema.org/draft/2019-09/meta/format",
+ "$id": "https://json-schema.org/draft/2019-09/meta/format-assertion",
"$vocabulary": {
- "https://json-schema.org/draft/2019-09/vocab/format": true
+ "https://json-schema.org/draft/2019-09/vocab/format-assertion": true
},
"$dynamicAnchor": "meta",
- "title": "Format vocabulary meta-schema",
+ "title": "Format vocabulary meta-schema for assertion results",
"type": ["object", "boolean"],
"properties": {
"format": { "type": "string" }