Json.Decode.Pipeline

JSON

Json.Decode.Pipeline

Use the (|>) operator to build JSON decoders.

Adapted from NoRedInk/elm-json-decode-pipeline 1.0.1 (BSD-3-Clause; see NOTICE).

Decoding fields

@docs required, requiredAt, optional, optionalAt, hardcoded, custom

Ending pipelines

@docs resolve

Values

required

required : String -> Decoder a -> Decoder (a -> b) -> Decoder b

Decode a required field.

Examples

import Json.Decode as Decode exposing (Decoder, int, string)
import Json.Decode.Pipeline exposing (required)

type alias User =
    { id : Int
    , name : String
    , email : String
    }

userDecoder : Decoder User
userDecoder =
    Decode.succeed User
        |> required "id" int
        |> required "name" string
        |> required "email" string

result : Result String User
result =
    Decode.decodeString
        userDecoder
        """
      {"id": 123, "email": "sam@example.com", "name": "Sam"}
    """

-- Ok { id = 123, name = "Sam", email = "sam@example.com" }

requiredAt

requiredAt : List String -> Decoder a -> Decoder (a -> b) -> Decoder b

Decode a required nested field.

optional

optional : String -> Decoder a -> a -> Decoder (a -> b) -> Decoder b

Decode a field that may be missing or have a null value. If the field is missing, then it decodes as the fallback value. If the field is present, then valDecoder is used to decode its value. If valDecoder fails on a null value, then the fallback is used as if the field were missing entirely.

Examples

import Json.Decode as Decode exposing (Decoder, int, null, oneOf, string)
import Json.Decode.Pipeline exposing (optional, required)

type alias User =
    { id : Int
    , name : String
    , email : String
    }

userDecoder : Decoder User
userDecoder =
    Decode.succeed User
        |> required "id" int
        |> optional "name" string "blah"
        |> required "email" string

result : Result String User
result =
    Decode.decodeString
        userDecoder
        """
      {"id": 123, "email": "sam@example.com" }
    """

-- Ok { id = 123, name = "blah", email = "sam@example.com" }

Because valDecoder is given an opportunity to decode null values before resorting to the fallback, you can distinguish between missing and null values if you need to:

userDecoder2 =
    Decode.succeed User
        |> required "id" int
        |> optional "name" (oneOf [ string, null "NULL" ]) "MISSING"
        |> required "email" string

optionalAt

optionalAt : List String -> Decoder a -> a -> Decoder (a -> b) -> Decoder b

Decode an optional nested field.

hardcoded

hardcoded : a -> Decoder (a -> b) -> Decoder b

Rather than decoding anything, use a fixed value for the next step in the pipeline. hardcoded does not look at the JSON at all.

Examples

import Json.Decode as Decode exposing (Decoder, int, string)
import Json.Decode.Pipeline exposing (required)

type alias User =
    { id : Int
    , email : String
    , followers : Int
    }

userDecoder : Decoder User
userDecoder =
    Decode.succeed User
        |> required "id" int
        |> required "email" string
        |> hardcoded 0

result : Result String User
result =
    Decode.decodeString
        userDecoder
        """
      {"id": 123, "email": "sam@example.com"}
    """

-- Ok { id = 123, email = "sam@example.com", followers = 0 }

custom

custom : Decoder a -> Decoder (a -> b) -> Decoder b

Run the given decoder and feed its result into the pipeline at this point.

Examples

import Json.Decode as Decode exposing (Decoder, at, int, string)
import Json.Decode.Pipeline exposing (custom, required)

type alias User =
    { id : Int
    , name : String
    , email : String
    }

userDecoder : Decoder User
userDecoder =
    Decode.succeed User
        |> required "id" int
        |> custom (at [ "profile", "name" ] string)
        |> required "email" string

result : Result String User
result =
    Decode.decodeString
        userDecoder
        """
      {
        "id": 123,
        "email": "sam@example.com",
        "profile": {"name": "Sam"}
      }
    """

-- Ok { id = 123, name = "Sam", email = "sam@example.com" }

resolve

resolve : Decoder (Decoder a) -> Decoder a

Convert a Decoder (Decoder a) into a Decoder a. Useful when you want to perform some custom processing just before completing the decoding operation.

Examples

import Json.Decode as Decode exposing (Decoder, float, int, string)
import Json.Decode.Pipeline exposing (required, resolve)

type alias User =
    { id : Int
    , email : String
    }

userDecoder : Decoder User
userDecoder =
    let
        toDecoder : Int -> String -> Int -> Decoder User
        toDecoder id email version =
            if version > 2 then
                Decode.succeed (User id email)

            else
                Decode.fail "This JSON is from a deprecated source. Please upgrade!"
    in
    Decode.succeed toDecoder
        |> required "id" int
        |> required "email" string
        |> required "version" int
        |> resolve