diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 48ecff5b..eecb49d8 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -15,9 +15,9 @@ Thanks for submitting a pull request! Please provide enough information so that ### Issue & Discussion References -- Closes #___ -- Related to #___ -- Others? +- Closes #___ +- Related to #___ +- Others? ### Summary diff --git a/.github/SECURITY.md b/.github/SECURITY.md index 87b438e3..8b847267 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -1,11 +1,24 @@ # Reporting Security Issues -The JSON Schema project does not house any implementation of JSON Schema itself. If you have found a security issue in any implementation of JSON Schema, please contact the appropriate maintainers, per the projects security reporting guidelines, if any. +The JSON Schema project does not house any implementation of JSON Schema itself. +If you have found a security issue in any implementation of JSON Schema, please +contact the appropriate maintainers, per the projects security reporting +guidelines, if any. -To report a security issue, please use the GitHub Security Advisory "https://github.com/json-schema-org/json-schema-spec/security/advisories/new" tab. +To report a security issue, please use the GitHub Security Advisory +"" +tab. -If you find a security issue in relation to the JSON Schema specification or another repository within this GitHub organization, please use the above. +If you find a security issue in relation to the JSON Schema specification or +another repository within this GitHub organization, please use the above. -The JSON Schema project TSC will review and respond to all security reports. Please follow [coordinated disclosure](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/about-coordinated-disclosure-of-security-vulnerabilities). +The JSON Schema project TSC will review and respond to all security reports. +Please follow [coordinated disclosure](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/about-coordinated-disclosure-of-security-vulnerabilities). + +If you are a maintainer of an implementation, please consider [adding a security +policy](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository). +If you need assistance in understanding a report, or remediation of a confirmed +issue, please feel free to reach out to us on our Slack server, in the +`#implementations` channel, and ask for a temporary private channel to discuss +your situation or concerns. -If you are a maintainer of an implementation, please consider [adding a security policy](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository). If you need assistance in understanding a report, or remediation of a confirmed issue, please feel free to reach out to us on our Slack server, in the `#implementations` channel, and ask for a temporary private channel to discuss your situation or concerns. \ No newline at end of file diff --git a/.remarkrc-lint.js b/.remarkrc-lint.js index f628bc82..1e60073f 100644 --- a/.remarkrc-lint.js +++ b/.remarkrc-lint.js @@ -5,6 +5,7 @@ import remarkPresetLintMarkdownStyleGuide from "remark-preset-lint-markdown-styl import remarkLintListItemIndent from "remark-lint-list-item-indent"; import remarkLintListItemSpacing from "remark-lint-list-item-spacing"; import remarkLintNoFileNameMixedCase from "remark-lint-no-file-name-mixed-case"; +import remarkLintNoFileNameIrregularCharacters from "remark-lint-no-file-name-irregular-characters"; export default { @@ -15,6 +16,7 @@ export default { remarkPresetLintMarkdownStyleGuide, [remarkLintListItemIndent, "one"], [remarkLintListItemSpacing, { checkBlanks: true }], - [remarkLintNoFileNameMixedCase, false] + [remarkLintNoFileNameMixedCase, false], + [remarkLintNoFileNameIrregularCharacters, false] ] }; diff --git a/.remarkrc.js b/.remarkrc.js new file mode 100644 index 00000000..95040a50 --- /dev/null +++ b/.remarkrc.js @@ -0,0 +1,10 @@ +import remarkGfm from "remark-gfm"; +import lintPreset from "./.remarkrc-lint.js"; + + +export default { + plugins: [ + remarkGfm, + lintPreset + ] +}; diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a196f61e..a2fa14aa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,45 +2,71 @@ ## Contributing to JSON Schema Specification -Thanks for taking the time to contribute! 🎉👍 +Thanks for taking the time to contribute! 🎉👍 -JSON Schema is an evolving language. This repository contains the specification text as well as Pull Requests with suggested improvements and contributions. +JSON Schema is an evolving language. This repository contains the specification +text as well as Pull Requests with suggested improvements and contributions. -Contributions that do not change the interpretation of the spec but instead improve legibility, fix editorial errors, clear up ambiguity and improve examples are encouraged and are often merged by a spec editor with little process. +Contributions that do not change the interpretation of the spec but instead +improve legibility, fix editorial errors, clear up ambiguity and improve +examples are encouraged and are often merged by a spec editor with little +process. -However, contributions that _do_ meaningfully change the interpretation of the spec must follow the Specification Development Process which is ⚠️currently under discussion and development⚠️. +However, contributions that *do* meaningfully change the interpretation of the +spec must follow the [Specification Development Process](./PROCESS.md). ## Issues -Issues should identify a problem, enhancement, or use case; and propose some course of action for the draft. For alternate support channels, see the [SUPPORT.md](https://github.com/json-schema-org/.github/blob/main/SUPPORT.md). +Issues should identify a problem, enhancement, or use case; and propose some +course of action for the draft. For alternate support channels, see the +[SUPPORT.md](https://github.com/json-schema-org/.github/blob/main/SUPPORT.md). ## Pull Requests -We welcome pull requests, both for editorial suggestions and to resolve open issues. +We welcome pull requests, both for editorial suggestions and to resolve open +issues. -If the pull request would solve a particular issue, reference the issue in the pull request description. +If the pull request would solve a particular issue, reference the issue in the +pull request description. -Changes that would affect implementation behavior should typically be opened as an issue first. +Changes that would affect implementation behavior should typically be opened as +an issue first. -Generally, pull requests should be made to the `main` branch unless it is a patch update and we are in a patch phase. In that case there will be a branch named something like `2020-12-patch` that the PR should target instead. +Generally, pull requests should be made to the `main` branch unless it is a +patch update and we are in a patch phase. In that case there will be a branch +named something like `2020-12-patch` that the PR should target instead. -Most PRs, including all PRs that impact implementation behavior, will be left open for a minimum of 14 days. Minor wording fixes may be merged more quickly once approved by a project member. +Most PRs, including all PRs that impact implementation behavior, will be left +open for a minimum of 14 days. Minor wording fixes may be merged more quickly +once approved by a project member. ## Milestones -Each milestone is an estimation of the work that will be done for the next draft. Milestones are typically named after the meta-schema draft number, and the _open_ milestone with the lowest draft number is the current active project. +Each milestone is an estimation of the work that will be done for the next +draft. Milestones are typically named after the meta-schema draft number, and +the *open* milestone with the lowest draft number is the current active project. -Issues may be removed from a milestoned due to lack of consensus, lack of anyone with the correct expertise to make a PR, or simply because we wish to publish a draft and defer the remaining issues to the next draft. +Issues may be removed from a milestoned due to lack of consensus, lack of anyone +with the correct expertise to make a PR, or simply because we wish to publish a +draft and defer the remaining issues to the next draft. -Numbered milestones other than the lowest-numbered one are used to tentatively organize future work, but may be completely reorganized once work on that draft actually begins. +Numbered milestones other than the lowest-numbered one are used to tentatively +organize future work, but may be completely reorganized once work on that draft +actually begins. -The `draft-future` milestone is for issues for which there is an agreement that they should be addressed, but no specific timeline. +The `draft-future` milestone is for issues for which there is an agreement that +they should be addressed, but no specific timeline. ## Code of Conduct -All official channels including the mailing list, GitHub organization and Slack server, follow our [Code of Conduct](https://github.com/json-schema-org/.github/blob/main/CODE_OF_CONDUCT.md). +All official channels including the mailing list, GitHub organization and Slack +server, follow our +[Code of Conduct](https://github.com/json-schema-org/.github/blob/main/CODE_OF_CONDUCT.md). ## Have Questions? -You can join the `#specification` channel in our [Slack workspace](https://json-schema.org/slack) to interact with other community members involved in the Specification development, share new ideas and ask questions. +You can join the `#specification` channel in our +[Slack workspace](https://json-schema.org/slack) to interact with other +community members involved in the Specification development, share new ideas and +ask questions. diff --git a/PROCESS.md b/PROCESS.md index eed30e85..b0a06cb0 100644 --- a/PROCESS.md +++ b/PROCESS.md @@ -1,97 +1,120 @@ + # JSON Schema Specification Development and Publication Process ## Purpose -This document describes the development and publication process for the JSON Schema specifications contained within this repository. +This document describes the development and publication process for the JSON +Schema specifications contained within this repository. -- [JSON Schema Core](./jsonschema-core.md) -- [JSON Schema Validation](./jsonschema-validation.md) +- [JSON Schema Core](./specs/jsonschema-core.md) +- [JSON Schema Validation](./specs/jsonschema-validation.md) ## Definitions ### Defined Behavior -Some behaviors within JSON Schema may be explicitly or implicitly undefined by the specifications for various reasons. How to handle these behaviors is generally left to implementations. +Some behaviors within JSON Schema may be explicitly or implicitly undefined by +the specifications for various reasons. How to handle these behaviors is +generally left to implementations. -A defined behavior is one that is fully and unambiguously defined by the specifications. +A defined behavior is one that is fully and unambiguously defined by the +specifications. -An undefined behavior is said to have an "indeterminate" validation result since implementations may resolve the behavior in different ways. +An undefined behavior is said to have an "indeterminate" validation result since +implementations may resolve the behavior in different ways. ### Stability and Breaking Changes -Stability is defined using the level of compatibility between sequential releases. If all schemas which are written to one release produce the same defined behavior under the following release, then those releases are compatible, and the specification is said to be stable between them. +Stability is defined using the level of compatibility between sequential +releases. If all schemas which are written to one release produce the same +defined behavior under the following release, then those releases are +compatible, and the specification is said to be stable between them. -If an existing schema under the new release exhibits defined behavior that is contrary to defined behavior under the previous release, the new release is said to contain breaking changes and the specification is unstable between those releases. +If an existing schema under the new release exhibits defined behavior that is +contrary to defined behavior under the previous release, the new release is said +to contain breaking changes and the specification is unstable between those +releases. -If a new release fully defines a previously undefined (or under-defined) behavior, the new release is still considered compatible, even if it contradicts the decision of any particular implementation. +If a new release fully defines a previously undefined (or under-defined) +behavior, the new release is still considered compatible, even if it contradicts +the decision of any particular implementation. -For reference, this table shows the validation results of a hypothetical schema and instance across two consecutive releases to illustrate the compatibility of those releases: +For reference, this table shows the validation results of a hypothetical schema +and instance across two consecutive releases to illustrate the compatibility of +those releases: -| _Next_ ➡️
⬇️ _Current_ | pass | fail | indeterminate | -|:---:|:---:|:---:|:---:| -| **pass** | ✅ | ❌ | ❌ | -| **fail** | ❌ | ✅ | ❌ | -| **indeterminate** | ✅ | ✅ | ✅ | +| *Next* ➡️
⬇️ *Current* | pass | fail | indeterminate | +| :-----------------------: | :--: | :--: | :-----------: | +| **pass** | ✅ | ❌ | ❌ | +| **fail** | ❌ | ✅ | ❌ | +| **indeterminate** | ✅ | ✅ | ✅ | ### Release -A release is any single publication of the JSON Schema specifications (as a group). +A release is any single publication of the JSON Schema specifications (as a +group). ### Version -Consecutive releases which maintain compatibility with each other comprise a version. +Consecutive releases which maintain compatibility with each other comprise a +version. ## Release and Version -The JSON Schema specification will aim to publish annually on or about the First of January each year. Releases are identified by the year they are published. +The JSON Schema specification will aim to publish annually on or about the First +of January each year. Releases are identified by the year they are published. -When a new release contains breaking changes, that release begins a new version of JSON Schema. +When a new release contains breaking changes, that release begins a new version +of JSON Schema. -The version will be identified as an integer, starting with `1` and incrementing as needed. +The version will be identified as an integer, starting with `1` and incrementing +as needed. -Stability will be prioritized when making changes to the specification. Breaking changes are undesired and should be avoided when possible. +Stability will be prioritized when making changes to the specification. Breaking +changes are undesired and should be avoided when possible. ## Publication ### Specifications -The specifications will be published on the JSON Schema website, https://json-schema.org/, using a path comprised of the version, year, and document name. For example, +The specifications will be published on the JSON Schema website, +, using a path comprised of the version, year, and +document name. For example, -``` -https://json-schema.org/1/2025/core.html -https://json-schema.org/1/2025/validation.html -``` +- `https://json-schema.org/1/2025/core.html` +- `https://json-schema.org/1/2025/validation.html` -Once a specification document has been published, neither the document (save for minor errata such as spelling mistakes) nor its publication URL may change. If the TSC elects to alter the above URL scheme, the new scheme only applies to future publications and are not retroactive. +Once a specification document has been published, neither the document (save for +minor errata such as spelling mistakes) nor its publication URL may change. If +the TSC elects to alter the above URL scheme, the new scheme only applies to +future publications and are not retroactive. ### Meta-schemas -A release meta-schema will be published under the same path using `schema.json` as the file name. +A release meta-schema will be published under the same path using `schema.json` +as the file name. -``` -https://json-schema.org/1/2025/schema.json -``` +- `https://json-schema.org/1/2025/schema.json` The website will also be configured to: -- serve the meta-schema from its release folder - ``` - https://json-schema.org/1/2025/ - ``` -- serve the meta-schema for the latest release in a version from its version folder - ``` - https://json-schema.org/1/ - ``` +- serve the meta-schema from its release folder: + `https://json-schema.org/1/2025/` +- serve the meta-schema for the latest release in a version from its version + folder: `https://json-schema.org/1/` -The latest-release meta-schemas will be updated with proposals as indicated by the [Proposal section](#proposal) of this document. +The latest-release meta-schemas will be updated with proposals as indicated by +the [Proposal section](#proposal) of this document. -```diff -@@ These are only publication and availability URLs. The specification will define the `$id` values for the meta-schemas. @@ -``` +> \[!IMPORTANT] +> These are only publication and availability URLs. The specification will +> define the `$id` values for the meta-schemas. ## Feature Life Cycle -New features will progress through a sequence of stages before being added to the specification, and existing stable features must be formally deprecated before being removed. The stages of the life cycle, in order, are: +New features will progress through a sequence of stages before being added to +the specification, and existing stable features must be formally deprecated +before being removed. The stages of the life cycle, in order, are: - Concept - Proposal @@ -117,34 +140,57 @@ stateDiagram-v2 ### Concept -The feature life cycle begins with an idea expressed in a GitHub issue in this repository. Initial discussion may occur in Slack or another space, but the life cycle does not formally begin until a GitHub issue is created. +The feature life cycle begins with an idea expressed in a GitHub issue in this +repository. Initial discussion may occur in Slack or another space, but the life +cycle does not formally begin until a GitHub issue is created. -The discussion should cover how the feature could work, use cases, syntax, alternatives, whether it’s a breaking change, etc., with a goal of deciding rough requirements. +The discussion should cover how the feature could work, use cases, syntax, +alternatives, whether it’s a breaking change, etc., with a goal of deciding +rough requirements. -During this stage, members of the Core Team will implement private prototypes of the ideas expressed in the issue to get a feel for how it integrates with the stable features. Questions to address may include: +During this stage, members of the Core Team will implement private prototypes of +the ideas expressed in the issue to get a feel for how it integrates with the +stable features. Questions to address may include: -- Does the idea operate within the confines of existing JSON Schema evaluation processes, or does it define something new? -- Is the idea merely a shortcut for some existing functionality (syntactic sugar), or does it solve a previously unsolvable problem? +- Does the idea operate within the confines of existing JSON Schema evaluation + processes, or does it define something new? +- Is the idea merely a shortcut for some existing functionality (syntactic + sugar), or does it solve a previously unsolvable problem? - What is the expected complexity for implementing the feature? -At least two (2) Core Team members must have implemented prototypes before the concept can continue to the formal proposal process. +At least two (2) Core Team members must have implemented prototypes before the +concept can continue to the formal proposal process. ### Proposal -Once a rough consensus for the idea has been reached, a formal proposal will be written, separate from the specification, with the goal of precisely defining specification changes. +Once a rough consensus for the idea has been reached, a formal proposal will be +written, separate from the specification, with the goal of precisely defining +specification changes. -The proposal will use the [Proposal Template](./proposals/proposal-template.md) and be stored in this repository's `proposals` folder. +The proposal will use the [Proposal +Template](./specs/proposals/proposal-template.md) and be stored in this +repository's `proposals` folder. -Additionally, a draft ADR will be included using the file name of the proposal document with an `-adr` suffix: `{proposal-file-name}-adr.md`. This ADR will include additional information from the "Concept" discussion. +Additionally, a draft ADR will be included using the file name of the proposal +document with an `-adr` suffix: `{proposal-file-name}-adr.md`. This ADR will +include additional information from the "Concept" discussion. Proposed keywords will be added to the appropriate vocabulary meta-schemas in: - latest published release and - the `main` branch of this repository. -The subschema for the proposed keyword will contain only a `$comment` keyword indicating that the feature is experimental and containing a link to the proposal document. Aside from the `$comment` keyword, the subschema will be empty. +The subschema for the proposed keyword will contain only a `$comment` keyword +indicating that the feature is experimental and containing a link to the +proposal document. Aside from the `$comment` keyword, the subschema will be +empty. -_This is done so that a proposed keyword is allowed but not validated as its syntax may change during the proposal/experimentation process. It also permits different implementations to support different variations of each proposal separately throughout this process. It will be up to the implementation to validate these keywords in accordance with their support._ +> \[!NOTE] +> This is done so that a proposed keyword is allowed but not validated as its +> syntax may change during the proposal/experimentation process. It also permits +> different implementations to support different variations of each proposal +> separately throughout this process. It will be up to the implementation to +> validate these keywords in accordance with their support. Tests for the proposal are added to the JSON Schema Test Suite. @@ -152,13 +198,15 @@ Tests for the proposal are added to the JSON Schema Test Suite. @@ TODO: Identify a location within the test suite for proposals. @@ ``` -Once an initial draft of the proposal has been completed and published, the feature moves into Experimentation. +Once an initial draft of the proposal has been completed and published, the +feature moves into Experimentation. ### Experimentation Implementations may begin to support the new feature. -Feedback from implementers and users are expected to result in refinements to the proposal, which will then be updated in the implementations. +Feedback from implementers and users are expected to result in refinements to +the proposal, which will then be updated in the implementations. Breaking changes to a proposed feature MAY occur, but are highly discouraged. @@ -172,30 +220,42 @@ In order to proceed to the next stage ([Stable](#stable)): @@ TODO: Determine usage metrics. @@ ``` -Experimental features are not considered to be interoperable across implementations. +Experimental features are not considered to be interoperable across +implementations. -If a proposal cannot advance to the next stage, it may be removed. The proposal document is moved to an `archive` subfolder, the keyword is removed from the meta-schemas, and any tests are moved to an `archive` subfolder. The removal of a feature which has not reached the stable state is not considered a breaking change. +If a proposal cannot advance to the next stage, it may be removed. The proposal +document is moved to an `archive` subfolder, the keyword is removed from the +meta-schemas, and any tests are moved to an `archive` subfolder. The removal of +a feature which has not reached the stable state is not considered a breaking +change. ### Stable -The feature is incorporated into the specification in the `main` branch as specified by the proposal document, and the feature will be required as of the next release. +The feature is incorporated into the specification in the `main` branch as +specified by the proposal document, and the feature will be required as of the +next release. The draft ADR is completed, dated, and moved to the `adr` folder. -The appropriate vocabulary meta-schema in the `main` branch is updated to include a subschema that validates the feature's syntax requirements. This will be made available with the next release. +The appropriate vocabulary meta-schema in the `main` branch is updated to +include a subschema that validates the feature's syntax requirements. This will +be made available with the next release. -Upon publication of the new release, the meta-schema for the lapsed release will have the keyword removed. +Upon publication of the new release, the meta-schema for the lapsed release will +have the keyword removed. The appropriate tests are incorporated into the main suite. ### Deprecated -If a feature is no longer useful, e.g. it has been replaced, it may be deprecated by indicating it as such in the specification. +If a feature is no longer useful, e.g. it has been replaced, it may be +deprecated by indicating it as such in the specification. Implementations must support deprecated features. ### Removed -A feature must have been published as deprecated for at least one release before it can be considered for removal. +A feature must have been published as deprecated for at least one release before +it can be considered for removal. Feature removal is considered a breaking change. diff --git a/README.md b/README.md index 8328f069..981d9445 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,15 @@ # Welcome to JSON Schema -[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/json-schema-org/.github/blob/main/CODE_OF_CONDUCT.md) [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![Financial Contributors on Open Collective](https://opencollective.com/json-schema/all/badge.svg?label=financial+contributors)](https://opencollective.com/json-schema) +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/json-schema-org/.github/blob/main/CODE_OF_CONDUCT.md) +[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) +[![Financial Contributors on Open Collective](https://opencollective.com/json-schema/all/badge.svg?label=financial+contributors)](https://opencollective.com/json-schema) -JSON Schema is a vocabulary that allows you to validate, annotate, and manipulate JSON documents. +JSON Schema is a vocabulary that allows you to validate, annotate, and +manipulate JSON documents. -This repository contains the sources for the **work in progress** of the next set of JSON Schema IETF Internet Draft (I-D) documents. -For the latest released I-Ds, please see the [Specification page](http://json-schema.org/specification.html) on the website. +This repository contains the sources for the **work in progress** of the next +set of JSON Schema IETF Internet Draft (I-D) documents. For the latest released +I-Ds, please see the +[Specification page](http://json-schema.org/specification.html) on the website. ## Call for contributions and feedback @@ -12,15 +17,21 @@ Reviews, comments and suggestions are most welcome! Please read our [guidelines for contributing](CONTRIBUTING.md). ## Status -For the current status of issues and pull requests, please see the following labels -[![Available](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Status:%20Available.svg?color=brightgreen)](https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aopen+is%3Aissue+label%3A%22Status%3A+Available%22) [![In Progress](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Status:%20In%20Progress.svg)](https://github.com/json-schema-org/json-schema-spec/labels/Status:%20In%20Progress) [![Review Needed](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Status:%20Review%20Needed.svg)](https://github.com/json-schema-org/json-schema-spec/labels/Status%3A%20Review%20Needed) +For the current status of issues and pull requests, please see the following +labels +[![Available](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Status:%20Available.svg?color=brightgreen)](https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aopen+is%3Aissue+label%3A%22Status%3A+Available%22) +[![In Progress](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Status:%20In%20Progress.svg)](https://github.com/json-schema-org/json-schema-spec/labels/Status:%20In%20Progress) +[![Review Needed](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Status:%20Review%20Needed.svg)](https://github.com/json-schema-org/json-schema-spec/labels/Status%3A%20Review%20Needed) [![Critical](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Priority:%20Critical.svg?color=critical -)](https://github.com/json-schema-org/json-schema-spec/labels/Priority%3A%20Critical) [![High](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Priority:%20High.svg?color=important)](https://github.com/json-schema-org/json-schema-spec/labels/Priority%3A%20High) [![Medium](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Priority:%20Medium.svg)](https://github.com/json-schema-org/json-schema-spec/labels/Priority%3A%20Medium) [![Low](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Priority:%20Low.svg)](https://github.com/json-schema-org/json-schema-spec/labels/Priority%3A%20Low) +)](https://github.com/json-schema-org/json-schema-spec/labels/Priority%3A%20Critical) +[![High](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Priority:%20High.svg?color=important)](https://github.com/json-schema-org/json-schema-spec/labels/Priority%3A%20High) +[![Medium](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Priority:%20Medium.svg)](https://github.com/json-schema-org/json-schema-spec/labels/Priority%3A%20Medium) +[![Low](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Priority:%20Low.svg)](https://github.com/json-schema-org/json-schema-spec/labels/Priority%3A%20Low) - -Labels are assigned based on [Sensible Github Labels](https://github.com/Relequestual/sensible-github-labels). +Labels are assigned based on +[Sensible Github Labels](https://github.com/Relequestual/sensible-github-labels). ## Authoring and Building @@ -38,6 +49,7 @@ a [VSCode extension](https://github.com/remarkjs/vscode-remark) we can use to get linting an link checking while developing the spec. #### Plugins + The following is a not-necessarily-complete list of configured plugins and the features they make available to you. @@ -51,7 +63,7 @@ features they make available to you. - [remark-heading-id](https://github.com/imcuttle/remark-heading-id) -- Adds support for `{#my-anchor}` syntax to add an `id` to an element so it can be referenced using URI fragment syntax. -- [remark-headings](/json-schema-org/json-schema-spec/blob/main/remark-headings.js) +- [remark-headings](/json-schema-org/json-schema-spec/blob/main/remark/remark-headings.js) -- A collection of enhancements for headings. - Adds hierarchical section numbers to headings. - Use the `%appendix%` prefix on headings that should be numbered as an @@ -60,21 +72,20 @@ features they make available to you. - Example: `#section-2-13` - Example: `#appendix-a` - Makes the heading a link utilizing its anchor -- [remark-reference-links](/json-schema-org/json-schema-spec/blob/main/remark-reference-link.js) +- [remark-reference-links](/json-schema-org/json-schema-spec/blob/main/remark/remark-reference-links.js) -- Adds new syntax for referencing a section of the spec using the section number as the link text. - - Example: + - Example: ```markdown ## Foo {#foo} - ## Bar This is covered in {{foo}} // --> Renders to "This is covered in [Section 2.3](#foo)" - Link text will use "Section" or "Appendix" as needed ``` -- [remark-table-of-contents](/json-schema-org/json-schema-spec/blob/main/remark-table-of-contents.js) +- [remark-table-of-contents](/json-schema-org/json-schema-spec/blob/main/remark/remark-table-of-contents.js) -- Adds a table of contents in a section with a header called "Table of Contents". -- [remark-code-titles](/json-schema-org/json-schema-spec/blob/main/remark-code-titles.js) +- [remark-code-titles](/json-schema-org/json-schema-spec/blob/main/remark/remark-code-titles.js) -- Add titles to code blocks - Example: ```markdown @@ -87,19 +98,19 @@ features they make available to you. escaped characters. So, to get `My "quoted" title`, you would need to be `"My \\\\"quoted\\\\" title"`. - [remark-torchlight](https://github.com/torchlight-api/remark-torchlight) -- - Syntax highlighting and more using https://torchlight.dev. Features include + Syntax highlighting and more using . Features include line numbers and line highlighting. - [remark-flexible-containers](https://github.com/ipikuka/remark-flexible-containers) -- Add a callout box using the following syntax. Supported container types are `warning`, `note`, and `experimental`. - - ``` - ::: {type} {title} - {content} - ::: - ``` + ```markdown + ::: {type} {title} + {content} + ::: + ``` ### Internet-Drafts + To build components that are being maintained as IETF Internet-Drafts, run `make`. The Makefile will create the necessary Python venv for you as part of the regular make target. @@ -115,10 +126,10 @@ The version of "xml2rfc" that this project uses is updated by modifying Descriptions of the xml2rfc, I-D documents, and RFC processes: -* https://xml2rfc.tools.ietf.org/authoring/draft-mrose-writing-rfcs.html -* https://www.ietf.org/tao.html -* https://www.ietf.org/ietf-ftp/1id-guidelines.html -* https://www.rfc-editor.org/rfc/rfc7322.txt +- +- +- +- ## Test suites @@ -127,7 +138,7 @@ Conformance tests for JSON Schema and its vocabularies may be found ## The website -The JSON Schema web site is at http://json-schema.org/ +The JSON Schema web site is at The source for the website is [maintained in a separate repository](https://github.com/json-schema-org/website). @@ -135,15 +146,16 @@ The source for the website is [maintained in a separate repository](https://gith ### Code Contributors -This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)]. +This project exists thanks to all the people who contribute. \[[Contribute](CONTRIBUTING.md)]. ### Financial Contributors -Become a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/json-schema/contribute)] +Become a financial contributor and help us sustain our community. \[[Contribute](https://opencollective.com/json-schema/contribute)] + #### Sponsors -Here are our top sponsors. You could be next! [[Become a sponsor](https://opencollective.com/json-schema#sponsor)] +Here are our top sponsors. You could be next! \[[Become a sponsor](https://opencollective.com/json-schema#sponsor)] @@ -162,4 +174,5 @@ Here are our top sponsors. You could be next! [[Become a sponsor](https://openco ## License -The contents of this repository are [licensed under](./LICENSE) either the BSD 3-clause license *or* the Academic Free License v3.0. +The contents of this repository are [licensed under](./LICENSE) either the BSD +3-clause license *or* the Academic Free License v3.0. diff --git a/adr/2022-04-08-cref-for-ambiguity-and-fix-later-gh-spec-issue-1172.md b/adr/2022-04-08-cref-for-ambiguity-and-fix-later-gh-spec-issue-1172.md index 5e83dd95..548b5b86 100644 --- a/adr/2022-04-08-cref-for-ambiguity-and-fix-later-gh-spec-issue-1172.md +++ b/adr/2022-04-08-cref-for-ambiguity-and-fix-later-gh-spec-issue-1172.md @@ -1,91 +1,115 @@ + # Acknowledge ambiguity in additionalProperties behaviour and fix after patch release -* Status: accepted -* Deciders: @relequestual @gregsdennis, @jdesrosiers, @karenetheridge -* Date: 2022-05-19 +- Status: accepted +- Deciders: @relequestual @gregsdennis, @jdesrosiers, @karenetheridge +- Date: 2022-05-19 Related... -Issue: https://github.com/json-schema-org/json-schema-spec/issues/1172 +Issue: -Discussion: https://github.com/json-schema-org/community/discussions/57 +Discussion: -Pull Request: https://github.com/json-schema-org/json-schema-spec/pull/1203 +Pull Request: ## Context and Problem Statement -When we changed the specification to use annotations as the context in which some keywords behave, we included a clause that allowed implementations which didn't use annotations to optimize the processing of `additionalProperties` in another way which produces the same effect as the prior behaviour. -This section created an ambiguity in terms of the resulting output format, but not validation. +When we changed the specification to use annotations as the context in which +some keywords behave, we included a clause that allowed implementations which +didn't use annotations to optimize the processing of `additionalProperties` in +another way which produces the same effect as the prior behaviour. This section +created an ambiguity in terms of the resulting output format, but not +validation. -We needed to decide on how to proceed for the patch release of the 2020-12 version of the specification. +We needed to decide on how to proceed for the patch release of the 2020-12 +version of the specification. -The two above links are to a GitHub Discussion and a GitHub Issue detailing the problems. -Details with an example of the problem can be seen in the Discussion's opening post specifically. +The two above links are to a GitHub Discussion and a GitHub Issue detailing the +problems. Details with an example of the problem can be seen in the Discussion's +opening post specifically. ## Decision Drivers -* The "patch release" should not change anything functionally -* Annotations as they are, are confusing to users, implementers, and specification editors alike -* Patch release is behind schedule -* There are currently no tests for the output format -* It's hard to see any immediate consensus on changing the annotation based behaviour +- The "patch release" should not change anything functionally +- Annotations as they are, are confusing to users, implementers, and + specification editors alike +- Patch release is behind schedule +- There are currently no tests for the output format +- It's hard to see any immediate consensus on changing the annotation based + behaviour ## Considered Options -* [Leaving it "as is" and do nothing](https://github.com/json-schema-org/community/discussions/57#discussioncomment-1413777) -* [Pick one](https://github.com/json-schema-org/community/discussions/57#discussioncomment-1416683) of the behaviours -* [Revert back to draft-07 behaviour](https://github.com/json-schema-org/community/discussions/57#discussioncomment-1453723) -* [Reinterpret how we understand annotation collection](https://github.com/json-schema-org/json-schema-spec/issues/1172#issuecomment-1049686478) to allow reading annotations within the same schema object regardless of assertion results -* [Acknowledge and accept that two approaches and results are allowable](https://github.com/json-schema-org/community/issues/161#issue-1173742930) -* Redefine annotation collection behaviour and/or how `additionalProperties` works +- [Leaving it "as is" and do nothing](https://github.com/json-schema-org/community/discussions/57#discussioncomment-1413777) +- [Pick one](https://github.com/json-schema-org/community/discussions/57#discussioncomment-1416683) + of the behaviours +- [Revert back to draft-07 behaviour](https://github.com/json-schema-org/community/discussions/57#discussioncomment-1453723) +- [Reinterpret how we understand annotation collection](https://github.com/json-schema-org/json-schema-spec/issues/1172#issuecomment-1049686478) + to allow reading annotations within the same schema object regardless of + assertion results +- [Acknowledge and accept that two approaches and results are allowable](https://github.com/json-schema-org/community/issues/161#issue-1173742930) +- Redefine annotation collection behaviour and/or how `additionalProperties` + works ## Decision Outcome -Chosen option: "Acknowledge and accept that two approaches and results are allowable", because +Chosen option: "Acknowledge and accept that two approaches and results are +allowable", because -* Leaving it "as is" will continue to cause confusion -* The change is non-functional which is required for the patch release -* The patch release is behind schedule -* Finding consensus of other solutions proved to be difficult -* There's no test suite for the output format, so it's not easy to see unintended consequences of a functional change -* We need to properly re-evaluate annotation collection and how annotations are used by other keywords +- Leaving it "as is" will continue to cause confusion +- The change is non-functional which is required for the patch release +- The patch release is behind schedule +- Finding consensus of other solutions proved to be difficult +- There's no test suite for the output format, so it's not easy to see + unintended consequences of a functional change +- We need to properly re-evaluate annotation collection and how annotations are + used by other keywords ### Positive Consequences -* Patch release can move forward -* Validation result is not impacted -* Confusion is at least seen and acknowledged -* Implementations which pick either approach are seen to be compliant +- Patch release can move forward +- Validation result is not impacted +- Confusion is at least seen and acknowledged +- Implementations which pick either approach are seen to be compliant ### Negative Consequences -* May have an impact for downstream tools which process full output data -* A test suite (not yet developed) which covers this situation needs to allow for multiple valid answers +- May have an impact for downstream tools which process full output data +- A test suite (not yet developed) which covers this situation needs to allow + for multiple valid answers ## Pros and Cons of the Options ### Leaving it "as is" and do nothing -Agree to do nothing and hope for the best. There isn't any downstream tooling yet anyway. +Agree to do nothing and hope for the best. There isn't any downstream tooling +yet anyway. -* Good, because no functional change -* Good, because no impact on downstream tooling -* Bad, because leaves a known ambiguity in the specification +- Good, because no functional change +- Good, because no impact on downstream tooling +- Bad, because leaves a known ambiguity in the specification + ### Pick one / Revert to draft-07 behaviour / Reinterpret annotation collection -* Good, because ambiguity is removed -* Good, because not many tools will be effected -* Bad, because it can be seen as a functional change (not really allowed for the patch release) -* Bad, because it can break existing implementations and downstream tools -* Bad, because without a test suite it's hard to see unexpected consequences +- Good, because ambiguity is removed +- Good, because not many tools will be effected +- Bad, because it can be seen as a functional change (not really allowed for the + patch release) +- Bad, because it can break existing implementations and downstream tools +- Bad, because without a test suite it's hard to see unexpected consequences ## Links -* Issue: [Ambiguous behaviour of additionalProperties when invalid](https://github.com/json-schema-org/json-schema-spec/issues/1172) -* Discussion: [The meaning of "additionalProperties" has changed](https://github.com/json-schema-org/community/discussions/57) -* Resolving Pull Request: [Add CREF about ambiguous behaviour of additionalProperties](https://github.com/json-schema-org/json-schema-spec/pull/1203) -* Alternative solution proposal: [Resolve contradictions in the described behaviour of "additionalProperties" and "items"](https://github.com/json-schema-org/json-schema-spec/pull/1154) - -* [Result of discussing](https://github.com/json-schema-org/json-schema-spec/issues/1172#issuecomment-1063962900) on an Open Community Working Meeting call - @jdesrosiers proposed a less controversial and more agreeable solution to add a comment that both are allowable -* [Related GitHub Discussion](https://github.com/json-schema-org/community/discussions/67) on alternative behaviour for `unevaluated*` keywords +- Issue: [Ambiguous behaviour of additionalProperties when invalid](https://github.com/json-schema-org/json-schema-spec/issues/1172) +- Discussion: [The meaning of "additionalProperties" has changed](https://github.com/json-schema-org/community/discussions/57) +- Resolving Pull Request: [Add CREF about ambiguous behaviour of additionalProperties](https://github.com/json-schema-org/json-schema-spec/pull/1203) +- Alternative solution proposal: [Resolve contradictions in the described + behaviour of "additionalProperties" and "items"](https://github.com/json-schema-org/json-schema-spec/pull/1154) +- [Result of discussing](https://github.com/json-schema-org/json-schema-spec/issues/1172#issuecomment-1063962900) + on an Open Community Working Meeting call - @jdesrosiers proposed a less + controversial and more agreeable solution to add a comment that both are + allowable +- [Related GitHub Discussion](https://github.com/json-schema-org/community/discussions/67) + on alternative behaviour for `unevaluated*` keywords diff --git a/adr/2022-09-decouple-from-ietf.md b/adr/2022-09-decouple-from-ietf.md index f7a190fa..6ec72ff2 100644 --- a/adr/2022-09-decouple-from-ietf.md +++ b/adr/2022-09-decouple-from-ietf.md @@ -1,15 +1,15 @@ # Decoupling from IETF -* Status: accepted -* Deciders: @jdesrosiers @relequestual @awwright @handrews @gregsdennis -* Date: 2022-09-27 +- Status: accepted +- Deciders: @jdesrosiers @relequestual @awwright @handrews @gregsdennis +- Date: 2022-09-27 Related Issues: -* https://github.com/orgs/json-schema-org/discussions/69 - This issue is about +- - This issue is about dropping the "draft" prefix from our releases. This ADR doesn't cover that, but much of the discussion about whether or not to decouple from IETF is in that discussion. -* This topic has been discussed in many other places as well that are difficult +- This topic has been discussed in many other places as well that are difficult to link to here including Slack, Twitter, OCWMs, and conference discussions. ## Context and Problem Statement @@ -26,29 +26,29 @@ that our "drafts" are intended for use in production. ## Decision Drivers -* IETF's draft versioning system doesn't work for JSON Schema and we stopped +- IETF's draft versioning system doesn't work for JSON Schema and we stopped using it to version our releases a while ago. We now use date based versioning and even have more than one draft submission per release (the initial release and the patch release). -* The IETF process is optimized for working on a draft until it's done and then +- The IETF process is optimized for working on a draft until it's done and then disbanding. In some cases, the RFC may be revisited and revised in the future, but this is rare and generally contains little more than clarifications and reference updates. JSON Schema is not like that. JSON Schema is more like a programming language. When it stops evolving, it will lose its relevance. When we finish a release of JSON Schema, we don't disband, we start work on the next release. -* Since the project resumed activity after the gap following draft-04, every one +- Since the project resumed activity after the gap following draft-04, every one of our releases is expected to be used in production and will be depended on for many years forward. This is not consistent with normal IETF drafts. Even if we don't publicly use the term "draft", we're still using the IETF I-D system in a way that's not intended. -* Under IETF, JSON Schema fits under the category of "draft". The community has +- Under IETF, JSON Schema fits under the category of "draft". The community has repeatedly told us that they perceive this to meant that JSON Schema "incomplete" and not "not ready for production use". This is the wrong message for us to be sending as all of our releases are intended to be used in production. This ADR doesn't decide whether or not to drop the "draft" from our releases, but decoupling from IETF gives us that option. -* Several members of the JSON Schema team have interacted with JSON-related IETF +- Several members of the JSON Schema team have interacted with JSON-related IETF working groups. Some of these interactions demonstrated an indifference or hostility to JSON Schema, and a preference for projects taking a different approach. Equally important was a lack of any active interest or constructive @@ -66,12 +66,12 @@ that our "drafts" are intended for use in production. 1. Continue to submit I-Ds, while using our customized process with no intention of pursing standards track RFC status. -2. Go all-in with IETF and pursue a standards track RFC with the IETF. The +1. Go all-in with IETF and pursue a standards track RFC with the IETF. The approach would be to describe the essential characteristics of evaluating a JSON Schema: the keywords that everybody is guaranteed to support, and any extension mechanisms. -3. Join W3C and pursue a standards track with them using their process. -4. Decouple completely from any standards organization and come up with our own +1. Join W3C and pursue a standards track with them using their process. +1. Decouple completely from any standards organization and come up with our own specification development lifecycle (SDLC) model inspired by well established projects with an SDLC that more closely meets or needs. @@ -140,20 +140,20 @@ to be an exception to the rule, and not frequently used. ### Positive Consequences -* Decoupling from IETF allows us to distance ourselves from the assumptions that +- Decoupling from IETF allows us to distance ourselves from the assumptions that people make about JSON Schema because they assume it works like a typical I-D. -* Decoupling from IETF allows us to customize our SDLC model to what works best +- Decoupling from IETF allows us to customize our SDLC model to what works best for JSON Schema. ### Negative Consequences -* If we don't go the standardization route with IETF or W3C, we lose access to +- If we don't go the standardization route with IETF or W3C, we lose access to their expert review process. -* Not being associated with a recognized standards organization such as IETF, +- Not being associated with a recognized standards organization such as IETF, W3C, or IEEE reduces the credibility of JSON Schema in the eyes of some. However, we have received feedback that our membership with OpenJS/Linux Foundation provides the credibility that we need. -* One of the benefits of an RFC is other standards can normatively reference it, +- One of the benefits of an RFC is other standards can normatively reference it, and use JSON Schema to define their JSON-based syntaxes. However, we have received feedback from people involved in standards development that told us that they were comfortable referencing OpenAPI's self published specification @@ -162,7 +162,7 @@ to be an exception to the rule, and not frequently used. member of the OpenJS Foundation, which is a sub-group of the Linux Foundation, so we expect standards developers to be just as comfortable referencing JSON Schema as they are referencing OpenAPI. -* Defining our own SLDC process will be a lot of work and none of us have +- Defining our own SLDC process will be a lot of work and none of us have expertise in defining such a process. However, we can take inspiration from existing well established projects and we would have the freedom to update our process as we learn what works and what doesn't. diff --git a/adr/2022-11-stable-spec.md b/adr/2022-11-stable-spec.md index b51595cf..0fa8b47a 100644 --- a/adr/2022-11-stable-spec.md +++ b/adr/2022-11-stable-spec.md @@ -1,31 +1,35 @@ # Selecting a new specification development process -* Status: accepted -* Deciders: @jdesrosiers @relequestual @awwright @handrews @gregsdennis -* Date: 2022-11-02 +- Status: accepted +- Deciders: @jdesrosiers @relequestual @awwright @handrews @gregsdennis +- Date: 2022-11-02 ## Context and Problem Statement + We've chosen to decouple our process from IETF, so we need to choose a new specification development process to replace it. ## Decision Drivers -* Dropping the "draft" label is an important driver of this change. It's mostly + +- Dropping the "draft" label is an important driver of this change. It's mostly an artifact of the IETF process and has proven to be confusing for the community. -* The community wants a stable version of JSON Schema. -* There is a need for JSON Schema to continue to evolve to meet evolving +- The community wants a stable version of JSON Schema. +- There is a need for JSON Schema to continue to evolve to meet evolving needs. -* There is a demand for custom keywords/vocabularies/dialects and we want to +- There is a demand for custom keywords/vocabularies/dialects and we want to continue to support those use cases. -* There is a need to ease the burden of implementations supporting multiple +- There is a need to ease the burden of implementations supporting multiple versions of JSON Schema. ## Considered Options + There have been two proposals put forward. Both address the goal of a stable specification with the ability to evolve. The third option represents sticking with the status quo. ### Option 1 - TC-39 Inspired + The spec would be converted from I-D XML to Markdown, but can otherwise be structured however we choose. A system would be put in place to allow us to flag the stability level of any feature in the spec. There would be only one version @@ -43,6 +47,7 @@ unstable features to "stable" status. Releases would happen once a year and be designated by the year they were released. ### Option 2 - IETF Inspired + The spec would be reorganized into two parts: "Core Semantics" and "Standard Extensions". Changes to either spec are subject to strict backward and forward compatibility requirements and would be released as a new spec that replaces and @@ -65,6 +70,7 @@ ubiquitous that they should be considered essential for implementations to support. ### Option 3 - Minimal Change + Option 3 represents the minimal amount of change to our process from what we have been doing. The spec would need to be converted from I-D XML to a Markdown version that would be served on the website, but otherwise we would continue to @@ -73,6 +79,7 @@ patch releases mid-cycle. Each release is a distinct version of JSON Schema and has no compatibility guarantees between versions. ## Decision Outcome + The decision is to go with Option 1 while leaving discussion open for aspects of Option 2 that could be adopted within the constraints of Option 1. @@ -90,6 +97,7 @@ the spec and restructuring is allowed at any time as long as it doesn't break compatibility requirements. ## Pros and Cons of the Options + The biggest benefit is shared between Option 1 and Option 2. Both approaches result in a stable spec. This will have benefits for both implementers and users. Because of the compatibility requirements, whenever you write a schema, @@ -99,7 +107,9 @@ separate code with different semantics in different versions. They just need to code for the current release and they will automatically have support for past releases (not including "draft" releases). + ### Option 1 - TC-39 Inspired + The two things that make this option stand out are the stability model governing spec evolution and the mutability of the spec document. @@ -138,7 +148,9 @@ take two years for a feature to reach stability which could be a long time to wait for users who need to stick to the stable feature set but could benefit greatly from a new feature. + ### Option 2 - IETF Inspired + The benefit of this approach is that it's compatible with the IETF process without imposing some of the constraints and perception issues that we had with our previous process. We can pursue an RFC in the future if we choose to without @@ -159,6 +171,7 @@ compatibility requirements, so we have to go extra slow to make sure we get it right. ### Option 3 - Minimal Changes + The benefit of this solution is that we don't have the overhead of defining and/or learning a new process. In the short term, we can put more effort into improving JSON Schema if we don't have the distraction of defining a whole new @@ -167,15 +180,15 @@ with the "draft" label and doesn't provide the stability the community is looking for. ## Links -* https://github.com/jdesrosiers/json-schema-spec/blob/main/adr/2022-09-decouple-from-ietf.md - - The ADR for the decision to decouple from IETF -* https://github.com/orgs/json-schema-org/discussions/234 - Proposal submitted +- + \- The ADR for the decision to decouple from IETF +- - Proposal submitted by @jdesrosiers for a process to replace the IETF based process we'd been using. -* https://github.com/orgs/json-schema-org/discussions/257 - @awwright's vision +- - @awwright's vision for JSON Schema including how it can continue to evolve while still having a stable core. -* https://github.com/json-schema-org/community/discussions/119 - When we first +- - When we first started talking about forward compatibility and a stable spec. - * https://json-schema.org/blog/posts/future-of-json-schema - User friendly + - - User friendly comments on decoupling from the IETF. diff --git a/adr/2023-04-sva-prefix.md b/adr/2023-04-sva-prefix.md index c398bc7a..97bdca83 100644 --- a/adr/2023-04-sva-prefix.md +++ b/adr/2023-04-sva-prefix.md @@ -1,31 +1,36 @@ # Supporting Single-Value Annotations via a Defined Prefix -* Status: accepted -* Deciders: @relequestual, @gregsdennis, @jdesrosiers, @karenetheridge, @awwright, @julian -* Date: 2023-04-04 +- Status: accepted +- Deciders: @relequestual, @gregsdennis, @jdesrosiers, @karenetheridge, + @awwright, @julian +- Date: 2023-04-04 Related: - Discussions: - - Disallow Unknown Keywords - https://github.com/orgs/json-schema-org/discussions/241 - - Support SVAs - https://github.com/orgs/json-schema-org/discussions/329 + - Disallow Unknown Keywords - + - Support SVAs - - PRs: - - https://github.com/json-schema-org/json-schema-spec/pull/1387 (proposal) + - (proposal) ## Context and Problem Statement -Dropping support for unknown keywords was a necessary step toward providing stability guarantees. However, the community's reaction to this news was not encouraging. How can we still support keywords that are merely collected as annotations and provide no functionality (single-value annotations, or SVAs)? +Dropping support for unknown keywords was a necessary step toward providing +stability guarantees. However, the community's reaction to this news was not +encouraging. How can we still support keywords that are merely collected as +annotations and provide no functionality (single-value annotations, or SVAs)? ## Decision Drivers -* Future-proofing - We want to ensure that we can still add keywords to the spec without breaking existing schemas. -* Implementation supportability - Is the proposal feasible to implement? -* Community preference +- Future-proofing - We want to ensure that we can still add keywords to the spec + without breaking existing schemas. +- Implementation supportability - Is the proposal feasible to implement? +- Community preference ## Considered Options 1. A defined prefix or other convention for SVAs - 1. Optionally defined by a new `$sigil` keyword + 1. Optionally defined by a new `$sigil` keyword 1. Inlined vocabularies that can define SVAs 1. A new core keyword that lists SVAs, e.g. `$ignored` 1. A defined configuration option to allow/forbid unknown keywords @@ -35,19 +40,23 @@ Dropping support for unknown keywords was a necessary step toward providing stab Chosen option: A defined prefix or other convention. -This option was chosen because it solves the problem in a clean way that can be easily implemented. It was also the favorite solution among the team members as well as the community. +This option was chosen because it solves the problem in a clean way that can be +easily implemented. It was also the favorite solution among the team members as +well as the community. Specifically, the prefix `x-` has been selected. ### Positive Consequences -* It solves the problem by allowing users to include custom data in their schemas. -* Many developers will be familiar with using `x-` for custom data. -* It's a simple way to differentiate SVAs from other keywords. +- It solves the problem by allowing users to include custom data in their + schemas. +- Many developers will be familiar with using `x-` for custom data. +- It's a simple way to differentiate SVAs from other keywords. ### Negative Consequences -* Some people preferred a different prefix as `x-` in some other contexts denotes "experimental" behavior. +- Some people preferred a different prefix as `x-` in some other contexts + denotes "experimental" behavior. ## Pros and Cons of the Options @@ -55,17 +64,22 @@ Specifically, the prefix `x-` has been selected. [Discussion](https://github.com/orgs/json-schema-org/discussions/329#discussioncomment-4988859) -* Good, because it's simple and easy to understand. -* Good, because `x-` specifically is familiar to many developers as an identifying prefix for custom data. -* Good, because it's easily supportable by the meta-schema (i.e. `patternProperties`) -* Bad, because `x-` in some other contexts can denote "experimental" behavior, which is not our meaning. +- Good, because it's simple and easy to understand. +- Good, because `x-` specifically is familiar to many developers as an + identifying prefix for custom data. +- Good, because it's easily supportable by the meta-schema (i.e. + `patternProperties`) +- Bad, because `x-` in some other contexts can denote "experimental" behavior, + which is not our meaning. #### Option 1a - Optionally defined by a new `$sigil` keyword [Discussion](https://github.com/orgs/json-schema-org/discussions/329#discussioncomment-5357549) -* Good, because it can give users flexibility for the prefix that they want to use. -* Bad, because it cannot be supported by the meta-schema without other changes, which may be difficult to define and/or implement. +- Good, because it can give users flexibility for the prefix that they want to + use. +- Bad, because it cannot be supported by the meta-schema without other changes, + which may be difficult to define and/or implement. High level of effort @@ -73,29 +87,35 @@ High level of effort [Discussion](https://github.com/orgs/json-schema-org/discussions/329#discussioncomment-4988882) -* Good, because it defines the SVAs in a vocabulary which means they are regarded as "known." -* Bad, because we don't have any support for inlined vocabularies at the moment and would have to build that. +- Good, because it defines the SVAs in a vocabulary which means they are + regarded as "known." +- Bad, because we don't have any support for inlined vocabularies at the moment + and would have to build that. ### Option 3 - A new core keyword that lists SVAs, e.g. `$ignored` [Discussion](https://github.com/orgs/json-schema-org/discussions/329#discussioncomment-4988904) -* Good, because it provides a way to define SVAs. -* Bad, because it cannot be supported by the meta-schema without other changes, which may be difficult to define and/or implement. +- Good, because it provides a way to define SVAs. +- Bad, because it cannot be supported by the meta-schema without other changes, + which may be difficult to define and/or implement. High level of effort + ### Option 4 - A defined configuration option to allow/forbid unknown keywords [Discussion](https://github.com/orgs/json-schema-org/discussions/329#discussioncomment-4999789) -* Good, because it returns previous functionality (i.e. allowing unknown keywords) to the user. -* Bad, because that previous functionality removes/circumvents stability guarantees. +- Good, because it returns previous functionality (i.e. allowing unknown + keywords) to the user. +- Bad, because that previous functionality removes/circumvents stability + guarantees. ### Option 5 - A new core keyword designed for "extra" data [Discussion](https://github.com/orgs/json-schema-org/discussions/329#discussioncomment-5374873) -* Good, because it provides a place for users to add extra data. -* Bad, because it's an extra depth level that users need to create. -* Bad, because it can only generate a single annotation instead of multiple. +- Good, because it provides a place for users to add extra data. +- Bad, because it's an extra depth level that users need to create. +- Bad, because it can only generate a single annotation instead of multiple. diff --git a/adr/2024-02-object-contains.md b/adr/2024-02-object-contains.md index f7ba55a3..ab6d5e16 100644 --- a/adr/2024-02-object-contains.md +++ b/adr/2024-02-object-contains.md @@ -1,54 +1,68 @@ # `contains` and JSON Objects -* Status: Proposed, accepted, reconsidered, and ultimately reverted. -* Deciders: @gregsdennis, @jdesrosiers, @handrews, @awwright, @karenetheridge, @relequestual (with input from a couple non-core members) -* Date: 2023-11-14 (documented 2024-02-09) +- Status: Proposed, accepted, reconsidered, and ultimately reverted. +- Deciders: @gregsdennis, @jdesrosiers, @handrews, @awwright, @karenetheridge, + @relequestual (with input from a couple non-core members) +- Date: 2023-11-14 (documented 2024-02-09) Technical Story: -- Original proposal [#1077](https://github.com/json-schema-org/json-schema-spec/issues/1077) and [PR](https://github.com/json-schema-org/json-schema-spec/pull/1092) -- Reversion discussion [#1358](https://github.com/json-schema-org/json-schema-spec/issues/1358) and [PR](https://github.com/json-schema-org/json-schema-spec/pull/1452) +- Original proposal + [#1077](https://github.com/json-schema-org/json-schema-spec/issues/1077) and + [PR](https://github.com/json-schema-org/json-schema-spec/pull/1092) +- Reversion discussion + [#1358](https://github.com/json-schema-org/json-schema-spec/issues/1358) and + [PR](https://github.com/json-schema-org/json-schema-spec/pull/1452) ## Context and Problem Statement -[2021-02] -The original proposal was for `contains` to apply to objects as well as arrays since there was no functionality to do so. -The discussion covered the options of modifying `contains` or introducing a new `objectContains` (or similar) keyword set (also needs separate min/max). -The decision was voted on and modifying `contains` won. +\[2021-02] +The original proposal was for `contains` to apply to objects as well as arrays +since there was no functionality to do so. The discussion covered the options of +modifying `contains` or introducing a new `objectContains` (or similar) keyword +set (also needs separate min/max). The decision was voted on and modifying +`contains` won. -[2021-06] +\[2021-06] A change was applied. -[2022-12] -With the team shifting focus to stability between spec releases, the question was raised again with the argument that allowing `contains` to apply to objects is a breaking change. -It was conceded that the better approach would be to retain `contains` only for arrays and introduce a new keyword set to apply to objects. +\[2022-12] +With the team shifting focus to stability between spec releases, the question +was raised again with the argument that allowing `contains` to apply to objects +is a breaking change. It was conceded that the better approach would be to +retain `contains` only for arrays and introduce a new keyword set to apply to +objects. -[2023-11] +\[2023-11] The change was applied (reverted to previous behavior). ## Decision Drivers -* The original decision to allow `contains` to apply to objects was driven by the fact that no such functionality existed. -* The decision to revert was driven by a desire to not break current usages of `contains`. +- The original decision to allow `contains` to apply to objects was driven by + the fact that no such functionality existed. +- The decision to revert was driven by a desire to not break current usages of + `contains`. ## Considered Options -* `contains` could be modified to apply to objects. -* a new keyword set (e.g. `objectContains` along with associated min/max) could be added. +- `contains` could be modified to apply to objects. +- a new keyword set (e.g. `objectContains` along with associated min/max) could + be added. ## Decision Outcome -Ultimately, `contains` will continue to apply to only arrays. -New keywords will need to be introduced to apply to objects. -(Such a proposal has not yet been made.) +Ultimately, `contains` will continue to apply to only arrays. New keywords will +need to be introduced to apply to objects. (Such a proposal has not yet been +made.) ### Positive Consequences -* Schemas which currently use `contains` without a `type: array` specifier will not suddenly start applying to objects also. +- Schemas which currently use `contains` without a `type: array` specifier will + not suddenly start applying to objects also. ### Negative Consequences -* The functionality of `contains` as applied to objects is still unsupported. +- The functionality of `contains` as applied to objects is still unsupported. ## Pros and Cons of the Options @@ -56,7 +70,8 @@ New keywords will need to be introduced to apply to objects. (Example provided recently by a user in [Slack](https://json-schema.slack.com/archives/C5CF75URH/p1707258032879409)) -The requirement is that an object may contain any number of properties, but one and only one of them must contain an object with a `title` property. +The requirement is that an object may contain any number of properties, but one +and only one of them must contain an object with a `title` property. ✔️ valid ```json @@ -82,8 +97,9 @@ The requirement is that an object may contain any number of properties, but one } ``` -Currently, this is impossible since there is no way to conditionally count property values. -However, with `contains` applying to objects, the following is possible: +Currently, this is impossible since there is no way to conditionally count +property values. However, with `contains` applying to objects, the following is +possible: ```json { @@ -97,13 +113,14 @@ However, with `contains` applying to objects, the following is possible: } ``` -* Good, because it provides functionality that previously did not exist -* Bad, because is can potentially break some schemas -* … +- Good, because it provides functionality that previously did not exist +- Bad, because is can potentially break some schemas +- ... ### New keywords -Same examples as [changing `contains`](#change-contains), except we use new keywords instead. +Same examples as [changing `contains`](#change-contains), except we use new +keywords instead. The schema would be something like this instead: @@ -119,7 +136,7 @@ The schema would be something like this instead: } ``` -* Good, because it provides functionality that previously did not exist -* Good, because it doesn't break anyone -* Bad, because we have to introduce three new keywords -* … +- Good, because it provides functionality that previously did not exist +- Good, because it doesn't break anyone +- Bad, because we have to introduce three new keywords +- ... diff --git a/adr/2024-05-08-extract-unstable-keywords.md b/adr/2024-05-08-extract-unstable-keywords.md index 74faf4db..f4bc53bc 100644 --- a/adr/2024-05-08-extract-unstable-keywords.md +++ b/adr/2024-05-08-extract-unstable-keywords.md @@ -1,56 +1,69 @@ # Extract Unstable Features for Initial Release -* Status: accepted -* Deciders: @gregsdennis @jdesrosiers @bhutton -* Date: 2024-05-08 +- Status: accepted +- Deciders: @gregsdennis @jdesrosiers @bhutton +- Date: 2024-05-08 Technical Story: -@gregsdennis [proposed](https://github.com/json-schema-org/json-schema-spec/issues/1443#issuecomment-2099427543) that an ADR be created to document that unstable features be extracted before the stable release. +@gregsdennis [proposed](https://github.com/json-schema-org/json-schema-spec/issues/1443#issuecomment-2099427543) +that an ADR be created to document that unstable features be extracted before +the stable release. -Also the [SDLC proposal](https://github.com/orgs/json-schema-org/discussions/671) which lists features that need to be put into the proposal process. +Also the [SDLC proposal](https://github.com/orgs/json-schema-org/discussions/671) +which lists features that need to be put into the proposal process. ## Context and Problem Statement -In creating a stable spec release, it's important that all included features are well-developed and their behaviors are finalized. As such, the following features will be extracted before the stable release. +In creating a stable spec release, it's important that all included features are +well-developed and their behaviors are finalized. As such, the following +features will be extracted before the stable release. - `$vocabulary` - This feature is still in development. -- Output formats - This feature is being extracted to its own spec anyway. (See [PR](https://github.com/json-schema-org/json-schema-spec/pull/1429) for more info and link to discussion.) -- `propertyDependencies` - This feature is not technically in the spec and should go through the proposal process. +- Output formats - This feature is being extracted to its own spec anyway. (See + [PR](https://github.com/json-schema-org/json-schema-spec/pull/1429) for more + info and link to discussion.) +- `propertyDependencies` - This feature is not technically in the spec and + should go through the proposal process. ## Decision Drivers -We can't publish a stable spec that contains unstable features. Thus we need to remove them. +We can't publish a stable spec that contains unstable features. Thus we need to +remove them. ## Considered Options 1. Extract unfinished features and put them through the proposal process. -2. Complete the features before releasing the spec. +1. Complete the features before releasing the spec. ## Decision Outcome -Chosen option: Extract unfinished features and put them through the proposal process. +Chosen option: Extract unfinished features and put them through the proposal +process. -This allows us to release a stable version of the specification while continuing to develop these features. +This allows us to release a stable version of the specification while continuing +to develop these features. ### Positive Consequences -* We can release a spec earlier that fulfills our users' needs. -* We can continue to develop these features. +- We can release a spec earlier that fulfills our users' needs. +- We can continue to develop these features. ### Negative Consequences -* These feature will be considered experimental until their proposals are accepted. This may be a hindrance to adoption. +- These feature will be considered experimental until their proposals are +accepted. This may be a hindrance to adoption. ## Pros and Cons of the Options + ### Extract unfinished features and put them through the proposal process -* Good, because we can release a spec earlier that fulfills our users' needs. -* Good, because we can continue to develop these features. -* Bad, because these features are experimental now. +- Good, because we can release a spec earlier that fulfills our users' needs. +- Good, because we can continue to develop these features. +- Bad, because these features are experimental now. ### Complete the features before releasing the spec -* Good, because the features will be ready to use when the spec releases. -* Bad, because the spec may not release if we can't finalize the features. +- Good, because the features will be ready to use when the spec releases. +- Bad, because the spec may not release if we can't finalize the features. diff --git a/adr/README.md b/adr/README.md index 331cd6bf..223275a3 100644 --- a/adr/README.md +++ b/adr/README.md @@ -1,15 +1,17 @@ -# Architectural Decision Log - -This log lists the architectural decisions for the JSON Schema specification. - - - -* [ADR-2022-04-08](2022-04-08-cref-for-ambiguity-and-fix-later-gh-spec-issue-1172.md) - Acknowledge ambiguity in additionalProperties behaviour and fix after patch release - - - -You can find the ADR for using ADRs in our [community repo ADR log](https://github.com/json-schema-org/community/tree/HEAD/docs/adr). - -For new ADRs, please use [template.md](template.md) as basis. -More information on MADR is available at . -General information about architectural decision records is available at . +# Architectural Decision Log + +This log lists the architectural decisions for the JSON Schema specification. + + + +- [ADR-2022-04-08](2022-04-08-cref-for-ambiguity-and-fix-later-gh-spec-issue-1172.md) + \- Acknowledge ambiguity in additionalProperties behaviour and fix after patch + release + + + +You can find the ADR for using ADRs in our [community repo ADR log](https://github.com/json-schema-org/community/tree/HEAD/docs/adr). + +For new ADRs, please use [template.md](template.md) as basis. More information +on MADR is available at . General information about +architectural decision records is available at . diff --git a/adr/template.md b/adr/template.md index baf6c9d0..6da4169a 100644 --- a/adr/template.md +++ b/adr/template.md @@ -1,65 +1,70 @@ -# [short title of solved problem and solution] +# \[short title of solved problem and solution] -* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] -* Deciders: [list everyone involved in the decision] -* Date: [YYYY-MM-DD when the decision was last updated] +- Status: \[proposed | rejected | accepted | deprecated | ... | superseded by + \[ADR-0005](0005-example.md)] +- Deciders: \[list everyone involved in the decision] +- Date: \[YYYY-MM-DD when the decision was last updated] -Technical Story: [description | ticket/issue URL] +Technical Story: \[description | ticket/issue URL] ## Context and Problem Statement -[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.] +\[Describe the context and problem statement, e.g., in free form using two to +three sentences. You may want to articulate the problem in form of a question.] ## Decision Drivers -* [driver 1, e.g., a force, facing concern, …] -* [driver 2, e.g., a force, facing concern, …] -* … +- \[driver 1, e.g., a force, facing concern, ...] +- \[driver 2, e.g., a force, facing concern, ...] +- … ## Considered Options -### [option 1] +### \[option 1] -[example | description | pointer to more information | …] +\[example | description | pointer to more information | ...] -* Good, because [argument a] -* Good, because [argument b] -* Bad, because [argument c] -* … +- Good, because \[argument a] +- Good, because \[argument b] +- Bad, because \[argument c] +- … -### [option 2] +### \[option 2] -[example | description | pointer to more information | …] +\[example | description | pointer to more information | ...] -* Good, because [argument a] -* Good, because [argument b] -* Bad, because [argument c] -* … +- Good, because \[argument a] +- Good, because \[argument b] +- Bad, because \[argument c] +- … -### [option 3] +### \[option 3] -[example | description | pointer to more information | …] +\[example | description | pointer to more information | ...] -* Good, because [argument a] -* Good, because [argument b] -* Bad, because [argument c] -* … +- Good, because \[argument a] +- Good, because \[argument b] +- Bad, because \[argument c] +- … ## Decision Outcome -"[option 1]" was chosen because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)]. +"\[option 1]" was chosen because \[justification. e.g., only option, which meets +k.o. criterion decision driver | which resolves force force | ... | comes out +best (see below)]. ### Positive Consequences -* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …] -* … +- \[e.g., improvement of quality attribute satisfaction, follow-up decisions + required, ...] +- ... ### Negative Consequences -* [e.g., compromising quality attribute, follow-up decisions required, …] -* … +- \[e.g., compromising quality attribute, follow-up decisions required, ...] +- ... ## Links -* [Link type] [Link to ADR] -* … +- \[Link type] \[Link to ADR] +- ... diff --git a/package.json b/package.json index 59d407d3..34b5f129 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "type": "module", "main": "index.js", "scripts": { - "lint": "eslint . ; remark --no-stdout --frail specs/", + "lint": "eslint . ; remark --no-stdout --frail .", "build": "remark --rc-path specs/.remarkrc-build.js --output web/" }, "license": "MIT",