Variable schemas for OASv2 and OASv3 (edge case)

[MikeRalphson]

My example is Microsoft's x-ms-paths (docs). Where x-ms-paths is an analogue of the paths property (i.e. it contains pathItem Objects).

I'm assuming MS will continue to use x-ms-paths with OASv3, as the problem it 'solves' is unchanged in OASv3. So in OASv2 it will be structured like a container of OASv2 pathItem Objects and OASv3 pathItem Objects in OASv3.

So, would something like the following be valid?

#...
com.microsoft:
  x-ms-paths:
  #...
    schema:
      oneOf:
      - $ref: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v2.0/schema.json#/definitions/Paths
      - $ref: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/49e784d7b7800da8732103aa3ac56bc7ccde5cfb/schemas/v3.0/schema.yaml#/definitions/Paths

And does it provide enough information as to the context for the use of each schema? Without some kind of hint, it seems to me that the schema would be only really suitable for validation, not auto-completion (generated documentation would be partially useful).

I think an OASv2 schema object is a proper subset of the OASv3 schema object, unless it references type: file or discriminator.

One option would be to have a schema property under the oas2 and oas3 properties which overrides the default schema. Then each could be defined as their appropriate type from the relevant spec. version (refs #4, #8 (comment)), and we gain a mechanism to support OASv4 etc. It would still be up for debate as to whether the top-level schema should be JSON-Schema draft X or some version of OpenAPI-Schema.

[tedepstein]

Thinking about this one.

One option would be to have a schema property under the oas2 and oas3 properties which overrides the default schema. Then each could be defined as their appropriate type from the relevant spec... and we gain a mechanism to support OASv4 etc.

The ability to specify things at different levels -- global to the namespace, property-specific, context-specific, etc., makes sense. OpenAPI does this.

But it's a stumbling block for implementations. We often find that code generators and documentation UIs, even including Swagger-UI, will sometimes fail to follow the rules for these "cascading" propeties. They only recognize them when declared at one particular level, or they don't apply the correct merging or override semantics when the property is specified at more than one level.

We introduced Swagger-Normalizer as a component of our commercial solution, more or less by necessity, to solve these problems. (Cascading properties are one category of problem solved by Normalizer; it also deals with external references, simplifying these things for downstream processors.)

So I'm a little hesitant to introduce cascading and override into these features, where we don't really need it. Even if we provided our own implementation of a normalizer-style pre-processor for Semoasa in some language, or set of languages, people will want to implement in other languages. Or they may just not want the added weight of a pre-processor.

Alternative approaches would include:

1. Use a more relaxed schema that accommodates all contexts, as you described.
2. Declare two or more context-specific extension properties, with different names, within the same namespace. (Not a very attractive option for most use cases, but I'm listing it here for completeness.)
3. Declare two or more context-specific extension properties, with the same name, in different namespaces. (Maybe not too bad, as long as we have good-enough component reuse to keep duplication to a minimum.)

[MikeRalphson]

Ah, must confess I hadn't considered your option 3. That I think would work fine.

[tedepstein]

OK, I'll close this one. We can reopen later if it seems like it's worth reconsidering.