Is `type` a required field for Schema Objects?

I am wondering how to interpret the following line of OpenAPI 3 (as of v3.0.1):

type - Value MUST be a string. Multiple types via an array are not supported.

Does this mean that the type field is mandatory and must be a string, or that it is optional and if it exists it must be a string?

[tedepstein]

I don’t think I would support a proposal to make type required, even though it would make my life easier as a tool provider.

Aside from being a breaking change, it would limit the use of OpenAPI to describe some APIs in the wild that actually do allow more than one data type for certain parameters or properties. I don’t think this is good API design, but OpenAPI should be able to describe bad APIs as well as good ones.

That said, optional typing is a legitimate challenge for code generators and implementation frameworks. So we can consider a range of possible ways to deal with this:

1. Leave it entirely up to the generators and frameworks. Let them do their own validation, and either reject OAS documents with missing type, or use type inference and default behaviors, along with appropriate configuration options and log information. This is what we’re doing today.
2. Lean on tool providers to facilitate creation of implementation-ready OpenAPI specs using extra validations (or other feedback), and to make these features highly discoverable so API designers are encouraged to use them. Further to this:
   • Explore JSON Schema Vocabularies. This is a planned set of features that I have only vague knowledge of, as I haven’t read the draft proposal. I think of vocabularies as something similar to UML profiles, but I’m not sure how close they are. Maybe it will be possible to create an “API Implementation Vocabulary” that makes type required, among other things.
   • Standardize the Implementation Profile using JSON Schema vocabularies, or some other profiling mechanism. Converge on an agreed set of constraints (and maybe extensions) to be defined under OpenAPI itself, or as a separate, related project.
3. Use SHOULD or RECOMMENDED in the OAS3 spec to indicate that type should be specified, wherever practical, to confer a minimum level of precision required by a broad set of downstream consumers, including code generators, frameworks, etc.
   • This would be a non-breaking change, but would allow our editors (and other commercial and open source editors) to flag missing type as a warning, while still remaining in full conformance to the OpenAPI specification.
   • I think a guideline like this could also be considered benign with respect to the planned alignment of OAS with JSON Schema. But that might need further discussion.

[tedepstein]

@silkentrance,

and maybe, just maybe, and since the OAS is defined using JSON Schema, there is a slight misunderstanding in what the meta schema of OAS is, which is basically JSON Schema…

I should point out that OAS itself is not defined using a JSON schema. An OpenAPI document (i.e. a description of an API, conforming to the OAS) takes the form of an object graph that can be partially described and validated using JSON Schema.

But the written specification is the authoritative source. Any “official” or unofficial JSON Schema describing the OAS itself is supplementary, not considered definitive.

…and what the concrete schema of the so defined APIs and types is, which is basically an applied customisation of JSON Schema which in turn is either more restrictive or even more extensible, as in vendor extensions. I sometimes also get confused with all the meta meta meta levels when defining a language or system.

Getting lost in the meta-levels is an occupational hazard. 😉

Therefore, when not specifying a type explicitly, OAS should consider the type for being a string. The user can then decide on how to handle the value of either parameter or property.

That would be a further break from JSON Schema. The OpenAPI TSC wants to explore convergence with a future draft of JSON Schema, such that Schema Object fully supports the syntax and semantics of JSON Schema. The overall consensus seems to be that this would be valuable, though I don’t think they’ve committed to this yet.

@bbqsrc,

When a user forgets to enter type, we now simply treat this as an error for the purpose of code generation as there is no meaningful step the generator can take without causing potentially worse effects by taking a guess based on the other fields.

We currently treat it as a warning in our editors, though again this is a bit of a divergence from the OAS standard, so we plan to make that warning configurable.

A particularly common form of this is a schema that omits type, but specifies properties. Strictly speaking, this does not mean that the value must be an object. It means that if the value is an object, and it includes any of those properties, the property values must conform to the corresponding property subschemas.

In reality, this construct almost always means that the user intends type: object, and I think it would be reasonable for a code generator to assume this, maybe with a validation: strict|lax config option to control that behavior.

There are lots of other cases where annotations like format, or assertions like maxLength or multipleOf can give a clue as to the intended type. And assuming type: string as the default might even be reasonable in some cases. Just be aware that any behaviors like this are out of strict conformance with the spec, and are prone to misinterpretation.