decoders and helper functions for handling JSON API compliant server payloads
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


elm-jsonapi decodes any JSON API compliant payload and provides helper functions for working with the results.

This library only provides base functionality for decoding payloads and working with the results. A more sophisticated wrapper which includes content negotation with servers can be found here.

JSON API specifies a format with which resources related to the document's primary resource(s) are "side-loaded" under a key called included. This library abstracts the structure of the document and reconstructs the resource graph for you; use the relatedResource and relatedResourceCollection functions to traverse the graph from any given resource to its related resources.

See the documentation at:


Decoding a Resource

import Http
import Json.Decode exposing ((:=))
import JsonApi
import JsonApi.Decode
import JsonApi.Resources
import JsonApi.Documents
import Task exposing (..)

type alias User =
  { username : String
  , email : String

userDecoder : Json.Decode.Decoder User
userDecoder =
  Json.Decode.object2 User
    ("username" := Json.Decode.string)
    ("email" := Json.Decode.string)

getUserResource : String -> Task Http.Error (JsonApi.Document)
getUserResource query =
    Http.get JsonApi.Decode.document ("" ++ query)

extractUsername : JsonApi.Document -> Result String User
extractUsername doc =
  JsonApi.Documents.primaryResource doc
    `Result.andThen` (JsonApi.Resources.attributes userDecoder)

Encoding a Client-generated Resource

import JsonApi.Encode as Encode
import JsonApi.Resources as Resource
import Json.Encode exposing (Value)

encodeLuke : Result String Value
encodeLuke = "jedi"
    |> Resources.withAttributes
        [ ( "first_name", string "Luke" )
        , ( "last_name", string "Skywalker" )
    |> Resources.withAttributes
        [ ( "home_planet", string "Tatooine" )
    |> Resources.withRelationship "father" { id = "vader", resourceType = "jedi" }
    |> Resources.withRelationship "sister" { id = "leia", resourceType = "princess" }
    |> Resources.withUuid "123e4567-e89b-12d3-a456-426655440000"
    |> Encode.clientResource

Known Issues

  • Links objects are unsupported. Links will only be captured if delivered as string values.
  • There is no dedicated type for Resource Identifiers. If your document's primary data is composed of Resource Identifiers, they will be represented as Resources without attributes or relationships.


elm-jsonapi is currently under development. I use and Github Issues to track new features and bugs. if there's a feature you'd like to see, please submit an issue!

if you'd like to contribute yourself, please reach out to me or submit a pull request for the relevant issue.

Stories in Ready