Repository navigation
Proposal: x-oas-draft-alternativeSchemas #1532
Description
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-schemabecause 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
typefield 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
typethat 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
externalValueproperty is required and must be a relative or absolute URL. - The
alternate-schemaproperty can be used anywhere theschemaproperty can be used.
Activity
philsturgeon commentedon Apr 9, 2018
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 hassyntax = "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 commentedon Apr 9, 2018
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 commentedon Apr 9, 2018
@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 commentedon Apr 9, 2018
I am no longer conflicted. 👍🏼
handrews commentedon Apr 10, 2018
@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 commentedon Apr 10, 2018
@handrews It's the only other schema language in JSON that I know of. And no, nobody has ever asked for support.
MikeRalphson commentedon Apr 10, 2018
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 commentedon Apr 10, 2018
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 commentedon Apr 10, 2018
As the guidance for the json schema
$schemakeyword isI don't think we need any additional recommendation that people declare their json schema version. Presumably the
$schemakeyword 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 commentedon Apr 10, 2018
@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
$schemaand base URI, work based on the schema document scope, not how you got to a schema object.handrews commentedon Apr 10, 2018
I think with the vocabulary stuff in draft-08 we'll be clarifying the schema document / file-scope stuff a lot, including how
$schemaand the closely related proposed$vocabularywork.MikeRalphson commentedon Apr 10, 2018
Thanks @handrews
darrelmiller commentedon Apr 23, 2018
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.
alternate-schemasbecause 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.alternate-schemasproperty 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.typefield 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.externalValueproperty is required and must be a relative or absolute URL.alternate-schemaproperty can be used anywhere theschemaproperty can be used.cmheazel commentedon Apr 23, 2018
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.
99 remaining items
darrelmiller commentedon Dec 27, 2019
@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 commentedon Dec 27, 2019
@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 commentedon Dec 27, 2019
@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 commentedon Dec 27, 2019
@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 commentedon Dec 27, 2019
I am not.
matjung commentedon Apr 8, 2020
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 commentedon Apr 8, 2020
I would also love to see a way to link openapi schema with a csvw or frictionless data csv schemas
dret commentedon Dec 21, 2020
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 commentedon Dec 21, 2020
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 commentedon Dec 22, 2020
philsturgeon commentedon Dec 23, 2020
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 commentedon Dec 23, 2020
darrelmiller commentedon Mar 17, 2022
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 commentedon Aug 22, 2022
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?