search

OAI / Arazzo-Specification

The Arazzo Specification - A Tapestry for Deterministic API Workflows
https://spec.openapis.org/arazzo/latest.html
Apache License 2.0
224 stars 44 forks source link

Schema dialects undefined in Arazzo #223

Open jeremyfiel opened 3 months ago

jeremyfiel commented 3 months ago

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.

frankkilcommins commented 3 months ago

Being honest, this was somewhat parked prior to 1.0.0 delivery. @handrews can you remember anything else from our conversations on it and if defining an explicit dialect for Arazzo is beneficial?

There are indeed many cases where an Arazzo document can describe workflows over APIs described by various versions of OAS. Instructions for tooling on how to parse/validate OAD's is driven by the OAD and the version of OAS therein, rather than Arazzo having an opinion on that.