Openapi-specification: Add support for patternProperties in schemas

[dolmen]

JSON Schema draft 4 has patternProperties which is not supported by Swagger 2.0.
patternProperties allows to have loosely defined objects where the list of keys is not fixed in the spec (like additionalProperties allows in Swagger 2.0), but the format of the keys is restricted with a regexp (contrary to additionalProperties where keys are not at all limited).

Here is a use case from #380:

name: pop
description: population by country
type: object
patternProperties:
  '^[A-Z]{2}$':
    type: integer
    description: the population of the country indicated by the property name.

[ePaul]

It also allows having several patterns with each a different value schema:

type: object
patternProperties:
  '^[A-Z]{2}$':
    type: integer
    description: the population of the country indicated by the property name.
  '^[A-Z]{3}$':
    type: string
    description: the name of the airport with the given IATA airport code.

I suppose this was deemed as too complicated to map to statically typed programming languages when choosing which features from JSON schema to use in Swagger 2.0. (I still can not imagine how a schema like this would be mapped to a Java class.)

[webron]

Related to #333.
Parent: #586

[webron]

Tackling PR: #741

[sukrit007]

👍

[daicoden]

For java, if you add another key name to each pattern property, you could generate an API

type: object
patternProperties:
  '^[A-Z]{2}$':
    type: integer
    name: population
    description: the population of the country indicated by the property name.
  '^[A-Z]{3}$':
    type: string
    name: airports
    description: the name of the airport with the given IATA airport code.

request.getPatternProperty("population") <- Map<String, Integer>
request.getPropertyPattern("airports").put("DEN", "Denver International Airport")

[coltonone20]

@webron It looks like #741 was closed in favor of #894, but I did not see anything in #894 about patternProperties. Will patternProperties be added to 3.0, just in a different PR? Thanks for all your hard work on OAS, much appreciated!

[webron]

No, patternProperties did not make it into 3.0.

[hotgazpacho]

So, how can we help get patternProperties into the OAS spec? The lack of this is really hampering our ability to express our response objects in OAS.

Use case:

We have an API that allows a customer to ask "what do you know about these things?", where things can be of different types. We use the values passed in as the keys in the response to say "here's what we know about this item".

[lpapp-polatis]

I would also be keen on having this feature because this could make the json a bit shorter for swagger examples. The property name could be an "id" in our case. That could be described by a simple regexp.

[philsturgeon]

Could we get the 3.1 label on this?

[MikeRalphson]

Would that be necessary if we have x-oas-draft-alternateSchema?

[handrews]

It's worth figuring out what should happen with the almost-JSON-Schema dialect going forward. Obviously it cannot be removed in 3.x, although I would argue for removing it in 4.0 because it is burdensome for new tools to implement.

In the meantime, I'd rather focus on getting x-oas-draft-alternateSchema: realJsonSchema in than on "fixing" the almost-JSON-Schema dialect. I suspect having to implement specialized JSON Schema-ish support is one of the larger barriers for some sorts of tooling, so let's not make that more complicated. Let's encourage people to use regular JSON Schema via x-oas-draft- instead, and build the case for making that the default approach in 4.x.

[philsturgeon]

This does raise the question: What is the schema going to be in this new alternate-schema world?

@handrews if the current schema is removed, then its _only_ alternate schema, meaning whats the alternate about. Would you see OAI moving to promote alternate-schema up to schema and have all tools and all systems supporting multiple schemas as a core requirement to working at all?

Or @MikeRalphson is it more likely OAI will be keeping this OpenAPI Schema Object around indefinitely, meaning there will forever be this custom "like JSON Schema but not" format supported as core, with alternates floating around too?

If the latter, is there any interest in trying to close some of the gaps between JSON Schema and OpenAPI Schema Object, in a backwards compatible way? I can understand not deleting stuff, but adding some of the excellent functionality that JSON Schema has been adding is going to help OpenAPI users, no?

[philsturgeon]

Btw this needs to be merged whatever happens. https://github.com/OAI/OpenAPI-Specification/pull/1521

[darrelmiller]

@philsturgeon I think the end result depends a lot on the popularity of alternate-schema. If it is fabulously popular and tooling has great support for it, then I can imagine in a 4.0 timeframe dropping schema object. I suspect a significant portion of OpenAPI users are not aware that the OpenAPI Schema is any different than JSON Schema. I think the future will be largely dependent on tool adoption.

[sweepy84]

Any updates on this - badly needed. Or is there a workaround or alternative?

[nfroidure]

@sweepy84 got the same issue and found out that link:https://philsturgeon.uk/api/2018/04/13/openapi-and-json-schema-divergence-solved/

It may help you for fitting the current spec

[webron]

@hkosova pointed out to me, this can be closed as implemented in OAS 3.1.

[ctrl-f5]

If this is implemented in 3.1, could you link to the spec where patternProperties are documented? I can not seem to find them mentioned anywhere.

[handrews]

@ctrl-f5 OAS 3.1 supports all of JSON Schema drafts draft-bhutton-json-schema-00 and draft-bhutton-json-schema-validation-00. patternProperties is defined in draft-bhutton-json-schema-00

[sergiojoker11]

If this is implemented in 3.1, could you link to the spec where patternProperties are documented? I can not seem to find them mentioned anywhere.

I am struggling to find this too.

[philsturgeon]

Seeing as the Schema Object in OpenAPI v3.1 is a valid JSON Schema object, they've not needed to re-define everything in OAS, instead you can look at the JSON Schema spec or use their tutorials. https://json-schema.org/understanding-json-schema/reference/object.html#patternproperties