Proposal: x-oas-draft-alternativeSchemas

[darrelmiller]

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.

[philsturgeon]

Where did we land on alternate schemas various versions? Saying "json-schema" here might be fine, as JSON Schema files contain "$schema": "http://json-schema.org/draft-XX/schema#", and Protobuf has syntax = "proto3";, but other formats might not?

It would be up to tool vendors to sniff out the right version, which might cause trouble.

Adding the version in the file does add a lot more work for everyone. When users upgrade their JSON Schema files, they would have to update all the OpenAPI references too, which doesn't sound ideal. Tool vendors would also need to update their registries of "supported alternate schemas" just to support a newer JSON Schema draft, which the underlying tools might already support just fine.

I'm conflicted. Probably leave them out and assume that formats declare their versions?

[handrews]

Please, please, PLEASE do not make people specify the JSON Schema draft version. Right now that's fairly straightforward, but as we move towards full vocabulary support including all of the things that will facilitate code generation, this will become far too complex. The whole point is to allow schema authors and vendors more flexibility in using and detecting support for vocabularies. Please don't duplicate the entire effort inside of OpenAPI.

[darrelmiller]

@philsturgeon Can we identify existing schema languages that are not clearly self-description as to version? I'm going to guess all the XML ones will use a namespace. JCR doesn't seem to have any way to version stuff, but then it is still draft.

Personally I'm a fan of formats that identify their own version. There is something icky about relying on external metadata. So, I wouldn't be opposed to just not offering a way to specify a version.

[philsturgeon]

I am no longer conflicted. 👍🏼

[handrews]

@darrelmiller do people ask about JCR in OpenAPI? It's on draft-09 but still lists only one complete implementation. No need for a big tangent here, just curious as to whether it comes up a lot or is just the first JSON-related example you thought of :-)

[darrelmiller]

@handrews It's the only other schema language in JSON that I know of. And no, nobody has ever asked for support.

[MikeRalphson]

There is also schematype for Yaml which has come up before as a possible alternate schema-description language, though I'm not sure about requests for support.

[handrews]

the only other schema language in JSON

Technically "for JSON", as its syntax is not JSON, merely "JSON-like", possessing the conciseness and utility that has made JSON popular. (oh wait, I'm being pedantic again, oops...)

[MikeRalphson]

As the guidance for the json schema $schema keyword is

The "$schema" keyword SHOULD be used in a root schema. It MUST NOT appear in subschemas.

I don't think we need any additional recommendation that people declare their json schema version. Presumably the $schema keyword is 'in scope' / visible the same way $refs outside the fragment being $ref'd by the OpenAPI document are resolvable.

Unless the fragment being $ref'd from the OpenAPI document counts as a "root schema"?

[handrews]

@MikeRalphson "root schema" is the root of a "schema document" which is a whole resource. If you are referencing a fragment other than "#" then you're referencing a subschema.

Certain concepts, most notably $schema and base URI, work based on the schema document scope, not how you got to a schema object.

[handrews]

I think with the vocabulary stuff in draft-08 we'll be clarifying the schema document / file-scope stuff a lot, including how $schema and the closely related proposed $vocabulary work.

[MikeRalphson]

Thanks @handrews

[darrelmiller]

UPDATED Proposal based on feedback from TSC meeting of April 16th.

This proposal is to enable to use of schemas other than the native OAS Schema object for describing request and response payloads and complex parameter/header structures.

openapi: 3.0.2
info:
  title: A sample using real JSON Schema and xsd
  version: 1.0.0
paths:
  /cat:
    get:
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
              x-oas-draft-alternateSchemas:
                - type: json-schema
                  externalValue: ./cat-schema-draft-08.json
                - type: json-schema
                  externalValue: ./cat-schema-draft-05.json
                - type: json-content-rules
                  externalValue: ./cat-JCRschema.json
            application/xml:
              x-oas-draft-alternateSchemas:
                - type: xml-schema
                  externalValue: ./cat-schema.xsd
                - type: relax-ng
                  externalValue: ./cat-schema.ng
                - type: schematron
                  externalValue: ./cat-schema.st

• The property is called alternate-schemas because they can be used in instead of, or in addition to the OAS Schema object. If both OAS Schema and alternate schemas are present then both the OAS schema and one of the alternate schemas SHOULD be respected.
• The alternate-schemas property is a list of schemas. They SHOULD be processed in the order included in the list. Tooling is expected to walk the list until it finds an alternate schema that it knows how to process. Multiple alternate-schemas are supported to enable a single specification be used to drive tools with different schema support capababilities.
• 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 possible for the same schema type to appear multiple times in the list of supported schemas. This is to provide support for different versions of the same schema type.
• It is recommended that tools provide users with warnings when they are unable to find an alternate schema that they 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.
• The use of an array of alternate schemas provides the ability for x- extensions to be included in the alternate schema information.

[cmheazel]

In this example shouldn't the externalValue property reference the schema for the returned content? For example, if I want to return GeoJSON (an IETF standard) then the externalValue could resolve to https://github.com/fge/sample-json-schemas/blob/master/geojson/geojson.json. The client would then validate the returned content against the GeoJSON schema.

[darrelmiller]

@cmheazel Yes you are correct. I see how my example file names are confusing. I'll fix that.

[cmheazel]

@darrelmiller here are some candidates (in addition to GeoJSON)

Geography Markup Language (GML) - MIME type application/gml+xml
Version 3.2.1 = http://schemas.opengis.net/gml/3.2.1/gml.xsd
Version 3.1.1 = http://schemas.opengis.net/gml/3.1.1/base/gml.xsd
Version 3.0.0 = http://schemas.opengis.net/gml/3.0.0/base/gml.xsd

And an in-development JSON encoding of the GML data model:
http://example.com/GML-SF0-JSON.json

[cmheazel]

Another question - XML validation can be a two step process; XML schema validation followed by XML content validation (Schematron). Would it be legal to have two externalValue properties? Validation would be the AND of the two.

[cmheazel]

I have some folks who want to use this feature in a RESTful Web Services standard. When can we lock this feature down and establish a timeline for adoption?

[darrelmiller]

This a proposal to add a new field called alternativeSchemas to the Media Type Object. We are considering the possibility of also allowing it to be added to the Parameter Object for simple parameter definitions. However, we will wait for implementer feedback on that issue.

Media Type Object

Fixed Fields

Field Name	Type	Description
alternativeSchemas	[alternative Schema Object]	List of alternative schemas. These schemas can be used in addition to, or as an alternative to any existing schema property. If both OAS Schema and alternative schemas are present then both the OAS schema and one of the alternative schemas SHOULD be respected. Alternative schemas MUST be processed in order. It is sufficient for tooling to process just the first alternative schema they are capable of processing in order to consider the content as valid. If tooling cannot process any alternative schemas, then they MAY issue a warning, but MUST not report the OpenAPI description as invalid.

Alternative Schema Object

This object makes it possible to reference an external file that contains a schema that does not follow the OAS specification.

Fixed Fields

Field Name	Type	Description
type	string	REQUIRED. The value MUST match one of the values identified in the alternative Schema Registry name of the tag.
externalValue	url	REQUIRED. This is a absolute or relative reference to an external file containing a schema of a known type.

This object MAY be extended with Specification Extensions.

Alternative Schema Registry

The Alternative Schema Registry is located at https://spec.openapis.org/registries/alternative-schema. Inital contents of the registry include:

Name	Link	Description
jsonSchema
xmlSchema

[aowss]

Thanks for coming back to me. I am very aware of anyOf in JSON Schema. 1) My concern was the addition of schema-like keywords in a property that is supposed to just import / include schemas. I feel that we are mixing concerns by adding this ability in this property. It’s probably the job of the imported schema to do that. => IMHO this property should only be used to include an external schema. Nothing more, nothing less 2) The concept of anyOf is very JSON Schema-specific. What does it mean to do that when the schemas are not JSON Schema ? 3) Did anyone express the need to include different schemas that are using the different schema languages ? => I am afraid that, as is the case with inlining non-JSON schemas in this property, we are trying to solve something bigger than the initial ask, i.e. include an external schema. In this specific case, I am not even sure that there is a real use case for that ( I might be wrong about this ). In conclusion, I think that we should focus this feature on the ability to include an external schema and deal with other asks as separate features. The inclusion of external schemas is a priority for a lot of people. A lot of us want their schema system to be separate from their API description. This allows us to use the latest version of JSON Schema for example even though OpenAPI supports a different version. Thanks again for coming back to me on this, Aowss

…

On Apr 3, 2019, at 12:32 PM, Henry Andrews ***@***.***> wrote: @aowss <https://github.com/aowss> I can perhaps address some of your syntax concerns: This seems to complicate the syntax with the introduction of schema constructs, e.g. anyOf, within the schema element. This assumes that these schema languages can be combined using these constructs. This might seem true at first glance but I am not sure it is as obvious as it seems, e.g. the use of default in these different languages. The semantics of JSON Schema's anyOf (and many other keywords) have been clarified in recent drafts. The keyword takes an array of subschemas, evaluates them according to their own rules, and logically ORs the validation results. In the context of JSON Schema proper, the subschemas are expected to also be JSON Schemas, but really the evaluation model lets them be opaque. So the way anyOf is being used here is entirely consistent with JSON Schema. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1532 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AGAZHpESBKXTyeBTojFPvu4MkuByE0BQks5vdNeAgaJpZM4TL4FX>.

[cmheazel]

@aowss I work with systems that return XML. The response undergoes syntax validation through an XML Schema document and valid value validation through a set of Schematron rules. Due to the complexity of Schematron, these rules are packaged in multiple Schematron files. So the answer to question #3 is yes.

[Relequestual]

Is this resolved by #1270 ?

[MikeRalphson]

@Relequestual no, #1270 was for a schema instance for partially validating OAS 3.0.x documents. This issue concerns the tentative process (using x-oas-draft- extensions so it would not have to wait for OAS 3.1 for implementations) of support for non-OAS 3.0 schema languages in requests and responses.

[Relequestual]

Ach, sorry. I should learn to read properly!

[BlueCoder77]

I'm confused as to why this was not implemented. I really need the ability to reference an XML Schema as the schema for my request and response. Nothing fancy, just an external reference to a single XML Schema document.

Can we please get this implemented? Pretty please?

[philsturgeon]

@BlueCoder77 sorry. It's not really a matter of how nice you ask, it's that the proposal in its current shape was no good (#1943). We mostly decided that 3.1 wasn't the right time for alternative schemas, and maybe v4.0 would be instead. 3.1 is getting proper JSON Schema support (#1977), which is what the majority of folks are doing¡ with OpenAPI anyhow.

XML Schema support is important, but it's enough hard work trying to get this smaller thing done. 😅

Maybe you could check out OAI/sig-moonwalk#121 and help get the feedback implemented? Might be doable for 3.2 with a bit of effort. Who knows.

[BlueCoder77]

@philsturgeon - Thanks for the help.

[darrelmiller]

@BlueCoder77 @philsturgeon

Allow me to add a slightly different perspective on this story. Phil isn't wrong, he just has a perspective :-)

The Alternative Schema proposal is in a state that we considered incorporating into the specification. However, when doing a "pilot" proposal we require multiple actual implementations of the feature before we incorporate into the specification. This is a validation process to ensure we don't add big features to the spec that are problematic for tooling.

Phil and the Stoplight crew attempted to implement the current proposal (Yay!) and had a bunch of feedback that they felt the approach was over-complicated and suggested ways it could be simplified. This is how the process is supposed to work.

In theory, multiple other implementers could come along and implement the proposal as is and say THIS IS AWESOME, SHIP IT. And in theory we could allow that feedback to overrule the Stoplight opinion. Unlikely, but theoretically possible.

There wasn't really a decision to say 3.1 is not the right time for alternative schema. We are in a place now, were we either need to re-work the proposal to make Phil et al. happy, or wait for feedback from other implementers who have actually tried to implement it. We missed the 3.1 shipping window for this proposal.

I don't think we need to wait until 4.0 for this. We do need more participation from people who actually build tooling.

[BlueCoder77]

@darrelmiller - Okay, so what do y'all consider an implementer? I really need this feature available for an OpenAPI I am writing for a client. Can I implement this and give me feedback?

[darrelmiller]

@BlueCoder77 An "implementer" is not someone who is creating OpenAPI descriptions. An "implementer" is someone who is writing tools to process an OpenAPI description. Processing could be for validation, editing, client code generation, mock servers, testing, or documentation generation.

If you are writing tools for your client to process OpenAPI descriptions that have included alternative schemas then your feedback would be most appreciated.

[BlueCoder77]

@darrelmiller - Okay, I understand. No, I am not an implementer. Are y'all aware of any current editor implementers that support importing an XML schema to a component model?

[philsturgeon]

I am not.

[matjung]

Regarding alternative schemas.
I was looking for a way to model CSV within OpenAPI and did not find out how to do it yet.
Is it possible to make references to another organizations schemata/specifications?
My thinking is to use DFDL (https://github.com/DFDLSchemas/CSV)
With DFDL one can use XML as model for CSV.
Or is there already an Open API method available for handling CSV in the response.

[Fak3]

I would also love to see a way to link openapi schema with a csvw or frictionless data csv schemas

[dret]

can somebody please summarize where this proposal stands in terms of OpenAPI 3.1? https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#schemaObject looks as if JSON schema is still hard-coded into OpenAPI? specifically, i am looking for a way how https://tools.ietf.org/html/rfc8927 could be used with OpenAPI. looking at this issue, it seems that this issue is the right place to look at, but looking at the current 3.1 RC it seems that this proposal didn't make it into 3.1?

[philsturgeon]

That’s right. The tldr was that instead of getting multiple schemas supported we focused on supporting the one same single type of schema but removing all the problematic discrepancies.

I think the thinking was 3.1: JSON Schema Properly, 4.0: multiple schemas.

[dret]

On 2020-12-21 11:54, Phil Sturgeon wrote: That’s right. The tldr was that instead of getting multiple schemas supported we focused on supporting the one same single type of schema but removing all the problematic discrepancies. I think the thinking was 3.1: JSON Schema Properly, 4.0: multiple schemas.

thanks for the clarification. looking forward to OpenAPI becoming more of its "own thing" without hardcoding the choice of a schema language.

[philsturgeon]

OpenAPI is absolutely it's own thing, its an API Description Format that covers the Service Model: Headers, Paths, Parameters, everything that is API specific. v3.1 just means it now uses an existing standard for describing the "Data Model", which is a huge improvement for 3.1 as it means tooling can converge instead of people copying and pasting tools to add exceptions for nullable and other discrepancies.

I remember you being pretty excited about the discrepancy issue being resolved and wanted it to happen sooner. Well, we got it done for 3.1, and this all takes a lot more time than anyone would think! 😅

I would like to figure out how we can make OpenAPI support XML Schema, Protobuf, and GraphQL Types, as they're things we want at Stoplight anyway. If anyone would be interested in making a working group to go make a plan for this, lmk, and I can set up some calls and shuffle it along. In the past it was just lots of people saying "why isn't this done yet" then @darrelmiller trying to find time to satisfy those demands, which probably isn't how we should do things going forward.

[dret]

On 2020-12-23 06:41, Phil Sturgeon wrote: OpenAPI is absolutely it's own thing, its an API Description Format that covers the Service Model: Headers, Paths, Parameters, everything that is API specific. v3.1 just means it now uses an existing standard for describing the "Data Model", which is a huge improvement for 3.1 as it means tooling can converge instead of people copying and pasting tools to add exceptions for nullable and other discrepancies.

sure, no doubt about that. my comment was just about OpenAPI currently subsuming JSON schema, and it doesn't have to be this way.

I remember you being pretty excited about the discrepancy issue being resolved and wanted it to happen sooner. Well, we got it done for 3.1, and this all takes a lot more time than anyone would think! 😅

i still think that it's great to see JSON schema versioning having one less complication!

I would like to figure out how we can make OpenAPI support XML Schema, Protobuf, and GraphQL Types, as they're things we want at Stoplight anyway. If anyone would be interested in making a working group to go make a plan for this, lmk, and I can set up some calls and shuffle it along. In the past it was just lots of people saying "why isn't this done yet" then @darrelmiller <https://github.com/darrelmiller> trying to find time to satisfy those demands, which probably isn't how we should do things going forward.

i apart from some comments here and there i haven't really participated much in OpenAPI work. this seems like a worthy (and potentially tricky) thing to do, and i'd be more than happy to help.

[darrelmiller]

This has been a long open issue and does not seem to have gained traction with implementations. If someone wants to reboot this effort, let us know, but for the moment we are going to close it.

[no-identd]

Shouldn't this become more of a roadmap item with an as of yet unset implementation date and less something remaining as a left over, essentially un(der)discoverable, closed issue entry?