This is an alternative site for discovering Elm packages. You may be looking for the official Elm package site instead.
Decoders and helper functions for working with JSONAPI payloads
version 2.2.2
license BSD3
native-modules False
elm-version 0.18.0 <= v < 0.19.0
Tag 2.2.2
Committed At 2018-10-02 20:31:51 UTC
elm-lang/core 5.0.0 <= v < 6.0.0 5.1.1
elm-community/list-extra 5.0.0 <= v < 8.0.0 7.1.0
elm-community/json-extra 2.0.0 <= v < 3.0.0 2.7.0
danyx23/elm-uuid 2.0.2 <= v < 3.0.0 2.1.2
NoRedInk/elm-decode-pipeline 3.0.0 <= v < 4.0.0 3.0.1
Fresheyeball/elm-tuple-extra 3.0.0 <= v < 4.0.0 3.0.0



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 can be used with elm 0.18.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