Comparison between Goa v1 vs. v3 about the design DSL
Tags: go, goadesign
Published: 2019-10-24 10:54:30

---
title: Comparison between Goa v1 vs. v3 about the design DSL
published: true
description: 
tags: #go #goadesign
---

This article compares Goa v1 and v3 design DSL.

| v1 | v3 |
| --- | --- |
| `API` | `API` |
| `APIKeySecurity` | `APIKeySecurity`<br>(`APIKey`)<br>(`APIKeyField`) |
| ~~`AccessCodeFlow`~~ (Obsolete) | - |
| `Action` | `Method` |
| ~~`ApplicationFlow`~~ (Obsolete) | - |
| `ArrayOf` | `ArrayOf` |
| `Attribute` | `Attribute` |
| `Attributes` | `Attributes` |
| [`BasePath`](#basepath) | `Path` |
| `BasicAuthSecurity` | `BasicAuthSecurity`<br>(`Password`)<br>(`PasswordField`)<br>(`Username`)<br>(`UsernameField`) |
| [`CONNECT`](#get_head_post_put_delete_connect_options_trace_patch) | `CONNECT` |
| `CanonicalActionName` | `CanonicalMethod` |
| `CollectionOf` | `CollectionOf` |
| [`Consumes`](#consumes_produces) | `Consumes` |
| `Contact` | `Contact` |
| `ContentType` | `ContentType` |
| ~~`Credentials`~~ (Moved to [goa.design/plugins/cors](https://godoc.org/goa.design/plugins/cors)) | - |
| [`DELETE`](#get_head_post_put_delete_connect_options_trace_patch) | `DELETE` |
| `Default` | `Default` |
| ~~`DefaultMedia`~~ (Obsolete) | - |
| `Description` | `Description` |
| `Docs` | `Docs` |
| `Email` | `Email` |
| `Enum` | `Enum` |
| `Example` | `Example`<br>(`Value`) |
| ~~`Expose`~~ (Moved to [goa.design/plugins/cors](https://godoc.org/goa.design/plugins/cors)) | - |
| `Files` | `Files` |
| [`Format`](#format) | `Format` |
| ~~`Function`~~ (Obsolete) | - |
| [`GET`](#get_head_post_put_delete_connect_options_trace_patch) | `GET` |
| [`HEAD`](#get_head_post_put_delete_connect_options_trace_patch) | `HEAD` |
| [`HashOf`](#hashof) | `MapOf` |
| `Header` | `Header` |
| [`Headers`](#headers) | `Headers` |
| [`Host`](#host_scheme) | `Host`<br>`Server`<br>`URI`<br>`Variable` |
| `ImplicitFlow` | `ImplicitFlow` |
| `JWTSecurity` | `JWTSecurity`<br>(`Token`)<br>(`TokenField`) |
| `License` | `License` |
| ~~`Link`~~ (Obsolete) | - |
| ~~`Links`~~ (Obsolete) | - |
| ~~`MaxAge`~~ (Moved to [goa.design/plugins/cors](https://godoc.org/goa.design/plugins/cors)) | - |
| `MaxLength` | `MaxLength` |
| `Maximum` | `Maximum` |
| `Media` | `Result` |
| `MediaType` | `ResultType` |
| ~~`Member`~~ (Obsolete) | - |
| `Metadata` | `Meta` |
| ~~`Methods`~~ (Moved to [goa.design/plugins/cors](https://godoc.org/goa.design/plugins/cors)) | - |
| `MinLength` | `MinLength` |
| `Minimum` | `Minimum` |
| `MultipartForm` | `MultipartRequest` |
| `Name` | `Name` |
| ~~[`NoExample`](#noexample)~~ (Obsolete) | - |
| `NoSecurity` | `NoSecurity` |
| `OAuth2Security ` | `OAuth2Security`<br>(`AccessToken`)<br>(`AccessTokenField`) |
| [`OPTIONS`](#get_head_post_put_delete_connect_options_trace_patch) | `OPTIONS` |
| ~~`OptionalPayload`~~ (Obsolete) | - |
| ~~`Origin`~~ (Moved to [goa.design/plugins/cors](https://godoc.org/goa.design/plugins/cors)) | - |
| [`PATCH`](#get_head_post_put_delete_connect_options_trace_patch) | `PATCH` |
| [`POST`](#get_head_post_put_delete_connect_options_trace_patch) | `POST` |
| [`PUT`](#get_head_post_put_delete_connect_options_trace_patch) | `PUT` |
| ~~`Package`~~ (Obsolete) | - |
| `Param` | `Param` |
| [`Params`](#params) | `Params` |
| `Parent` | `Parent` |
| `PasswordFlow` | `PasswordFlow` |
| `Pattern` | `Pattern` |
| `Payload` | `Payload` |
| [`Produces`](#consumes_produces) | `Produces` |
| ~~`Query`~~ (Obsolete) | - |
| ~~`ReadOnly`~~ (Obsolete) | - |
| `Reference` | `Reference` |
| `Required` | `Required` |
| `Resource` | `Service` |
| `Response` | `Response` |
| ~~`ResponseTemplate`~~ (Obsolete) | - |
| ~~[`Routing`](#routing)~~ (Obsolete) | - |
| ~~[`Scheme`](#host_scheme)~~ (Obsolete) | - |
| `Scope` | `Scope` |
| `Security` | `Security` |
| `Status` | `Code` |
| [`TRACE`](#get_head_post_put_delete_connect_options_trace_patch) | `TRACE` |
| `TermsOfService` | `TermsOfService` |
| `Title` | `Title` |
| ~~`TokenURL`~~ (Obsolete) | - |
| ~~`Trait`~~ (Obsolete) | - |
| `Type` | `Type` |
| `TypeName` | `TypeName` |
| `URL` | `URL` |
| ~~`UseTrait`~~ (Obsolete) | - |
| `Version` | `Version` |
| `View` | `View` |
| - | `AuthorizationCodeFlow` |
| - | `Body` |
| - | `ClientCredentialsFlow` |
| - | `ConvertTo` |
| - | `CreateFrom` |
| - | `Elem` |
| - | `Error` |
| - | `Extend` |
| - | `Fault` |
| - | `Field` |
| - | `GRPC` |
| - | `HTTP` |
| - | `Key` |
| - | `MapParams` |
| - | `Message` |
| - | `Metadata` |
| - | `Services` |
| - | `StreamingPayload` |
| - | `StreamingResult` |
| - | `Tag` |
| - | `Temporary` |
| - | `Timeout` |
| - | `Trailers` |

<a name="basepath"></a>
## `BasePath`

* Replaced with `Path`.
* Describe in `HTTP`.

```go
// v1
BasePath("/users")
```

```go
// v3
HTTP(func() {
	Path("/users")
})
```

<a name="consumes_produces"></a>
## `Consumes`, `Produces`

* Describe in `HTTP`.
* `Function` and `Package` are obsolete.

```go
// v1
Consumes("application/xml")
Consumes("application/json")
Produces("application/xml")
Produces("application/json")
```

```go
// v3
HTTP(func() {
	Consumes("application/xml")
	Consumes("application/json")
	Produces("application/xml")
	Produces("application/json")
})
```

<a name="format"></a>
## `Format`

* The argument type is `string` in v1. v3 uses `expr.ValidationFormat` instead.
* `expr.ValidationFormat`s are defined in `goa.design/goa/expr` as `const`.

<a name="get_head_post_put_delete_connect_options_trace_patch"></a>
## `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH`

* The path parameters are described using colon (`:`) in v1. v3 uses curly braces (`{`, `}`) instead.

```go
// v1
GET("/users/:id")
```

```go
// v3
GET("/users/{id}")
```

<a name="hashof"></a>
## `HashOf`

* Replaced with `MapOf`.
* Describe an optional DSL for the key using `Key`.
* Describe an optional DSL for the value using `Elem`.

```go
// v1
HashOf(String, Integer,
	func() {
		MinLength(1)
		MaxLength(16)
	},
	func() {
		Minimum(1)
		Maximum(5)
	},
)

// v3
MapOf(String, Int, func() {
	Key(func() {
		MinLength(1)
		MaxLength(16)
	})
	Elem(func () {
		Minimum(1)
		Maximum(5)
	})
})
```

<a name="headers"></a>
## `Headers`

### Request headers

* Describe `Attribute` in `Payload`, `Headers` in `HTTP`.

```go
// v1
Action("show", func() {
	Headers(func() {
		Header("Authorization", String)
	})
})
```

```go
// v3
Method("show", func() {
	Payload(func() {
		Attribute("Authorization", String)
	})
	HTTP(func() {
		Headers(func() {
			Header("Authorization", String)
		})
	})
})
```

<a name="host_scheme"></a>
## `Host`, `Scheme`

* `Host` and `Scheme` (and `BasePath`) are used in v1. v3 uses `Server`, `Host` and `URI` instead.

```go
// v1
Host("localhost:8080")
Scheme("http")
BasePath("/cellar")
```

```go
// v3
Server("app", func() {
	Host("development", func() {
		URI("http://localhost:8080/cellar")
	})
})
```

<a name="noexample"></a>
## `NoExample`

* Obsolete.
* `Meta` can be used as an alternative.

```go
Meta("swagger:example", "false")
```

<a name="params"></a>
## `Params`

### Path parameters

* Describe `Attribute` in `Payload`, `Params` in `HTTP`.
* `Params` can be omitted. It is implicitly defined.

```go
// v1
Action("show", func() {
	Params(func() {
		Param("id", Integer)
	})
})
```

```go
// v3
Method("show", func() {
	Payload(func() {
		Attribute("id", Int)
	})
	HTTP(func() {
		Params(func() {       // Can be omitted
			Param("id", Int)  //
		})                    //
	})
})
```

### Query parameters

* Describe `Attribute` in `Payload`, `Params` in `HTTP`.
* `Params` cannot be ommited.

```go
//v1
Action("list", func() {
	Params(func() {
		Param("name", String)
	})
})
```

```go
// v3
Method("list", func() {
	Payload(func() {
		Attribute("name", String)
	})
	HTTP(func() {
		Params(func() {            // Cannot be omitted
			Param("name", String)  //
		})                         //
	})
})
```

<a name="routing"></a>
## `Routing`

* Obsolete.
* Describe DSLs which have same name as HTTP request methods in `HTTP`.

```go
// v1
Action("show", func() {
	Routing(
		GET("/:id"),
	)
})
```

```go
// v3
Method("show", func() {
	HTTP(func() {
		GET("/{id}")
	})
})
```