Five things they didn't tell you were changing in OpenAPI 3.0.0-RC0

Articles like this one are excellent at setting out the major changes in the OpenAPI 3.0.0-RC0 implementor's draft. They normally come with this picture:

You can tell how excellent it is by how many times it's been copied and reposted, often without checking for errors such as "dataForm parameters" (it should of course be formData).

However, there are some surprises in store once you start digging further into the specification.

Even Marsh Gardiner's excellent talk doesn't touch on all of these points.

Here are five changes which may otherwise have passed you by...

1. Parameters don't have a type property any more

You read that right. We all know body and file parameters have gone, but more surprising is that the type property on an OpenAPI parameter has been removed, along with all of the following:

    'format',
    'minimum',
    'maximum',
    'exclusiveMinimum',
    'exclusiveMaximum',
    'minLength',
    'maxLength',
    'multipleOf',
    'items',
    'minItems',
    'maxItems',
    'uniqueItems',
    'additionalProperties',
    'pattern',
    'enum',
    'default'

Parameters are now by default untyped. They function as strings unless otherwise specified. Awaiting clarity on this, the specification is a little vague on this point.

You now need to declare a schema property to constrain a parameter to even a primitive type.

    "parameters" : [{
        "name" : "petId",
        "in" : "path",
        "description" : "ID of pet to return",
        "required" : true,
        "type" : "integer",
        "format" : "int64"
    }],

becomes

    "parameters": [{
        "name": "petId",
        "in": "path",
        "description": "ID of pet to return",
        "required": true,
        "schema": {
            "type": "integer",
            "format": "int64"
        }
    }],

Alternatively, a parameter may have a content property (mutually exclusive with schema) for example if a parameter was formatted as application/json.

Sounds like a bit of extra work? It is, but it gives the OpenAPI 3 specification more flexibility and consistency. Anything you can describe with a JSON schema can now be your type. Examples, defaults, formatting, array properties, all work exactly as you would define them in the schema of a requestBody or response. It's a big change, but one that I'm sure we'll all get used to quickly.

2. Headers don't have a type property any more

Ok, this is a bit of a cheat. As I said above, the OpenAPI 3 specification aims for consistency, and that's what we have here. To define a header's type other than an unformatted string, simply you must declare or reuse a schema or content object.

3. oAuth2 authentication now supports multiple flows

You'd be excused for missing this one too, as the securityScheme object has a property called flow, not flows. This is up for possibly changing in the specification, post RC0.

4. Terms of Service must now be a URL

This change fits in with the vast majority of real-world usage in Swagger / OpenAPI 2 definitions as far as I can see. I've only found one example of someone including additional text in this property.

From my experience however, almost anything parses as a valid URL, so you are likely to get past any validators which show up.

5. Rules on reusable component names

The rules have been tightened on what makes a valid name for a reusable component (i.e. what your names were under parameters, definitions and responses in Swagger / OpenAPI 2.0). Now only the characters A-Z, a-z, ., - and _ are valid.

Resources

It's very early days of course, but support for OpenAPI 3.0.0 isn't non-existent, even at the RC0 stage.

An unofficial list has been started to collect projects with support for the emerging standard.

Wrapping up

I hope you've found something useful in this post, but please don't hesitate to contact me via email or @permittedSoc on Twitter if I've missed anything.

Thanks to @webron for some early feedback on this post.