vocabulary enhancements #2803
vocabulary enhancements #2803
Conversation
this improves readability, and makes it possible to add dependencies between keywords
…te keywords oneOf, anyOf, allOf." https://spec.openapis.org/oas/v3.1.0#fixed-fields-20
karenetheridge
force-pushed
the
ether/vocabulary-enhancements
branch
from
2172dcb to
b1770ad
Compare
| discriminator: | ||
| $ref: '#/$defs/extensible' | ||
| properties: | ||
| mapping: | ||
| additionalProperties: | ||
| type: string | ||
| format: uri-reference |
There was a problem hiding this comment.
This is not correct. These values can be either a uri-reference or a Schema Name.
An object to hold mappings between payload values and schema names or references.
Unfortunately, the concept of a "schema name" is not actually defined. See #2618 for a patch proposal that defines the concept the way I believe existing tooling interprets it.
There was a problem hiding this comment.
I see. It would be good to clarify that wording, then (and perhaps take out the bits that don't add much value).
| dependentSchemas: | ||
| discriminator: | ||
| anyOf: | ||
| - required: [ oneOf ] | ||
| - required: [ anyOf ] | ||
| - required: [ allOf ] |
There was a problem hiding this comment.
The spec technically says not having oneOf/anyOf/allOf with a discriminator is a failure, but there is no good reason to fail in this case. It should be a linter warning, not a schema failure. Personally, I'd rather leave this out, but I'm ok with it since it is technically what the spec says. I propose changing this in #2621
There was a problem hiding this comment.
it is indeed a very strange keyword, and doesn't really fit with the simplicity that most other keywords have.
I'll put this PR into draft mode while the other issue is being discussed.
| properties: | ||
| discriminator: | ||
| $ref: '#/$defs/discriminator' | ||
| example: true | ||
| externalDocs: | ||
| $ref: '#/$defs/external-docs' | ||
| xml: | ||
| $ref: '#/$defs/xml' |
There was a problem hiding this comment.
I see you've inlined the referenced schemas. The style I prefer is that any objects (excluding objects used like maps) are generally pulled out into definitions. It allows the reader to see what the whole schema does in the first few lines. Especially when inlining multiple large object schemas, it can we hard to determine the top level properties of an object. This way the reader can see the top level structure more easily and then dig down into the definitions to learn more about the specific properties they are interested in.
There was a problem hiding this comment.
I inlined them here because they aren't referenced from anywhere else, and to mirror the style we use for the standard json-schema-spec schema files. This file is more like those schemas, rather than the main openapi schema (where splitting out into definitions, even if something is only referenced once, is helpful because the document is so nested). Vocabularies aren't like that -- there's just one level: the keywords themselves.
There was a problem hiding this comment.
There is no precedent for compound keywords like these in the JSON Schema meta-schemas because there are no such keywords in JSON Schema. The only time we use objects is for map-like structures such as properties mapping a property name to a schema. If there were something similar in JSON Schema, I'd like to think we would use a definition for that as well.
| anyOf: | ||
| - required: [ oneOf ] | ||
| - required: [ anyOf ] | ||
| - required: [ allOf ] | ||
| $dynamicAnchor: meta | ||
| $id: https://spec.openapis.org/oas/3.1/meta/base |
There was a problem hiding this comment.
I noticed that this schema's keywords are all mixed up. I know that wasn't introduced in this schema, but it would be nice to fix that while we're making changes anyway.
There was a problem hiding this comment.
I'm not sure what you mean here.
There was a problem hiding this comment.
I mean the ordering is not the same as the JSON version. Things that are best practice to put at the top of the document ($id, $schema, $vocabularies) are at the bottom of the document. Unorganized schemas are harder to read.
small improvements for the discriminator keyword, from the spec