feat(typings): update OpenAPI 3.0 and 3.1 typing declarations

[jeremyfiel]

fixes #1547

What/Why/How?

The typings for OAS 3 and OAS 3_1 schemas were incorrectly defined per the OpenAPI Specification.

OAS 3.0 has a specific requirement which defines an OpenAPI Schema rather than a JSON Schema schema. There are subtleties to the OpenAPI 3.0 Schema.

OpenAPI 3.1 Schemas are equivalent to a JSON Schema 2020-12 schema.

Reference

Per the OpenAPI 3.0 Specification

4.7.24.1 JSON Schema Keywords
The following keywords are taken directly from the JSON Schema definition and follow the same specifications:

• title
• multipleOf
• maximum
• exclusiveMaximum
• minimum
• exclusiveMinimum
• maxLength
• minLength
• pattern (This string SHOULD be a valid regular expression, according to the Ecma-262 Edition 5.1 regular expression dialect)
• maxItems
• minItems
• uniqueItems
• maxProperties
• minProperties
• required
• enum

The following keywords are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification.

• type - Value MUST be a string. Multiple types via an array are not supported.
• allOf - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
• oneOf - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
• anyOf - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
• not - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
• items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if type is "array".
• properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
• additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. Consistent with JSON Schema, additionalProperties defaults to true.
• description - [CommonMark] syntax MAY be used for rich text representation.
• format - See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
• default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is "string", then default can be "foo" but cannot be 1.

Alternatively, any time a Schema Object can be used, a Reference Object can be used in its place. This allows referencing definitions instead of defining them inline.

Additional keywords defined by the JSON Schema specification that are not mentioned here are strictly unsupported.

Other than the JSON Schema subset fields, the following fields MAY be used for further schema documentation:

4.7.24.2 Fixed Fields

Field Name	Type	Description
nullable	boolean	This keyword only takes effect if type is explicitly defined within the same Schema Object. A true value indicates that both null values and values of the type specified by type are allowed. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of null as a value. A false value leaves the specified or default type unmodified. The default value is false.
discriminator	Discriminator Object	Adds support for polymorphism. The discriminator is used to determine which of a set of schemas a payload is expected to satisfy. See Composition and Inheritance for more details.
readOnly	boolean	Relevant only for Schema Object properties definitions. Declares the property as “read only”. This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as readOnly being true and is in the required list, the required will take effect on the response only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.
writeOnly	boolean	Relevant only for Schema Object properties definitions. Declares the property as “write only”. Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as writeOnly being true and is in the required list, the required will take effect on the request only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.
xml	XML Object	This MAY be used only on property schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property.
externalDocs	External Documentation Object	Additional external documentation for this schema.
example	Any	A free-form field to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
deprecated	boolean	Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is false.

---

Per the OpenAPI 3.1 Specification

4.8.24 Schema Object
The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is a superset of the JSON Schema Specification Draft 2020-12. The empty schema (which allows any instance to validate) MAY be represented by the boolean value true and a schema which allows no instance to validate MAY be represented by the boolean value false.

For more information about the keywords, see JSON Schema Core and JSON Schema Validation.

Unless stated otherwise, the keyword definitions follow those of JSON Schema and do not add any additional semantics; this includes keywords such as $schema, $id, $ref, and $dynamicRef being URIs rather than URLs. Where JSON Schema indicates that behavior is defined by the application (e.g. for annotations), OAS also defers the definition of semantics to the application consuming the OpenAPI document.

Testing

Screenshots (optional)

Check yourself

• Code changed? - Tested with redoc/reference-docs/workflows (internal)
• All new/updated code is covered with tests
• New package installed? - Tested in different environments (browser/node)

Security

• Security impact of change has been considered
• Code follows company security practices and guidelines

[changeset-bot]

🦋 Changeset detected

Latest commit: 498f6b7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@redocly/openapi-core	Patch
@redocly/cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jeremyfiel]

ok, i think i'm done with this. missed a few keywords for Oas3_1 schemas.

ready for review. thanks

[tatomyr]

I prefer using the generic interface because it's less likely for the common properties to diverge. Not sure which approach would be cleaner though. Why did you decide to change the approach?

[jeremyfiel]

the keywords which utilized the generic interface were moved into the Oas3Schema and Oas3_1Schema. So it was unused.

[tatomyr]

Yes, but what was the reason for moving the keywords from Oas3XSchemaBase? Was there an issue with leaving them as they were?

[jeremyfiel]

Yes, they have different behavior between 30 asd 31. So the extension of Oas3XSchemaBase was incorrect and the keywords should be assigned to each version

[tatomyr]

Ok. I'll test that once I have time. Thank you for contributing!

[jeremyfiel]

I added a few extra JSON Schema 2020-12 keywords that were missed