Skip to content
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.

Sign up for GitHub

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

$schema Guidance #2266

Merged
merged 5 commits into from
Jul 23, 2020
Merged

$schema Guidance #2266

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
01098c6
chore: explain how $schema might work
Jun 15, 2020
3d2144b
reordered and made it specifically only schema resources
Jul 2, 2020
7e2e35f
Update versions/3.1.0.md
philsturgeon Jul 6, 2020
ae38cfb
Update versions/3.1.0.md
philsturgeon Jul 6, 2020
6e71af6
new approach
Jul 22, 2020
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
14 changes: 14 additions & 0 deletions versions/3.1.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2336,6 +2336,20 @@ As such, inline schema definitions, which do not have a given id, *cannot* be us
The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML.
The [XML Object](#xmlObject) contains additional information about the available options.

###### Picking Schema Vocabularies

OpenAPI documents are made up of multiple resources, sometimes resources are all in the same root OpenAPI document (inline resources), or resources are contain their own documents with `$ref` (separate resources). A schema object could exist as an inline resource, or a separate resource.
philsturgeon marked this conversation as resolved.
Show resolved Hide resolved

It is important for tooling to be able to detect what meta-schema any given resource wishes to be processed with: JSON Schema Core, JSON Schema Validation, OpenAPI Schema Object, or some custom meta schema.
MikeRalphson marked this conversation as resolved.
Show resolved Hide resolved

The `$schema` keyword can be used to define which meta-schema should be used when interacting with any schema resource.
philsturgeon marked this conversation as resolved.
Show resolved Hide resolved

Inline schema resources will default to using `$schema: "https://spec.openapis.org/oas/3.1/schema-object"`.
philsturgeon marked this conversation as resolved.
Show resolved Hide resolved

Separate schema resources will default to using `$schema: "https://json-schema.org/draft/2019-09/schema"`.
philsturgeon marked this conversation as resolved.
Show resolved Hide resolved

Any schema resource can override this default by setting the `$schema` property to something else.
philsturgeon marked this conversation as resolved.
Show resolved Hide resolved

##### Schema Object Examples

###### Primitive Sample
Expand Down