Five things they didn't tell you were changing in OpenAPI 3.0.0-RC0
Tags: openapi, swagger, openapi3, api
Published: 2017-04-06 09:49:10

---
title: Five things they didn't tell you were changing in OpenAPI 3.0.0-RC0 
published: true
description: Diving deeper into the next version of the OpenAPI (Swagger) spec
cover_image:
tags: 
  - openapi
  - swagger
  - openapi3
  - api
---
Articles like [this one](https://dzone.com/articles/what-you-need-to-know-about-oas-30) are excellent at setting out the major changes in the OpenAPI 3.0.0-RC0 implementor's draft. They normally come with this picture:

![OpenAPI3 structure](https://www.openapis.org/wp-content/uploads/2017/03/image00-1-768x539.png)

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](https://youtu.be/4lBMQteMd6Y) 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:

```javascript
	'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.

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

becomes

```json
	"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](https://github.com/OAI/OpenAPI-Specification/issues/967) 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](https://github.com/APIs-guru/openapi-directory/blob/master/APIs/bigoven.com/partner/swagger.yaml#L7) 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](https://github.com/mermade/swagger2openapi) 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](https://github.com/mermade/awesome-openapi3) 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](mailto:mike.ralphson@gmail.com) or @permittedSoc on Twitter if I've missed anything.

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