Openapi-specification: Make schema object compatible with JSON Schema specification

[epoberezkin]

That's is related to #333

Given that all the major differences were removed in version 3, what is the reason to have remaining differences?

• type as array is just a syntax sugar for anyOf
• items - what is the reason to not support array syntax? APIs returning tuples and other heterogenous arrays are [regrettably] present. Why spec says items MUST be present? What's wrong with it not being present?
• patternProperties - together with propertyNames added in draft-06 it is needed to support hash-maps rather than records.

Additional fields in schema are not a problem, but it still beats me why the restrictions are needed - they create nothing but inconvenience. The argument that certain functionality of tools can't be supported for the full JSON schema spec (see https://github.com/OAI/OpenAPI-Specification/issues/333#issuecomment-179367580 by @fehguy) is a very week one to not support full JSON schema in API spec.

Instead, OpenAPI can say that tools can choose to support full or restricted JSON-schema and make it clear in their documentation.

I understand that it means that the code in some language may not be possible to generate due to the restrictions of those languages. But it should be the problem constrained to the users of that particular language rather than to all users (using more dynamic/loosely typed languages). If I were to need to generate c++ code from OpenAPI spec, the generator would impose these restrictions and I would simplify the API definition file.

Having full JSON-schema spec allowed outweighs the benefit that ALL tools can always work with the schema - I believe it should be left to the developer's discretion to decide whether to use full/restricted schema rather than having "restricted" imposed by OpenAPI as the only possible option. This "nanny state" approach is very frustrating when using this spec.

It would also allow to simplify this spec by simply referencing JSON schema spec instead of redefining it here.

[avkonst]

Great justification! I totally agree.

[MikeRalphson]

Re: patternProperties - is this any more difficult for tooling to support than additionalProperties ? I ask because I'm trying to ascertain how close we would be for an OpenAPI-described API to be able to serve its own OpenAPI definition via a schema-defined response. I'm using as my example the draft OpenAPI 3.0.x schema under development at google gnostic.

[webron]

I don't really see the ability to define an OpenAPI definition that accepts an OpenAPI definition as a drive to support patternProperties. There are other reasons to support it, but this is not it.

[Relequestual]

@webron I know @handrews and @philsturgeon have been on OpenAPI steering calls of late, sorry I haven't been able to attend due to travel.

Has there been any further discussion or thoughts on this since 2017?

[Relequestual]

Maybe this is the same as #1443 ?

[philsturgeon]

Correct @Relequestual, this would be taken care of by #1443.

[lpinca]

It's a shame that items does not support the array syntax. There is currently no way to define a tuple like

{
  "type": "array",
  "items": [
    { "type": "string" },
    { "type": "string" },
    { "type": "integer" }
  ]
}

The closest thing is

{
  "type": "array",
  "items": {
    "anyOf": [
      { "type": "string" },
      { "type": "string" },
      { "type": "integer" }
    ]
  },
  "minItems": 3,
  "maxItems": 3
}

but ofc it's not the same.

[handrews]

@lpinca See #1736 - assuming tooling vendors support proper JSON Schema (hopefully more recent versions) as alternativeSchemas, this will be addressed in OAS 3.1.

[lpinca]

@handrews awesome! Thank you.

[tedepstein]

Why not use an array of object?

{
  "type": "array",
  "items": {
    "type" : "object", 
    "properties": {
      "s1": {
        "type": "string"
      }, 
      "s2": {
        "type": "string"
      },
      "i1": {
        "type": "integer"
      }
    }
  },
  "minItems": 3,
  "maxItems": 3
}

I understand a tuple is not an object, because its members are unnamed. But I never saw a really good reason why it's a problem to name the members.

[lpinca]

@tedepstein you are right but the spec i'm working on is for an existing API not a new one, changing it it's a breaking change.

[tedepstein]

@lpinca, thank you for the explanation. I feel better now. :-)

[ikokostya]

Label Post 3.0 Proposal for this issue is not clear.

Looks like version 3 of OpenAPI specification still doesn't support tuple syntax for arrays: https://github.com/OAI/OpenAPI-Specification/blob/04f659aeffd3082de70212189477def845c68aa6/schemas/v3.0/schema.json#L470

Is it correct?

[ikokostya]

There is another problem: null type is not supported https://github.com/OAI/OpenAPI-Specification/blob/04f659aeffd3082de70212189477def845c68aa6/schemas/v3.0/schema.json#L412

Refs https://github.com/OAI/OpenAPI-Specification/issues/1368

[philsturgeon]

I was hoping that alternative schema would be the savior here, but the current approach is not what I hoped it would be: #1943

Instead https://github.com/OAI/OpenAPI-Specification/pull/1977 is a new effort at closing the gap on OpenAPI v3.1 and JSON Schema.

[philsturgeon]

This was fixed in #1977 so we can close this.