Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

reworked 'format' to default to annotation except when configured for assertion #1023

Closed
wants to merge 1 commit into from
Closed

reworked 'format' to default to annotation except when configured for assertion #1023

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 41 additions & 70 deletions jsonschema-validation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -549,6 +549,11 @@
utilize this vocabulary as if its URI were present with a value of false.
See the Implementation Requirements below for details.
</t>
<t>
The <xref target="meta-schema">standard core and validation meta-schema</xref>
includes this vocabulary in its "$vocabulary" keyword with a value of false
since implementations are not required to provide support for this keyword.
</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;.
Expand All @@ -563,60 +568,50 @@
<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
<cref>This is due to the keyword's history, this 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.
</t>
<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. By default, these options
MUST default to annotation collection. The manifestation of options is
implemenation-specific and not covered by this specification.
</t>
<t>
An implementation MUST adhere to its configured behavior at all times. There
is currently no mechanism defined by this specification which allows this
configuration to be defined by the schema.
</t>

<section title="As an annotation">
<t>
The value of format MUST be collected as an annotation, if the implementation
supports annotation collection. This enables application-level validation when
The value of "format" MUST be collected as an annotation (if the implementation
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.
<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.
Together with the requirement of collecting unknown keywords as annotations
and the "format" vocabulary being declared with a "false" value, the
net effect is that the behavior of this keyword is unchanged whether the
implementation understands the "format" vocabulary or not. If a meta-schema
were to declare this vocabulary with a "true" value and the implementation
doesn't understand it, the "$vocabulary" rule would be invoked and the
implementation would be required halt validation.
</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 to treat the "format" keyword as an
assertion, 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;
MUST implement syntactic validation for all format attributes defined
in this specification, and for any additional format attributes that
it recognizes, such that there exist possible instance values
of the correct type that will fail validation.
</t>
<t>
MAY choose to implement validation of any or all format attributes
Expand All @@ -626,30 +621,6 @@
SHOULD document its level of support for validation.
</t>
</list>
<cref>
This matches the current reality of implementations, which provide
widely varying levels of validation, including no validation at all,
for some or all format attributes. It is also designed to encourage
relying only on the annotation behavior and performing semantic
validation in the application, which is the recommended best practice.
</cref>
</t>

<t>
When the vocabulary is declared with a value of true, an implementation
that supports this form of the vocabulary:
<list>
<t>
MUST evaluate "format" as an assertion unless it is explicitly
configured not to do so;
</t>
<t>
MUST implement syntactic validation for all format attributes defined
in this specification, and for any additional format attributes that
it recognizes, such that there exist possible instance values
of the correct type that will fail validation.
</t>
</list>
The requirement for minimal validation of format attributes is intentionally
vague and permissive, due to the complexity involved in many of the attributes.
Note in particular that the requirement is limited to syntactic checking; it is
Expand All @@ -666,20 +637,20 @@
an "@" is clearly not a valid email address, and an "email" or "hostname"
containing characters outside of 7-bit ASCII is likewise clearly invalid.
</cref>
<cref>
This matches the current reality of implementations, which provide
widely varying levels of validation, including no validation at all,
for some or all format attributes. It is also designed to encourage
relying only on the annotation behavior and performing semantic
validation in the application, which is the recommended best practice.
</cref>
</t>

<t>
It is RECOMMENDED that implementations use a common parsing library for each format,
or a well-known regular expression. Implementations SHOULD clearly document
how and to what degree each format attribute is validated.
</t>
<t>
The <xref target="meta-schema">standard core and validation meta-schema</xref>
includes this vocabulary in its "$vocabulary" keyword with a value of false,
since by default implementations are not required to support this keyword
as an assertion. Supporting the format vocabulary with a value of true is
understood to greatly increase code size and in some cases execution time,
and will not be appropriate for all implementations.
</t>
</section>
<section title="Custom format attributes">
<t>
Expand Down