Proposal: x-oas-draft-alternativeSchemas

A long standing request has been to add support for alternate schemas. See #764 #1443

There are many concerns about the effect this will have on the tooling ecosystem, however, there is also a strong desire from the community to support both more recent versions of JSON Schema and other formats such as XSD Schema, Protobuf Schema.

Instead of simply adding this feature to the specification and hoping that tooling vendors will implement it. I propose we use the draft feature (PR #1531 ) process to validate the value and feasibility of this feature.

openapi: 3.0.2
info:
  title: A sample using real JSON Schema and xsd
  version: 1.0.0
paths:
  /:
    get:
      responses:
        '200':
          description: Ok
          content:
            application/json:
              x-oas-draft-alternate-schema:
                type: json-schema
                externalValue: ./rootschema.json
            application/xml:
              x-oas-draft-alternate-schema:
                type: xml-schema
                externalValue: ./rootschema.xsd

• The property is called alternate-schema because it can be used in instead of, or in addition to the OAS Schema object. If both are present then both schemas must be respected.
• The type field is required and must match one of the values identified in an alternate schema registry which will be created as part of this proposal. The alternate schema registry will provide a link to a specification for the schema file.
• It is recommended that tools provide users with warnings when they encounter an alternate schema type that they do not support. Tools should not fail to process a description, unless the schema is essential to the operation. Ideally they should continue as if the alternate-schema is not present in a form of graceful degradation.
• The externalValue property is required and must be a relative or absolute URL.
• The alternate-schema property can be used anywhere the schema property can be used.

[handrews]

@tedepstein I think I’ll also wait on others before going further into the substance of this issue.

Regarding the process, I am sympathetic to your frustration. Part of my suggestion for splitting this out into a separate topic is that, having dealt with more than a few thread of this nature in the JSON Schema project, splitting has been one of the most effective ways to de-escalate arguments and make progress where we were able to do so.

In this particular case, I am very concerned that alternativeSchema will miss the 3.1 release because of a late-added feature request that is not at all essential to alternativeSchema’s usefulness. It may be essential for your tooling, but there are many people who are waiting on this feature who do not need inline schemas.

If alternativeSchema gets punted out of 3.1 over the question of inline schemas, I’m going to be more than a little upset over that 😢

So I don’t really want to get into the merits. I want to ensure that the core of the proposal moves forward, because it’s extremely important to me that alternativeSchema be in 3.1. Obviously as someone driving the JSON Schema project, the single most important thing for me in OpenAPI is to be able to use actual JSON Schemas.

[tedepstein]

@philsturgeon, we have customers who want this for JSON Schema, possibly other languages. I also have plans to support an alternative schema language. In both cases, we need inline/embedded alternative schemas in order to provide a reasonably good UX for editing.

It sounds like @fmvilas and @adjenks are both saying they would want and expect this.

The error messages in your screenshots would be addressed by using literal multi-line strings, i.e. adding a pipe character after the schema: key, and putting the schema content on separate lines, indented:

    x-oas-draft-alternate-schema:
      type: xml-schema
      schema: |
        <hello-world some-attr="Hi" />
        <hello-world some-attr="isn't this great" />

Folded strings (> instead of |) work for this purpose too, and most OpenAPI specs that have substantial markdown documentation are already using folded or literal multi-line strings for description properties. So it’s not like we’d be requiring users to do something exotic.