OAI / OAI/Arazzo-Specification

Schema dialects undefined in Arazzo

Open
#223 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
471
Forks
69
Avg merge
17h 58m
Merged PRs (30d)
19

Description

Do schema dialects need some mention in the Arazzo specification?

taken from OAS, I believe this should also apply to Arazzo.

4.8.24.2.3 Specifying Schema Dialects
It is important for tooling to be able to determine which dialect or meta-schema any given resource wishes to be processed with: JSON Schema Core, JSON Schema Validation, OpenAPI Schema dialect, or some custom meta-schema.

The $schema keyword MAY be present in any root Schema Object, and if present MUST be used to determine which dialect should be used when processing the schema. This allows use of Schema Objects which comply with other drafts of JSON Schema than the default Draft 2020-12 support. Tooling MUST support the OAS dialect schema id, and MAY support additional values of $schema.

To allow use of a different default $schema value for all Schema Objects contained within an OAS document, a jsonSchemaDialect value may be set within the OpenAPI Object. If this default is not set, then the OAS dialect schema id MUST be used for these Schema Objects. The value of $schema within a Schema Object always overrides any default.

When a Schema Object is referenced from an external resource which is not an OAS document (e.g. a bare JSON Schema resource), then the value of the $schema keyword for schemas within that resource MUST follow JSON Schema rules.


This is important for the inputs keyword where a JSON Schema 2020-12 schema object is accepted as a valid input. I believe there to be many cases where an Arazzo description may reference an OAS 3.0.x description which uses a superset/subset of JSON Schema draft-05 and there may be additional cases referencing an OAS 3.1.x description which may use other JSON Schema drafts, embedded or referenced.

It may be important to have a better explanation of the expected behavior for this section. It may also refer to JSON Schema 2020-12 bundling rules which covers it pretty well.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Arazzo specification's inputs keyword and compare its JSON Schema 2020-12 wording with the cited OpenAPI section on specifying schema dialects. Review the referenced JSON Schema bundling rules and determine the expected behavior for embedded and external schemas; done means the specification clearly documents dialect selection and references.

Written by the indexing model from the issue text.

Assessment

Tech stack
json, openapi
Domain
api, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.