Alternative Schema and Custom Security Schemes

[cmheazel]

Added Alternative Schema and Alternative Schema Object.

[MikeRalphson]

Good stuff. @darrelmiller there is an implication in DEVELOPMENT.md that a draft feature won't be promoted until there has been successfull pilot implementations / feedback. Do we know of any for alternativeSchemas?

[darrelmiller]

From TSC meeting,

• Do we want to specify that anyOf fails if none of the alternateSchemas are processable?
• Do we want to enforce sequential processing of anyOf? Do we need a new keyword?
• Should we rename type to schemaType to avoid confusion with the normal schema type keyword?

Action:

• Henry will summarize what the JSON Schema anyOf behavior to ensure we attempt to remain consistent.

[philsturgeon]

Suggested change

It is important that there is a common understanding of the values which can be used to populate the alterative schema "type" property. An registry of alternative schema types is hosted at [https://spec.openapis.org/registries/alternative-schema](https://spec.openapis.org/registries/alternative-schema). This register serves as a controlled vocabulary which should be used to populate the "type" property. The Inital contents of the registry include:

It is important that there is a common understanding of the values which can be used to populate the alternative schema "type" property. A registry of alternative schema types is hosted at [https://spec.openapis.org/registries/alternative-schema](https://spec.openapis.org/registries/alternative-schema). This register serves as a controlled vocabulary which should be used to populate the "type" property. The Initial contents of the registry include:

[handrews]

Also "This register serves" -> "This registry serves"

[fenollp]

Note: link is dead for me

[handrews]

@fenollp yeah, I think the expectation is that that registry will exist by the time OAS 3.1 is published, but it has not been set up yet.

[MikeRalphson]

@fenollp you can substitute spec.mermade.org.uk for spec.openapis.org in those urls to get an idea for how the registry might look (framework is an approved proof-of-concept, but the content is purely illustrative).

[philsturgeon]

@darrelmiller schemaType 👍

[handrews]

OK, regarding anyOf, mostly this requires defining the behavior of alternativeSchemas clearly in a way that produces a sensible reaction with anyOf's semantics. This all is framed in terms of the three basic JSON Schema keyword behaviors: Assertions, Annotations, and Applicators (and if anyone has a better name than "applicators", feel free to suggest- it need not start with "a").

For those not inclined to dive into the spec:

• Assertions produce a boolean result
• Annotations attach an arbitrary value (such as a title string, or an indication that a value is read-only) to a location in the instance
• Applicators apply one or more other schemas, which may either be present inline as subschemas or referenced using URIs, to some part of the instance, and optionally combine or modify the results based on some sort of rules (e.g. in the case of anyOf, OR the assertion results and keep all annotations)

You generally want to evaluate assertions first, because if you fail an assertion you don't need to process the applicators or annotations.

anyOf applies its subschemas to the current instance location (the one the schema object containing the anyOf was being applied to), and logically ORs the assertion results. Annotations are kept from all subschemas that successfully validated. Since anyOf is not ordered (despite using a list), the annotations part means that you have to check all branches, not just until you find the first one. This will be important for OAS when we add code generation annotations.

---

So:

alternativeSchema/type is more or less an assertion- it passes if the implementation knows how to handle that type of schema. Most assertions assert things about the instance, but $vocabulary in draft-08 will also assert things about what the implementation is or is not able to handle.

alternativeSchema/location is an applicator, applying the referenced schema to the current location. Presumably, most schema systems will produce a boolean validation result. We can say that those that do not perform validation always return true, just to make the handling consistent for people writing and using alternative schema processing plugins.

If alternativeSchema/type is JSON Schema, all the usual JSON Schema rules about annotations apply. Otherwise, if the schema system has any vaguely analogous mechanism for returning some sort of data, that data becomes alternativeSchema/location's annotation result. This is assuming that collecting annotations is, at some point, of interest to OAS e.g. for code gen.

The behavior of anyOf: [{alternativeSchema: ...}, {alternativeSchema: ...}, ...] we end up with here is that schema validation fails if none of the alternatives are recognizable, or none of the recognizable ones passed validation with the alternate schema.

I would say that this is correct. If an API designer wants to allow not recognizing any of them, either because a no-op is fine or because there are also OAS-native schema keywords to evaluate, then they can just have one more branch of the anyOf that has the OAS-native schema keywords in it. Or if a no-op is fine, just add an empty schema {} to the anyOf, in which case it's guaranteed to always succeed.

[darrelmiller]

Do we need a allOf that has firstOf semantics? Should this be a blocker for shipping alternative-schema?

[handrews]

x-oas-draft-firstOfPleaseDontBugJSONSchemaAboutThis 😜

[handrews]

As noted on today's call (for the benefit of those not present), I think (pending the resolution of other procedural concerns), we should move ahead with alternativeSchema for the many use cases that do not require firstOf semantics, and consider x-oas-draft-firstOf to get more feedback on that use case. Particularly how prevalent it is in practice.

[cmheazel]

The Web Feature Service (ISO 19142:2010) is a Web Service which allows clients to discover and access spatial/temporal objects (Features). Version 3.0 of the WFS is based on OpenAPI. I have received some feedback from the implementors of this standard relating to alternative schema: 1) Peter Vretanos, Cubewerx, "Our WFS 3.0 supports numerous output formats. Some of these have associated schema descriptions that are not easily mapped into the JSON-Schema that OpenApi uses. Actually, in some cases the schema is not expressed in JSON or XML at all (e.g. DTD or SQL DDL) making it impossible to describe resources using OpenAPI's existing mechanisms. Having the ability to reference an external schema to describe such resources would be a big plus for us!" 2) Andre Aime, GeoSolutions, "for INSPIRE compliant WFSs the ability to refer to an external standard schema is pretty much a requirement" NOTE: INSPIRE is the European Union directive to create a European Union spatial data infrastructure based on Web standards. See https://inspire.ec.europa.eu/

[cmheazel]

Added Custom Security Schemes per our discussion at the last meeting.

[MikeRalphson]

Added Custom Security Schemes per our discussion at the last meeting.

@cmheazel It may be better to add that as a separate PR, thus they can be merged independantly, and we can guarantee easy reversion if any problem is later found.

[cmheazel]

@MikeRalphson Will do. Can't get it done for Thursday though.

[MikeRalphson]

No problem.

[MikeRalphson]

Split as per comments.

[darrelmiller]

@webron Needs to comment on this during his long holiday break.

[ioggstream]

@cmheazel Hi! And thanks for this great PR. Did you had the chance to split your PR? #1736 (comment) If you want I can help ;)

[cmheazel]

@cmheazel Hi! And thanks for this great PR. Did you had the chance to split your PR? #1736 (comment) If you want I can help ;)

Hi @ioggstream if you have the time I would appreciate the help. I'm a bit swamped at the moment.

[ioggstream]

I'd add a fragment to better clarify https://github.com/OAI/OpenAPI-Specification/pull/1736/files#diff-b83206d953b4be5d312b068f82ba0217R3174

eg. see https://github.com/teamdigitale/api-openapi-samples/blob/alternativeSchema/openapi-v3/external-schema.yaml

            anyOf:
            - alternativeSchema:
                type: xmlSchema
                location: schema.xsd#/person

@andreapoli

[ioggstream]

If next OAS will use jsonSchema this could be removed, right?

[philsturgeon]

We aren’t updating alternative schema until #1977 is in, and it may well stay because in the future JSON Schema v1.0 will be different from the OpenAPI JSON Schema vocab pegged to 2019-09.

…

On Thu, Nov 7, 2019 at 11:47, Roberto Polli ***@***.***> wrote: @ioggstream commented on this pull request. --------------------------------------------------------------- In [versions/3.1.0.md](#1736 (comment)): > +```yaml +schema: + type: array + items: + alternativeSchema: + type: jsonSchema + location: ./real-jsonschema.json +``` + +##### Alternative Schema Registry + +It is important that there is a common understanding of the values which can be used to populate the alterative schema "type" property. An registry of alternative schema types is hosted at [https://spec.openapis.org/registries/alternative-schema](https://spec.openapis.org/registries/alternative-schema). This register serves as a controlled vocabulary which should be used to populate the "type" property. The Inital contents of the registry include: + +Name | Link | Description +---|:---:|--- +<a name="jsonSchemaType"></a>jsonSchema | `https://spec.openapis.org/registries/alternative-schema#jsonSchema` | JSON schema documents If next OAS will use jsonSchema this could be removed, right? — You are receiving this because you commented. Reply to this email directly, [view it on GitHub](#1736?email_source=notifications&email_token=AAAQONLOQCUMWR6O5FNANW3QSP54FA5CNFSM4GARED3KYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCKWFGQY#pullrequestreview-313283395), or [unsubscribe](https://github.com/notifications/unsubscribe-auth/AAAQONMOC3CMCEQHGAFW7YTQSP54FANCNFSM4GARED3A).