Skip to content

Commit cd49ab9

Browse files
gregsdennisgregsdennis
committed
start on proposal (with adr)
1 parent 39415d8 commit cd49ab9

File tree

2 files changed

+169
-0
lines changed

2 files changed

+169
-0
lines changed

‎proposals/vocabularies-adr.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# [short title of solved problem and solution]
2+
3+
* Status: proposed
4+
* Deciders: @gregsdennis, @jdesrosiers
5+
* Date: 2024-06-10
6+
7+
Technical Story:
8+
9+
- Issues discussing feature - https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aopen+is%3Aissue+label%3Avocabulary
10+
- ADR to extract from the spec and use feature life cycle - https://github.com/json-schema-org/json-schema-spec/pull/1510
11+
12+
## Context and Problem Statement
13+
14+
The current approach to extending JSON Schema by providing custom keywords is
15+
very implementation-specific and therefore not interoperable.
16+
17+
To address this deficiency, this document proposes vocabularies as a concept
18+
and a new Core keyword, `$vocabulary` to support it.
19+
20+
## Decision Drivers <!-- optional -->
21+
22+
- Language-agnostic
23+
- Ease of use
24+
- Ease of implementation
25+
26+
## Considered Options
27+
28+
### Current design as included in 2019-09 and 2020-12.
29+
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.
32+
33+
An implementation declares support for a particular vocabulary via
34+
implementation of its keywords and documentation.
35+
36+
`$vocabulary` keyword is an object with URI keys and boolean values. The URIs
37+
identify each vocab, and the values indicate whether the implementation must
38+
"understand" that vocab in order to process the schema. This keyword is only
39+
processed when it is found as part of a meta-schema.
40+
41+
* Good because it provides a language-agnostic mechanism that's built into JSON
42+
Schema itself
43+
* Bad because unknown keywords are now unsupported, which implies that
44+
[unknown vocabularies are implicitly unsupported](https://github.com/orgs/json-schema-org/discussions/342)
45+
46+
### [option 2]
47+
48+
[example | description | pointer to more information | …]
49+
50+
* Good, because [argument a]
51+
* Good, because [argument b]
52+
* Bad, because [argument c]
53+
* … <!-- numbers of pros and cons can vary -->
54+
55+
### [option 3]
56+
57+
[example | description | pointer to more information | …]
58+
59+
* Good, because [argument a]
60+
* Good, because [argument b]
61+
* Bad, because [argument c]
62+
* … <!-- numbers of pros and cons can vary -->
63+
64+
## Decision Outcome
65+
66+
_TBD_
67+
68+
### Positive Consequences <!-- optional -->
69+
70+
_TBD_
71+
72+
### Negative Consequences <!-- optional -->
73+
74+
_TBD_

‎proposals/vocabularies.md

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# JSON Schema Proposal: <TODO>
2+
3+
## Abstract
4+
5+
The current approach to extending JSON Schema by providing custom keywords is
6+
very implementation-specific and therefore not interoperable.
7+
8+
To address this deficiency, this document proposes vocabularies as a concept
9+
and a new Core keyword, `$vocabulary` to support it.
10+
11+
While the Core specification will define and describe vocabularies in general,
12+
the Validation specification will also need to change to incorporate some of
13+
these ideas. This proposal will be updated as necessary to reflect the changes
14+
in both documents.
15+
16+
## Current Status
17+
18+
This proposal was originally integrated into both specifications, starting with
19+
the 2019-09 release, and has been extracted as the feature is incomplete. The
20+
feature, at best effort, was extracted in such a way as to retain the
21+
functionality present in the 2020-12 release.
22+
23+
Trying to fit the 2020-12 version into the current specification, however,
24+
raises some problems, and further discussion around the design of
25+
this concept is needed.
26+
27+
## Note to Readers
28+
29+
The issues list for this proposal can be found at
30+
<https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aopen+is%3Aissue+label%3Avocabulary>.
31+
32+
For additional information, see <https://json-schema.org/>.
33+
34+
To provide feedback, use this issue tracker or any of the communication methods
35+
listed on the homepage.
36+
37+
## Table of Contents
38+
39+
## Conventions and Terminology
40+
41+
All conventions and terms used and defined by the JSON Schema Core specification
42+
also apply to this document.
43+
44+
## Overview
45+
46+
### Problem Statement
47+
48+
The specification allows implementations to support user-defined keywords. However, this vague and open allowance has drawbacks.
49+
50+
1. This isn't a requirement, it is a permission. An implementation could just as easily choose _not_ to support user-defined keywords.
51+
2. There is no prescribed mechanism by which an implementation should provide this support. As a result, each implementation that _does_ have the feature supports it in different ways.
52+
3. Support for any given user-defined keyword will be limited to that implementation. There is no guarantee that the keyword will be supported in another implementation, and unless the user explicitly configures the other implementation, their keywords likely will not be supported.
53+
54+
This exposes a need for the specification(s) to define a way for implementations to share knowledge of a keyword or group of keywords.
55+
56+
### Solution
57+
58+
<!-- What is the solution? Include examples of use. -->
59+
60+
### Limitations
61+
62+
<!-- Are there any limitations inherent to the proposal? -->
63+
64+
## Change Details
65+
66+
<!--
67+
This is where the specification changes are defined. This must be precise as
68+
these changes will be made verbatim.
69+
70+
For example
71+
72+
1. The following section will be added to the JSON Schema Core specification as
73+
a subsection of "Keywords for Applying Subschemas Conditionally".
74+
> ### {New section name}
75+
>
76+
> {Feature description}
77+
2. The following subschema will be added to the Applicator Vocabulary schema,
78+
`https://json-schema.org/<version>/<release>/meta/applicator`, at
79+
`/properties/{keyword}`:
80+
```jsonc
81+
{
82+
// keyword schema
83+
}
84+
```
85+
-->
86+
87+
## [Appendix] Change Log
88+
89+
* [MMMM YYYY] Created
90+
91+
## [Appendix] Champions
92+
93+
| Champion | Company | Email | URI |
94+
|----------------------------|---------|-------------------------|----------------------------------|
95+
| Your Name | | | < GitHub profile page > |

0 commit comments

Comments
 (0)