Proposal: x-oas-draft-alternativeSchemas

[darrelmiller]

A long standing request has been to add support for alternate schemas. See OAI/OpenAPI-Specification#764 OAI/OpenAPI-Specification#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 OAI/OpenAPI-Specification#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

[tedepstein]

Question: have we considered allowing scenarios where schema is used as an "information-only" approximation of the "real" schema, specified under alternateSchemas?

This could be useful to provide documentation in formats or interactive UIs that are not able to process the authoritative schema in its native format, but can still present standard OAS Schema Object as an abstraction, or high-level guideline to the message structure.

[tedepstein]

Also, can you include an OAS Schema Object (i.e. a "standard" OpenAPI schema) in alternateSchemas list, as a way to specify its order of preference with respect to other alternateSchemas?

If you don't do this, but you do specify both schema and alternativeSchemas, is the standard schema entry assumed to go at the end of the list, as the least preferred option?

[handrews]

@darrelmiller

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.

So this means it cannot be used anywhere outside of the Media Object? That feels more complicated to me. In particular, it makes the case of sharing a schema between the Media Object and Parameter Object (or other places where a schema can occur) impossible with alternate schemas, so now instead of being able to use fewer schemas you need to use even more.

[darrelmiller]

@tedepstein @handrews Following a conversation with @webron I am considering an alternative place to put the alternative schema field. :-)

Specifically because of the fact that you can $ref native schema objects, it might make sense to put the alternativeSchemas property in the native Schema Object. This gives a few benefits:

• easier to add alternativeSchemas that currently exist in a document and are re-used in multiple places.
• tooling implementers only have to implement the property in one object
• we are able to use alternativeSchemas anywhere the schemas are currently used.

This would make it look like this:

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-alternativeSchemas:
                  - 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:
              schema:
                x-oas-draft-alternativeSchemas:
                  - type: xml-schema
                    externalValue: ./cat-schema.xsd
                  - type: relax-ng
                    externalValue: ./cat-schema.ng
                  - type: schematron
                    externalValue: ./cat-schema.st

[handrews]

@darrelmiller @webron @tedepstein I like this new idea of putting it in the Schema Object! Much more consistent. I think it's important that schemas (in the general sense) have the same capabilities anywhere they can be used.

From a JSON Schema perspective of processing the OAS-native schemas, x-oas-draft-alternativeSchemas can be treated kind of like an opportunistic allOf.

I was going to ask about externalValue vs $ref, but I guess externalValue makes more sense for non-JSON Schema alternatives. I don't feel strongly about it- if I want to $ref something in some way that doesn't work with externalValue I can make my external document just {"$ref": "whatever"}

Is the type: object in the application/json example required for some reason or is it just there to provide a minimal indicator to tools that don't understand x-oas-draft-alternativeSchemas?

[ralfhandl]

@darrelmiller @handrews I would have assumed that I can use JSON Pointer fragments in externalValue with type: json-schema to avoid having "wrapper files" for addressing a certain part of a "schema collection" within a single file.

[darrelmiller]

@handrews the type:object was just my minimal OAS Schema to indicate that OAS Schemas can be used in combination with alternativeSchemas.

@ralfhandl That's a good question. URL fragments are a natural feature of a URL, so it seems reasonable to enable support for JSON Pointers in URL fragments. We need to decide if we want to add that burden onto tool devs. It does seem like a reasonable requirement but we definitely should call it out if we do decide to support it.

[handrews]

@ralfhandl @darrelmiller URI fragment syntax/support is determined by the media type of the target resource, not the source, so any application/schema+json document should be addressable with either JSON Pointer fragments or plain name fragments (created by "$id": "#this-is-a-plain-name").

Not supporting it would be failing to support the media type properly.

@ralfhandl never mind my $ref example, I can't even remember exactly what I thought externalValue couldn't do. Although if it forbids part of the URI syntax (fragments) that would be a problem and would require weird indirection such as an extra schema document that is just a $ref.

[chriskapp]

Hi, could we not also simply add the $schema keyword to the Schema Object to indicate the JSONSchema version of the provided schema i.e.:

application/json:
  schema:
    $schema: "http://json-schema.org/draft-07/schema#"
    type: object

If no $schema is available we would assume the OAI JSON Schema. For alternate schemas XSD etc. we could still use the x-oas-draft-alternativeSchemas keyword but I think for tool developers (like me) this would make things much easier.

[handrews]

@chriskapp how would handling it inline be easier? Mostly people seem to want to be able to just hand the external file off to whatever 3rd-party schema tooling is being used. Are you planning to directly implement standard JSON Schema support within your OpenAPI implementation?

[cmheazel]

Can we please stop changing this? I'm trying to implement.

[chriskapp]

@handrews yes this was my idea/hope to use a normal JSONSchema parser inside OpenAPI. If we take a look at the solution:

application/json:
  schema: <-- OpenAPI JSONSchema standard
    type: object
    x-oas-draft-alternativeSchemas:
      - type: json-schema
        externalValue: <-- JSONSchema standard draft-04, draft-08, etc.

a parser would then basically look for both schemas and then its maybe not clear which schema to use. Maybe the logic is to use the OAI JSONSchema for code generation and the normal JSONSchema only for validation? On the other hand a generator maybe uses the same schema multiple times, maybe also with the extra burden to generate a separate file. I think this makes the implementation and tooling more difficult since OAI JSONSchema and JSONSchema could be the same with some extra effort.

@cmheazel I dont want to generate work here but Iam under the impression that this topic is still under discussion and I feel like its important to give feedback from a tool developer perspective.

[MikeRalphson]

@chriskapp perhaps this wording

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.

Needs to be clarified to indicate that "capable of processing" is specific to the context for which the tool is using the schema/alternativeSchema (i.e. validation, documentation generation, code generation etc).

Thank you for the link to JSON Schema Code: JSON Schema rules to simplify code generation I hadn't previously come across this. Perhaps it may inform the proposed JSON Schema code-generation vocabulary?

[cmheazel]

@chriskapp I was under the impression we had settled this at the last TSC meeting. Re-reading the minutes it appears that I was mistaken.
Personally, I found the version we discussed Monday to be simple, elegant, and easy to implement.

[chriskapp]

@MikeRalphson yes this spec was a first attempt to build such a vocabulary for the JSON Schema spec to combine OAI JSON schema and JSON schema. There is also a PR at the JSON schema vocabulary repository regarding this. Iam currently not sure about the state of the vocabulary separation inside the JSON Schema spec (@handrews can probably say more about this) but maybe its worth to take those ideas into consideration.

[handrews]

@chriskapp my apologies for not recognizing you- you changed your github id didn't you? :-)

All: @chriskapp wrote that spec (and the related PR) incorporating advice from me on stating things in terms of restricted interpretations. However, the difficulties associated with that approach (you can see me comment on some in the PR) were a major motivation for the formalized annotation collection and extensible vocabularies approach planned for draft-08.

Rather than restricting keywords (which is not visually apparent when looking at the keywords in the schema), I expect things like code generation to add annotations that disambiguate keywords that are difficult to handle. There is a bit more about this in the PR, although nothing like a new proposal. I don't want to derail this issue, but this shift in approach to generative use cases for JSON Schema (code generation, UI generation, documentation generation) is arguably the most important thing in draft-08. And very relevant to OpenAPI.

[darrelmiller]

@cmheazel I thought we had a reasonable approach on Monday, but then it was brought to my attention that if we have the alternativeSchema as a peer to schema that is going to be a real pain for schemas that are referenced. This was big enough of an issue for me to change the status back to draft:proposal from draft:pilot. My apologies for not making that clear.

[darrelmiller]

I want to update this proposal with the new approach using alternativeSchemas as a property of the schema object. However, this opens a whole new set of questions. The Schema object is defined recursively and therefore we need to ask if it makes sense to have representations where portions are defined by the native Schema Object and other parts by an alternative schema. Also, if the Schema object has an oneOf and allOf, do we really need alternativeSchemas to be a list.

Here are some spitballed ideals...

Simple case

type: object
alternative-schema:
  type:  jsonSchema 
  externalValue: ./myschema.json

Nested alternative schemas

type: array
items:
  alternative-schema:
    type:  jsonSchema 
    externalValue: ./myschema.json

Support for tools with different capabilities

type: object
oneOf:
  - alternative-schema:
      type:  jsonSchema 
      externalValue: ./myschema-draft-06.json
  - alternative-schema:
      type:  jsonSchema 
      externalValue: ./myschema-draft-07.json

Layered validation

type: object
allOf:
  - alternative-schema:
      type:  xmlSchema 
      externalValue: ./myschema.xsd
  - alternative-schema:
      type:  schematron 
      externalValue: ./myschematronvalidation.st

[darrelmiller]

@chriskapp Based on various feedback I'm getting the impression we are going to have to have a way to further qualify the "version" of the type of alternate schema. My immediate reaction is that I'm not a fan of the $schema notion just because it is feels specific to JSON Schema and we need this ability for other schema types also. But I agree we need to think more about this.

[cmheazel]

@darrelmiller I thought we had a reasonable approach as well. I've seen these efforts turn into a debating club. Round and round without ever reaching a conclusion. I was afraid that was happening here. That being said, the discussion has moved forward addressing valid issues. So I'll be patient and behave myself.

[tedepstein]

The property is called alternative-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.

When we say both schemas must be respected, that means the content must conform to both schemas in order to be valid. But it doesn't necessarily mean that implementations are required to validate against both schemas, or otherwise "use" both schemas. Is that right?

If we move x-oas-draft-alternative-schemas into the Schema Object, then I think this also means:

1. If the Schema Object does not specify any constraining properties (type, properties, maxLength, etc.), then the content does not need to be JSON. It only needs to conform to the specified alternative schemas.
2. If the Schema Object does specify constraining properties, then the content must be JSON, and must conform to the native Schema Object constraints, as well as any alternative schemas.
3. (Maybe) if the Schema Object specifies non-constraining properties like title, definition, and documentation those become part of the schema object definition, but do not require the content to be valid JSON.

Thoughts about that last point? I think it's valuable to assign non-constraining metadata to the Schema Object without implying that the content must be valid JSON.

Also, I think we may still need to clarify the relationship of the native OAS Schema Object vs. alternative schemas:

• The alternative schemas form a sequence, in order of preference from the designer's point of view. I assume we will give guidance that implementations SHOULD honor this order, by using the most preferred schema that the implementation is capable of using for its purpose (validation, documentation, etc.).
• In the case where a native Schema Object and an alternative schema are both applicable, are implementations required (MUST) or encouraged (SHOULD) to use both of these for validation purposes? (I would vote no.)
• In that case, should the matching alternative schemas take priority over the native schema objects, so the native Schema Objects are least preferred? (This seems like a reasonable default behavior.)
• Will native OpenAPI 3.x Schema Objects be one of the entries in our schema types registry, so the API can specify this in the alternative schemas list, and thus assign a position in the order of preference? (This seems like it would be useful.)

[tedepstein]

Will there be a way to designate the native Schema Objects as "information-only", so they can be used in documentation as a general guide to the structure of the message? I think this is important for documentation formats in particular. It will be difficult (or at least will take some time) for documentation presentation formats to support all of the most common schema types, and it is always possible to introduce new schema types that aren't universally supported by mainstream documentation formats. Users will be discouraged from using these formats if they cannot also use common documentation formats with them.

@chriskapp wrote:

Maybe the logic is to use the OAI JSONSchema for code generation and the normal JSONSchema only for validation?

This suggests that we might need a usage keyword, whose value is an array of SchemaUsageType values, where SchemaUsageType is an enum of common schema usage contexts: documentation, validation, code generation, and maybe a few others.

The default would be all usages, so the presence of a usage value has the effect of limiting the usage. This also changes the schema selection algorithm: tools should use the first applicable schema that the tool is capable of processing, where "applicable" means that the schema matches the media type of the content, and matches the usage context.

          content:
            application/json:
              schema:
                type: object
                x-oas-draft-alternativeSchemas:
                  - type: json-schema
                    externalValue: ./cat-schema-draft-08.json
                    usage: 
                    - documentation
                  - type: json-schema
                    externalValue: ./cat-schema-draft-05.json
                  - type: json-content-rules
                    externalValue: ./cat-JCRschema.json
            application/xml:
              schema:
                x-oas-draft-alternativeSchemas:
                  - type: xml-schema
                    externalValue: ./cat-schema.xsd
                    usage: 
                    - documentation
                    - validation
                  - type: relax-ng
                    externalValue: ./cat-schema.ng
                  - type: schematron
                    externalValue: ./cat-schema.st

@MikeRalphson wrote:

Needs to be clarified to indicate that "capable of processing" is specific to the context for which the tool is using the schema/alternativeSchema (i.e. validation, documentation generation, code generation etc).

Yes, similar idea, factored a bit differently. ;-) But I'm suggesting we make the intended usage contexts explicit in the API spec.

@handrews wrote:

Rather than restricting keywords (which is not visually apparent when looking at the keywords in the schema), I expect things like code generation to add annotations that disambiguate keywords that are difficult to handle. There is a bit more about this in the PR, although nothing like a new proposal. I don't want to derail this issue, but this shift in approach to generative use cases for JSON Schema (code generation, UI generation, documentation generation) is arguably the most important thing in draft-08. And very relevant to OpenAPI.

This sounds kind of similar to what I'm suggesting, but I really cannot tell without more background on the PR you're describing. Should I read up on some of this to get a different perspective on this idea of usage context, and how we might support it in OAS alternative schemas?

[tedepstein]

@cmheazel wrote:

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.

I know we talked about this on the last meeting. Where did that land?

[tedepstein]

@handrews wrote:

I was going to ask about externalValue vs $ref, but I guess externalValue makes more sense for non-JSON Schema alternatives. I don't feel strongly about it- if I want to $ref something in some way that doesn't work with externalValue I can make my external document just {"$ref": "whatever"}

The $ref would imply that it's a JSON Reference, which is not necessarily what we want in all cases, but it does give users and tool vendors clear guidance as to how to handle the fragment. In the absence of that, how will we manage referencing of schemas somewhere within a resource? Will we apply some standard across all of the schema types? Or will each schema type in our registry specify hash fragment interpretation (e.g. XPath for XML Schema)...?

URL fragments are a natural feature of a URL, so it seems reasonable to enable support for JSON Pointers in URL fragments. We need to decide if we want to add that burden onto tool devs. It does seem like a reasonable requirement but we definitely should call it out if we do decide to support it.

JSON Pointer fragments are already supported, and have great practical value for packaging related definitions into a single resource, and referencing them there. My concern is that JSON pointer is (AFAIK) useless for schema formats that are not JSON.

So I'm thinking that standardizing the fragment semantics as part of the schema type registry entry might be a pretty sensible way to deal with this.

[handrews]

@tedepstein

So I'm thinking that standardizing the fragment semantics as part of the schema type registry entry might be a pretty sensible way to deal with this.

Per RFC 3986 §3.5:

The semantics of a fragment identifier are defined by the set of representations that might result from a retrieval action on the primary resource. The fragment's format and resolution is therefore dependent on the media type [RFC2046] of a potentially retrieved representation, even though such a retrieval is only performed if the URI is dereferenced. ... Fragment identifier semantics are independent of the URI scheme and thus cannot be redefined by scheme specifications.

OAS cannot define fragment syntax and semantics, in a registry or otherwise. Only the media type of the target representation can define those semantics. JSON Schema defines semantics for JSON Pointer and plain name fragment syntax. XML defines fragment based on the XPointer framework. These are not re-definable.

[handrews]

@tedepstein

If the Schema Object does specify constraining properties, then the content must be JSON, and must conform to the native Schema Object constraints, as well as any alternative schemas.

JSON Schema does not require the content to be JSON, only that the content can be mapped into the data model, which is derived from JSON. Some media types, such as YAML as long as it doesn't use the more exotic features, are trivial to map, while others (XML) do not have an obvious mapping.

(Maybe) if the Schema Object specifies non-constraining properties like title, definition, and documentation those become part of the schema object definition, but do not require the content to be valid JSON.

This gets into the difference between assertions and annotations. How annotations get used is application-defined, so OAS can say anything it wants about that.

[handrews]

@tedepstein I am definitely against a "usage" concept. With multi-vocabulary support in draft-08, the vocabulary in use should indicate its purpose. Of course applications can attempt to do whatever they want with a schema (such as generate code from the validation vocabulary alone, even though it's not well-suited for such things), but the way you'd tell if a schema is intended for code generation is to check whether it uses the code generation vocabulary.

[darrelmiller]

@tedepstein Regarding this:

When we say both schemas must be respected, Perhaps a better word would have been "processed" instead of "respected". If the tool doesn't understand an alternativeSchema, it cannot be expected to guarantee that it validates.

The idea of adding a usage property concerns me significantly. The application of schemas are currently vauge and I actually think that is a feature. I think any attempt to nail down an enumeration of usages would be both insanely challenging and ultimately restrictive.

The alternativeSchema feature is an escape hatch for people who know what they are doing, understand the limitations of OAS Schema and are aware of the limited tooling support for alternative schemas.

OAS schema objects are already used for non-JSON payloads, e.g. form encoding.

I believe if OAS schema constraints exist, their impact will be unaffected by the addition of the new alternativeSchema property. alternativeSchema is always in addtion to the OAS Schema object. This should never cause a problem because an empty OAS Schema Object allows everything.

If you look at the example snippets I gave in my last comment, the one labelled Layered Validation shows how allOf could be used to address the scenario @cmheazel brought up with Xml Schema and Schematron.

[darrelmiller]

So far, I like the idea of adding alternativeSchema to OAS Schema because:

• It makes $refs just work
• It makes alternativeSchema an object instead of a list, making the simple case even simpler
• It enables allOf and anyOf scenarios covering both reasons for having multiple alternative schemas
• It enables single representations to be validated by multiple schema languages. e.g. folks who embed encoded XML in JSON properties could actually validate that XML.

The one thing I'm not sure of is whether JSON Schema's rules for processing oneOf match what we were propsing. i.e. Walk the array in order and stop as soon as you find one that works.

I do think we should be explicit in indicating that externalValue can have a fragment identifier and therefore can point to a portion of a target document.

The only remaning issue I see is that not having a schema version property is going to force tools to load a schema to learn whether they support that version. That may be prohibitively expensive. So we probably need a generic way of identifying a version of a schema.

[tedepstein]

The one thing I'm not sure of is whether JSON Schema's rules for processing oneOf match what we were propsing. i.e. Walk the array in order and stop as soon as you find one that works.

It sounds like anyOf would be a better fit for this.

[philsturgeon]

I'm worried that we're overthinking some of this, and this thread feels like we're jumping the shark. 🏄🦈

I really liked the initial proposal, as defined here my Darrel in this comment.