Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit 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:

Elm Version

This module is compatible with Elm 0.19.x. It can be tested with elm-test 0.18.2


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


decoders and helper functions for handling JSON API compliant server payloads







No packages published