Skip to content

Commit

Permalink
Merge pull request #1027 from json-schema-org/separate-format-vocabul…
Browse files Browse the repository at this point in the history 
…aries

`format` as a annotation by default - separate vocabs (option 3)
  • Loading branch information
@Relequestual
Relequestual committed Nov 24, 2020
2 parents d8c66e2 + 242cfd0 commit 2ce4968
Show file tree
Hide file tree
Showing 3 changed files with 66 additions and 71 deletions.
117 changes: 49 additions & 68 deletions jsonschema-validation.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -514,18 +514,12 @@
<section title="Foreword">
<t>
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.
</t>

<t>
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.
</t>

<t>
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
Expand All @@ -536,84 +530,65 @@
<xref target="json-schema">core JSON Schema.</xref>
<cref>
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.
</cref>
</t>

<t>
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:
&lt;https://json-schema.org/draft/2020-11/vocab/format-annotation&gt;. The current
URI for the corresponding meta-schema is:
<eref target="https://json-schema.org/draft/2020-11/meta/format-annotation"/>.
Implementing support for this vocabulary is REQUIRED.
</t>
<t>
The current URI for this vocabulary, known as the Format vocabulary, is:
&lt;https://json-schema.org/draft/2020-11/vocab/format&gt;.
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:
&lt;https://json-schema.org/draft/2020-11/vocab/format-assertion&gt;. The current
URI for the corresponding meta-schema is:
<eref target="https://json-schema.org/draft/2020-11/meta/format-assertion"/>.
Implementing support for the Format-Assertion vocabulary is OPTIONAL.
</t>
<t>
The current URI for the corresponding meta-schema is:
<eref target="https://json-schema.org/draft/2020-11/meta/format"/>.
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.
</t>

</section>

<section title="Implementation Requirements">
<t>
The "format" keyword functions as an annotation, and optionally as an assertion.
<cref>This is due to the keyword's history, and is not in line with current
keyword design principles.</cref> 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.
</t>

<section title="As an annotation">
<section title="Format-Annotation Vocabulary">
<t>
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.
</t>
<t>
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.
<cref>
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.
</cref>
</t>
</section>

<section title="As an assertion">
<t>
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.
</t>

<t>
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.
</t>

<t>
When the vocabulary is declared with a value of false, an implementation:
When the implementation is configured for assertion behavior, it:
<list>
<t>
MUST NOT evaluate "format" as an assertion unless it is explicitly
configured to do so;
</t>
<t>
SHOULD provide an implementation-specific best effort validation
for each format attribute defined below;
Expand All @@ -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;
</t>
<t>
SHOULD document its level of support for validation.
</t>
</list>
<cref>
This matches the current reality of implementations, which provide
Expand All @@ -634,14 +606,24 @@
validation in the application, which is the recommended best practice.
</cref>
</t>
</section>

<section title="Format-Assertion Vocabulary">
<t>
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.
</t>
<t>
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:
<list>
<t>
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;
</t>
<t>
MUST evaluate "format" as an assertion;
</t>
<t>
MUST implement syntactic validation for all format attributes defined
Expand Down Expand Up @@ -685,10 +667,9 @@
<t>
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.
</t>
<t>
Vocabularies do not support specifically declaring different value sets for keywords.
Expand Down
14 changes: 14 additions & 0 deletions meta/format-annotation.json
View file
Original file line number Diff line number Diff line change
@@ -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" }
}
}
6 changes: 3 additions & 3 deletions meta/format.json → meta/format-assertion.json
View file
Original file line number Diff line number Diff line change
@@ -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" }
Expand Down

0 comments on commit 2ce4968

Please sign in to comment.