You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- For - @gregsdennis@jdesrosiers@jviotti@mwadams@karenetheridge
11
+
- Neutral - @relequestual
12
+
- Against - @julian
12
13
13
14
## Context and Problem Statement
14
15
15
16
There's a long and sticky history around format.
16
17
17
18
1. Going back all the way to Draft 01, format has never required validation.
18
-
2. Whether to support format validation has always been the decision of the implementation.
19
-
3. The extent to which formats are validated has also been the decision of the implementation.
20
-
21
-
The result of all of this is that implementation support for validation has been spotty at best. Despite the JSON Schema specs referencing very concretely defined formats (by referencing other specs), implementations that do support validation don't all support each format equally. This has been the primary driving force behind keeping format as an opt-in validation.
22
-
23
-
With 2019-09, we decided that it was time to give the option of format validation to the schema author. They could enable validation by using a meta-schema which listed the Format Vocabulary with a true value, which meant, "format validation is required to process this schema."
24
-
25
-
In 2020-12, we further refined this by offering two separate vocabularies, one that treats the keyword as an annotation and one that treats it as an assertion. The argument was that the behavior of a keyword shouldn't change based on whether the vocabulary was required or not.
26
-
27
-
However, the fact remains that our users consistently report (via questions in Slack, GitHub, and StackOverflow) that they expect format to validate. (The most recent case I can think of was only last week, in .Net's effort to build a short-term solution for schema generation from types.)
19
+
1. Whether to support format validation has always been the decision of the
20
+
implementation.
21
+
1. The extent to which formats are validated has also been the decision of the
22
+
implementation.
23
+
24
+
The result of all of this is that implementation support for validation has been
25
+
spotty at best. Despite the JSON Schema specs referencing very concretely
26
+
defined formats (by referencing other specs), implementations that do support
27
+
validation don't all support each format equally. This has been the primary
28
+
driving force behind keeping format as an opt-in validation.
29
+
30
+
With 2019-09, we decided that it was time to give the option of format
31
+
validation to the schema author. They could enable validation by using a
32
+
meta-schema which listed the Format Vocabulary with a true value, which meant,
33
+
"format validation is required to process this schema."
34
+
35
+
In 2020-12, we further refined this by offering two separate vocabularies, one
36
+
that treats the keyword as an annotation and one that treats it as an assertion.
37
+
The argument was that the behavior of a keyword shouldn't change based on
38
+
whether the vocabulary was required or not.
39
+
40
+
However, the fact remains that our users consistently report (via questions in
41
+
Slack, GitHub, and StackOverflow) that they expect format to validate. (The most
42
+
recent case I can think of was only last week, in .Net's effort to build a
43
+
short-term solution for schema generation from types.)
28
44
29
45
Due to this consistency in user expectations, we have decided to:
30
46
31
47
1. make format an assertion keyword, and
32
-
2. strictly enforce it by moving the appropriate tests into the required section of the Test Suite and building them more completely.
48
+
1. strictly enforce it by moving the appropriate tests into the required section
49
+
of the Test Suite and building them more completely.
33
50
34
51
## Decision Drivers
35
52
36
-
* User expectation
37
-
* Current behavior
38
-
* Historical context
39
-
* Disparity of current implementation support vs the proposed requirements
53
+
- User expectation
54
+
- Current behavior
55
+
- Historical context
56
+
- Disparity of current implementation support vs the proposed requirements
40
57
41
58
## Considered Options
42
59
43
60
### `format` remains an annotation keyword by default
44
61
45
-
This is the current state. The primary benefit is that we don't need to make a breaking change.
46
-
47
-
The primary downside is that the current system of (1) configuring the tool or (2) incluing the `format-assertion` vocab[^1] is confusing for many and doesn't align with user expectations.
62
+
This is the current state. The primary benefit is that we don't need to make a
63
+
breaking change.
48
64
49
-
[^1] The `format-assertion` vocabulary will no longer be an option since we have demoted vocabularies to a proposal for the stable release. This leaves tool configuration as the only option to enable `format` validation.
65
+
The primary downside is that the current system of (1) configuring the tool or
66
+
(2) incluing the `format-assertion` vocab[^1] is confusing for many and doesn't
67
+
align with user expectations.
50
68
51
69
### `format` becomes an assertion keyword by default
52
70
53
-
We change the spec to require `format` validation. Furthermore:
71
+
We change the spec to require `format` validation. Furthermore:
54
72
55
-
* Implementations SHOULD support `format` with the defined values
56
-
* Implementations MAY support others, but only by explicit config
57
-
* Implementations MUST refuse to process a schema that contains an unsupported format
73
+
- Implementations SHOULD support `format` with the defined values
74
+
- Implementations MAY support others, but only by explicit config
75
+
- Implementations MUST refuse to process a schema that contains an unsupported
76
+
format
58
77
59
78
## Decision Outcome
60
79
61
-
The TSC has decided via vote (see voting issue above) that we should change `format` to act as an assertion by default, in line with option (2).
80
+
The TSC has decided via vote (see voting issue above) that we should change
81
+
`format` to act as an assertion by default, in line with option (2).
62
82
63
83
### Positive Consequences <!-- optional -->
64
84
65
-
* Aligns with user expectations.
66
-
* Users are still able to have purely annotative behavior through use of something like `x-format`.
67
-
* Increased consistency for `format` validation across implementations.
85
+
- Aligns with user expectations.
86
+
- Users are still able to have purely annotative behavior through use of
87
+
something like `x-format`.
88
+
- Increased consistency for `format` validation across implementations.
68
89
69
90
### Negative Consequences <!-- optional -->
70
91
71
-
* This is a breaking change, which means that we will likely have to re-educate the users who correctly treat it as an annotation.
72
-
* Older schemas which do not specify a version (`$schema`) may change their validation outcome.
73
-
* The burden on implementations will be greater since format validation was previously optional.
74
-
75
-
## Links <!-- optional -->
92
+
- This is a breaking change, which means that we will likely have to re-educate
93
+
the users who correctly treat it as an annotation.
94
+
- Older schemas which do not specify a version (`$schema`) may change their
95
+
validation outcome.
96
+
- The burden on implementations will be greater since format validation was
97
+
previously optional.
76
98
77
-
*[Link type][Link to ADR]<!-- example: Refined by [ADR-0005](0005-example.md) -->
78
-
* … <!-- numbers of links can vary -->
99
+
[^1]: The `format-assertion` vocabulary will no longer be an option since we
100
+
have demoted vocabularies to a proposal for the stable release. This leaves tool
101
+
configuration as the only option to enable `format` validation.
0 commit comments