Go Reference test golangci-lint


Package jsonapi implements a marshaler/unmarshaler for JSON:API v1.0.


Take a look at the go reference for more examples and detailed usage information.



type Article struct {
    ID    string `jsonapi:"primary,articles"`
    Title string `jsonapi:"attribute" json:"title"`

a := Article{ID: "1", Title:"Hello World"}

b, err := jsonapi.Marshal(&a)
if err != nil {
    // ...

fmt.Println("%s", string(b))
// {
//     "data": [
//         "id": "1",
//         "type": "articles",
//         "attributes": {
//             "title": "Hello World"
//         }
//     ]
// }



body := `{"data":[{"id":"1","type":"articles","attributes":{"title":"Hello World"}}]}`

type Article struct {
    ID    string `jsonapi:"primary,articles"`
    Title string `jsonapi:"attribute" json:"title"`

var a Article
if err := jsonapi.Unmarshal([]byte(body), &a); err != nil {
    // ...

fmt.Prints("%s, %s", a.ID, a.Title)
// "1", "Hello World"


The following information is well documented in the go reference. This section is included for a high-level overview of the features available.

Struct Tags

Like encoding/json jsonapi is primarily controlled by the presence of a struct tag jsonapi. The standard json tag is still used for naming and omitempty.

Tag Usage Description Alias
primary jsonapi:"primary,{type}" Defines the identification field. N/A
attribute jsonapi:"attribute" Defines an attribute. attr
relationship jsonapi:"relationship" Defines a relationship. rel
meta jsonapi:"meta" Defines a meta object. N/A

Functional Options

Both jsonapi.Marshal and jsonapi.Unmarshal take functional options.

Option Supports
jsonapi.MarshalOption meta, json:api, includes, document links, sparse fieldsets
jsonapi.UnmarshalOption meta

Non-String Identifiers

Identification MUST be represented as a string regardless of the actual type in Go. To support non-string types for the primary field you can implement optional interfaces.

Context Interface
Marshal fmt.Stringer
Marshal jsonapi.MarshalIdentifier
Unmarshal jsonapi.UnmarshalIdentifier


Links are supported via two interfaces and the Link type. To include links you must implement one or both of the following interfaces.

Type Interface
Resource Object Link Linkable
Resource Object Related Resource Link LinkableRelation



  • exposes an API that looks/feels a lot different than encoding/json
  • has quite a few bugs w/ complex types in attributes
  • doesn’t provide easy access to top-level fields like meta
  • allows users to generate invalid JSON:API
  • not actively maintained


  • has required interfaces
  • interfaces for includes/relationships are hard to understand and verbose to implement
  • allows users to generate invalid JSON:API
  • part of a broader api2go framework ecosystem


View Github