JSON Schema Support Proposal

[webron]

WIP

This PR will build up to a proposal for the changes in handling JSON Schema in OpenAPI.next.
This comment will be modified as the proposal evolves.

At this time, please avoid adding comments to this proposal. Comments will be deleted. When the status of the PR changes, comments and discussions would be welcome.

This PR does not cover representation of XML and alternative data structures.

[ralfhandl]

@fehguy Using allOf might make it more difficult for tools.

Following the discussion in #556 I experimented with description nested within JSON References versus allOf. In the allOf variant both Swagger UI and Swagger Editor were more likely to "give up" on type expansion and just mark a property's type as "undefined", whereas additional properties within JSON References allowed correct expansion of types.

[tedepstein]

There's a conflict between the allOf semantics and the default value of false for additionalProperties.

Consistent with JSON schema, an allOf schema is valid "if and only if it is valid against all the schemas in this keyword's value."

In JSON Schema, this example:

{
  "a" : "Jack",
  "b" : "Jill"
}

...is valid against this schema:

    allOf:
    - type: object
      properties:
        a:
          type: string
    - type: object
      properties:
        b:
          type: string

This holds true because:

• The example is valid w.r.t. the first schema (defining only property 'a'); and
• The example is valid w.r.t. the second schema (defining only property 'b'); and

But both of those conditions depend on the default value of true for additionalProperties. If additionalProperties were false, then the example wouldn't be valid w.r.t. either of those subschemas:

• The example is invalid w.r.t. the first schema because the additional property b is disallowed.
• The example is invalid w.r.t. the second schema because the additional property a is disallowed.

IIUC, based on @webron's earlier comments, the intention in the current 2.0 and planned 3.0 versions of OpenAPI is to redefine the default value of additionalProperties to false, and disallow setting it to true.

We can talk about how to resolve this. But first:

• Is the problem clear enough?
• @webron, do I understand your earlier comments correctly?

[ePaul]

@fehguy I think in your format example of type:integer the fallback description is backward (i.e. it should be »type: integer, format: int64 falls back to type:integer«.)

[fehguy]

@ePaul no, exactly the opposite. If you don't specify the format, the underperscribed type, integer would have a fallback to int64 in my example. integer on its own, is simply ambiguous.

[ePaul]

@fehguy Hmm, then the text needs to be clearer, I've read it differently. (And the spec would need to say which format is the default for each type.)

My approach would be to say:

• type: string without format = any JSON string, without any restrictions or special interpretation.
• type: number without format = any JSON number (= a decimal number with any number of digits before and after the decimal point, possibly represented on wire with e-notation). In Java this would correspond to BigDecimal.
• type: integer without format = any JSON integer (= a decimal number without a decimal point, with any number of digits, possible represented on wire with e-notation using a positive exponent). In Java this would correspond to BigInteger.

(For types boolean, object and array there are no formats anyways, and null is not a real type.)

And all formats unsupported by an implementation would fall back to those meanings – this allows any application to work around the non-support. This is how I interpreted the current spec anyways.

We could introduce a format: abitrary or similar for this meaning.

[webron]

Closed in favor of (the now merged) #894.