version 3.0: additional formats

As there are several issues proposing new formats, here a list of the possible future full picture

Common Name	Type	Format	Comments
octet/(unsigned) byte	integer	uint8	new: unsigned 8 bits
signed byte	integer	int8	new: signed 8 bits
short	integer	int16	new: signed 16 bits
integer	integer	int32	signed 32 bits
long	integer	int64	signed 64 bits
big integer	integer
float/single	number	float
double	number	double
decimal	number	decimal	new: decimal floating-point number, recipient-side internal representation as a binary floating-point number may lead to rounding errors
big decimal	number
string	string
byte	string	byte	base64 encoded characters
url-safe binary	string	base64url	new: base64url encoded characters - #606
binary	string	binary	any sequence of octets
boolean	boolean
date	string	date	As defined by full-date - RFC3339
dateTime	string	date-time	As defined by date-time - RFC3339
time (of day)	string	time	new: As defined by partial-time - RFC3339 - #358
duration	string	duration	new: As defined by xs:dayTimeDuration - XML Schema 1.1 - #359
uuid	string	uuid	new: Universally Unique Identifier (UUID) RFC4122
password	string	password	Used to hint UIs the input needs to be obscured.

[fehguy]

@whitlockjc yes, and with a fallback to primitive types, if not supported. I don’t think we should be inventing types.

In general, if we specify a format, we should dictate exactly what that is supposed to be. If a user expects a different behavior from a defined format, well, that violates the spec.

So… to make this concrete:

type: string
format: uuid

Should have a very specific format defined in the spec, specifically what @DavidBiesack mentioned:

uuid = 8HEXDIG "-" 4HEXDIG "-" 4HEXDIG "-" 4HEXDIG "-" 12HEXDIG

type: string
format: date-time

quite specifically says RFC3339 format (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types)

If I want to invent tonys-date-time then pretty much no tools will know what the heck to do with it, and would fall back to type: string.

[fehguy]

It seems that type must be a constrained type. format can be interpreted by the codegeneration. for example:

type: string
format: uuid

may fall back to String if UUID is not supported. But you cannot invent a type.

If that’s not the mentality, then we must constrain all formats to a fixed set, which may be hard to support inside the OAI.