Skip to content

Commit

Permalink
addressing PR comments
Browse files Browse the repository at this point in the history
  • Loading branch information
gregsdennis committed Jun 21, 2024
1 parent bc542ee commit 651f22d
Show file tree
Hide file tree
Showing 2 changed files with 14 additions and 16 deletions.
16 changes: 10 additions & 6 deletions proposals/vocabularies-adr.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,19 +27,23 @@ and a new Core keyword, `$vocabulary` to support it.

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

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

An implementation declares support for a particular vocabulary via
implementation of its keywords and documentation.
With vocabularies as the primary method for defining individual keywords,
dialects can be created by combining different vocabularies.

Users must confirm with an implementation's documentation whether a given
vocabulary is supported.

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

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

Expand Down
14 changes: 4 additions & 10 deletions proposals/vocabularies.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ support for them.

### Solution

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

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

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

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

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

#### Machine Readability

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

0 comments on commit 651f22d

Please sign in to comment.