Skip to content

extract propertyDependencies #1450

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 9 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ jsonschema-*.txt
relative-json-pointer.html
relative-json-pointer.pdf
relative-json-pointer.txt
extensions/*.html

# For the Python enviornment
.venv
Expand Down
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,11 @@ Labels are assigned based on [Sensible Github Labels](https://github.com/Releque
## Authoring and Building

### Specification
To build the spec files to HTML from the Markdown sources, run `npm run build`.
You can also build each individually with `npm run build-core` and `npm run
build-validation`.
To build the spec files to HTML from the Markdown sources, run `npm run
build-all`.
You can also build each individually with `npm run build -- filename.md`
(Example: `npm run build -- jsonschema-core.md`). You can also use wildcards to
build multiple specs at the same time: `npm run build -- jsonschema-*.md`.

The spec is built using [Remark](https://remark.js.org/), a markdown engine with
good support for plugins and lots of existing plugins we can use.
Expand Down
37 changes: 32 additions & 5 deletions build/build.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

67 changes: 67 additions & 0 deletions extensions/propertyDependencies.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# JSON Schema Extension: The `propertyDependencies` Keyword

## Abstract

The `propertyDependencies` keyword is a more friendly way to select between two
or more schemas to validate an instance against than is currently supported by
JSON Schema.

## Status

**Current Status**: EXPERIMENTAL

This extension is in the early stages of development. Changes, including
breaking changes, are possible. At this stage, it's recommended that
implementations disable this keyword by default.
Comment on lines +13 to +15
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I expect at some point we'd move this to some sort of "statuses" document (or section in a larger process document). I don't think a definition of what the "EXPERIMENTAL" status generally needs to be included for these.

As we don't yet have such a document, I think having this is fine.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I forgot to explain what I was thinking here. I'm not sure it makes sense. I was just trying it out.

I expect that the concept of a proposal being a proposal to adopt an extension wouldn't be limited to our extensions. Some third-party may define an extension spec in whatever form they choose with their own ideas about the status of the document. So, the extension spec's status is a different concept than the proposal process status. I thought, "what would I put here if this was just a standalone third-party spec and the proposal process wasn't involved?"

While I might use a status like "EXPERIMENTAL" while the spec is third-party, I'd probably switch to something like "Proposed Standard" when it enters the proposal process. So, what I did doesn't quite makes sense. It's kind of half way in two places.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All that is whatever. It needs to be defined, and I'm just saying a document like this only needs to point to wherever that ends up being defined. It doesn't need to copy any text. It should just say, "This is my status. For more info about statuses, click here."


This extension has been
[proposed](https://github.com/json-schema-org/json-schema-spec/blob/main/proposals/propertyDependencies.md)
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here you're linking to the file in GH...

for inclusion as a standard keyword in the JSON Schema specification.

## Note to Readers

The issues list for this extension can be found at
<https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aissue+propertydependencies>.

For additional information, see <https://json-schema.org/>.

To provide feedback, use this issue tracker or any of the communication methods
listed on the homepage.

## Table of Contents

## Conventions and Terminology

All conventions and terms used and defined by the [JSON Schema Core
specification](../jsonschema-core.html) also apply to this document.

## Extension

This document adds the `propertyDependencies` keyword to the
`https://json-schema.org/vocab/applicator` [applicator
vocabulary](../jsonschema-core.html#applicatorvocab).

### `propertyDependencies`

This keyword specifies subschemas that are evaluated if the instance is an
object and contains a certain property with a certain string value.

This keyword's value MUST be an object. Each value in the object MUST be an
object whose values MUST be valid JSON Schemas.

If the outer object key is a property in the instance and the inner object key
is equal to the value of that property, the entire instance must validate
against the schema. Its use is dependent on the presence and value of the
property.

Omitting this keyword has the same behavior as an empty object.

## [Appendix] Change Log

* [October 2023] Created

## Champions

| Champion | Company | Email | URI |
|----------------------------|---------|----------------------|----------------------------------|
| Jason Desrosiers | Postman | <[email protected]> | <https://github.com/jdesrosiers> |
19 changes: 2 additions & 17 deletions jsonschema-core.md
Original file line number Diff line number Diff line change
Expand Up @@ -1655,7 +1655,7 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
Clients SHOULD be able to make requests with a "From" header so that server
operators can contact the owner of a potentially misbehaving script.

## A Vocabulary for Applying Subschemas
## A Vocabulary for Applying Subschemas {#applicatorvocab}

This section defines a vocabulary of applicator keywords that are RECOMMENDED
for use as the basis of other vocabularies.
Expand Down Expand Up @@ -1793,7 +1793,7 @@ successfully validates against its subschema. Implementations MUST NOT evaluate
the instance against this keyword, for either validation or annotation
collection purposes, in such cases.

##### `dependentSchemas`
##### `dependentSchemas` {#dependent-schemas}

This keyword specifies subschemas that are evaluated if the instance is an
object and contains a certain property.
Expand All @@ -1807,21 +1807,6 @@ property.

Omitting this keyword has the same behavior as an empty object.

##### `propertyDependencies`

This keyword specifies subschemas that are evaluated if the instance is an
object and contains a certain property with a certain string value.

This keyword's value MUST be an object. Each value in the object MUST be an
object whose values MUST be valid JSON Schemas.

If the outer object key is a property in the instance and the inner object key
is equal to the value of that property, the entire instance must validate
against the schema. Its use is dependent on the presence and value of the
property.

Omitting this keyword has the same behavior as an empty object.

### Keywords for Applying Subschemas to Child Instances

Each of these keywords defines a rule for applying its subschema(s) to child
Expand Down
Loading