Skip to content

Commit 651f22d

Browse files
committed
addressing PR comments
1 parent bc542ee commit 651f22d

File tree

2 files changed

+14
-16
lines changed

2 files changed

+14
-16
lines changed

proposals/vocabularies-adr.md

+10-6
Original file line numberDiff line numberDiff line change
@@ -27,19 +27,23 @@ and a new Core keyword, `$vocabulary` to support it.
2727

2828
### Current design as included in 2019-09 and 2020-12.
2929

30-
Vocabularies are external documents that describe how new keywords function.
31-
They can be in a specification style, or a blog post, or some other format.
30+
Vocabularies are collections of keywords and are defined by vocabulary document.
31+
For the 2019-09 and 2020-12 vocabularies, the documents are integrated into the
32+
specifications themselves.
3233

33-
An implementation declares support for a particular vocabulary via
34-
implementation of its keywords and documentation.
34+
With vocabularies as the primary method for defining individual keywords,
35+
dialects can be created by combining different vocabularies.
36+
37+
Users must confirm with an implementation's documentation whether a given
38+
vocabulary is supported.
3539

3640
`$vocabulary` keyword is an object with URI keys and boolean values. The URIs
3741
identify each vocab, and the values indicate whether the implementation must
3842
"understand" that vocab in order to process the schema. This keyword is only
3943
processed when it is found as part of a meta-schema.
4044

41-
* Good because it provides a language-agnostic mechanism that's built into JSON
42-
Schema itself
45+
* Good because it provides a language-agnostic method of defining extension
46+
keywords that's built into JSON Schema itself
4347
* Bad because unknown keywords are now unsupported, which implies that
4448
[unknown vocabularies are implicitly unsupported](https://github.com/orgs/json-schema-org/discussions/342)
4549

proposals/vocabularies.md

+4-10
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ support for them.
6767

6868
### Solution
6969

70-
Two new concepts, vocabularies and dialects, will be introduced into the Core
70+
This proposal introduces vocabularies as a new concept to be added to the Core
7171
specification.
7272

7373
A vocabulary is identified by an absolute URI and is used to define a set of
@@ -95,8 +95,9 @@ said to "include" that vocabulary.
9595
}
9696
```
9797

98-
A dialect is the set of vocabularies listed by a meta-schema. It is ephemeral
99-
and carries no identifier.
98+
Whereas in the current specification, a dialect is merely the set of keywords
99+
used by a schema, with this proposal a dialect is defined by the set of
100+
vocabularies listed by a meta-schema. It is ephemeral and carries no identifier.
100101

101102
_**NOTE** It is possible for two meta-schemas, which would have different `$id`
102103
values, to share a common dialect if they both declare the same set of
@@ -195,13 +196,6 @@ unknown keywords presents a problem for schemas that use keywords from optional
195196
vocabularies. (This is the topic of the discussion at
196197
https://github.com/orgs/json-schema-org/discussions/342.)
197198

198-
In short, if a schema uses a keyword from an unknown _optional_ vocabulary, the
199-
implementation cannot proceed because unknown keywords are explicitly
200-
disallowed. However, not being able to proceed with evaluation is the behavior
201-
prescribed for _required_ vocabularies. Thus, if the behaviors for required and
202-
optional vocabularies is the same, then the boolean value is moot, which
203-
highlights that the structure of `$vocabulary` needs to be reconsidered.
204-
205199
#### Machine Readability
206200

207201
The vocabulary URI is an opaque value. There is no data that an implementation

0 commit comments

Comments
 (0)