Generates Elm types, JSON decoders, JSON encoders and fuzz tests from JSON schema specifications
Branch: master
Clone or download
dragonwasrobot Updates generated code to Elm 0.19 (#74)
* Updates generated code to Elm 0.19

Now generates Elm 0.19 code, without any option for generating
backwards compatible Elm 0.18 code.

In the process, some dependencies and the README have been updated.
Latest commit bb37100 Dec 2, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config Fuzzers (#69) Jul 9, 2018
examples
lib Updates generated code to Elm 0.19 (#74) Dec 2, 2018
priv/templates Updates generated code to Elm 0.19 (#74) Dec 2, 2018
test Updates generated code to Elm 0.19 (#74) Dec 2, 2018
.formatter.exs
.gitignore Fuzzers (#69) Jul 9, 2018
.tool-versions Updates generated code to Elm 0.19 (#74) Dec 2, 2018
CONTRIBUTING.md Printers review (#66) Apr 29, 2018
LICENSE Initial commit Mar 5, 2017
README.md Updates generated code to Elm 0.19 (#74) Dec 2, 2018
coveralls.json Splits the parser and printing into separate repos (#72) Jul 27, 2018
mix.exs Updates generated code to Elm 0.19 (#74) Dec 2, 2018
mix.lock

README.md

JSON schema to Elm

Generates Elm types, JSON decoders, JSON encoders, and Fuzz tests from JSON schema specifications.

Installation

This project requires that you already have elixir and its build tool mix installed, this can be done with brew install elixir or similar.

  • Download latest release at: https://github.com/dragonwasrobot/json-schema-to-elm/releases, or
  • clone this repository: git clone git@github.com:dragonwasrobot/json-schema-to-elm.git, then
  • build an executable: MIX_ENV=prod mix build, and
  • rune the executable, js2e, that has now been created in your current working directory.

Usage

Run ./js2e for usage instructions.

Note: The js2e tool only tries to resolve references for the file(s) you pass it. So if you need to generate Elm code from more than one file you have to pass it the enclosing directory of the relevant JSON schema files, in order for it to be able to resolve the references correctly.

A proper description of which properties are mandatory and how the generator works is still in progress, but feel free to take a look at the examples folder which contains an example of a pair of JSON schemas and their corresponding Elm output. Likewise, representations of each of the different JSON schema types are described in the lib/types folder.

Example

If we supply js2e with the following JSON schema file, definitions.json:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Definitions",
    "id": "http://example.com/definitions.json",
    "description": "Schema for common types",
    "definitions": {
        "color": {
            "id": "#color",
            "type": "string",
            "enum": [ "red", "yellow", "green", "blue" ]
        },
        "point": {
            "id": "#point",
            "type": "object",
            "properties": {
                "x": {
                    "type": "number"
                },
                "y": {
                    "type": "number"
                }
            },
            "required": [ "x", "y" ]
        }
    }
}

it produces the following Elm file, Data/Definitions.elm:

module Data.Definitions exposing
    ( Color(..)
    , Point
    , colorDecoder
    , encodeColor
    , encodePoint
    , pointDecoder
    )

-- Schema for common types

import Data.Utils
    exposing
        ( encodeNestedOptional
        , encodeNestedRequired
        , encodeOptional
        , encodeRequired
        )
import Json.Decode as Decode
    exposing
        ( Decoder
        , andThen
        , at
        , fail
        , field
        , index
        , map
        , maybe
        , nullable
        , oneOf
        , succeed
        )
import Json.Decode.Pipeline
    exposing
        ( custom
        , optional
        , required
        )
import Json.Encode as Encode
    exposing
        ( Value
        , list
        , object
        )


type Color
    = Red
    | Yellow
    | Green
    | Blue


type alias Point =
    { x : Float
    , y : Float
    }


colorDecoder : Decoder Color
colorDecoder =
    Decode.string
        |> andThen
            (\color ->
                case color of
                    "red" ->
                        succeed Red

                    "yellow" ->
                        succeed Yellow

                    "green" ->
                        succeed Green

                    "blue" ->
                        succeed Blue

                    _ ->
                        fail <| "Unknown color type: " ++ color
            )


pointDecoder : Decoder Point
pointDecoder =
    succeed Point
        |> required "x" Decode.float
        |> required "y" Decode.float


encodeColor : Color -> Value
encodeColor color =
    case color of
        Red ->
            Encode.string "red"

        Yellow ->
            Encode.string "yellow"

        Green ->
            Encode.string "green"

        Blue ->
            Encode.string "blue"


encodePoint : Point -> Value
encodePoint point =
    []
        |> encodeRequired "x" point.x Encode.float
        |> encodeRequired "y" point.y Encode.float
        |> Encode.object

which contains an Elm type for the color and point definitions along with their corresponding JSON decoders and encoders.

Furthermore, if we instead supply js2e with a directory of JSON schema files that have references across files, e.g.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Circle",
    "id": "http://example.com/circle.json",
    "description": "Schema for a circle shape",
    "type": "object",
    "properties": {
        "center": {
            "$ref": "http://example.com/definitions.json#point"
        },
        "radius": {
            "type": "number"
        },
        "color": {
            "$ref": "http://example.com/definitions.json#color"
        }
    },
    "required": ["center", "radius"]
}

then the corresponding Elm file, Data/Circle.elm, will import the definitions (types, encoders and decoders) from the other Elm module, Data/Definitions.elm.

module Data.Circle exposing
    ( Circle
    , circleDecoder
    , encodeCircle
    )

-- Schema for a circle shape

import Data.Definitions as Definitions
import Data.Utils
    exposing
        ( encodeNestedOptional
        , encodeNestedRequired
        , encodeOptional
        , encodeRequired
        )
import Json.Decode as Decode
    exposing
        ( Decoder
        , andThen
        , at
        , fail
        , field
        , index
        , map
        , maybe
        , nullable
        , oneOf
        , succeed
        )
import Json.Decode.Pipeline
    exposing
        ( custom
        , optional
        , required
        )
import Json.Encode as Encode
    exposing
        ( Value
        , list
        , object
        )


type alias Circle =
    { center : Definitions.Point
    , color : Maybe Definitions.Color
    , radius : Float
    }


circleDecoder : Decoder Circle
circleDecoder =
    succeed Circle
        |> required "center" Definitions.pointDecoder
        |> optional "color" (nullable Definitions.colorDecoder) Nothing
        |> required "radius" Decode.float


encodeCircle : Circle -> Value
encodeCircle circle =
    []
        |> encodeRequired "center" circle.center Definitions.encodePoint
        |> encodeOptional "color" circle.color Definitions.encodeColor
        |> encodeRequired "radius" circle.radius Encode.float
        |> Encode.object

Furthermore, js2e also generates test files for the generated decoders and encoders to make the generated code immediately testable. The generated test files fuzzes instances of a given Elm type and tests that encoding it as JSON and decoding it back into Elm returns the original instance of that generated Elm type. In the above case, the following test files, tests/Data/CircleTests.elm and tests/Data/DefinitionsTests.elm, are generated:

module Data.CircleTests exposing
    ( circleFuzzer
    , encodeDecodeCircleTest
    )


-- Tests: Schema for a circle shape

import Data.Circle exposing (..)
import Data.DefinitionsTests as Definitions
import Expect exposing (Expectation)
import Fuzz exposing (Fuzzer)
import Json.Decode as Decode
import Test exposing (..)


circleFuzzer : Fuzzer Circle
circleFuzzer =
    Fuzz.map3
        Circle
        Definitions.pointFuzzer
        (Fuzz.maybe Definitions.colorFuzzer)
        Fuzz.float


encodeDecodeCircleTest : Test
encodeDecodeCircleTest =
    fuzz circleFuzzer "can encode and decode Circle object" <|
        \circle ->
            circle
                |> encodeCircle
                |> Decode.decodeValue circleDecoder
                |> Expect.equal (Ok circle)

and

module Data.DefinitionsTests exposing
    ( colorFuzzer
    , encodeDecodeColorTest
    , encodeDecodePointTest
    , pointFuzzer
    )

-- Tests: Schema for common types

import Data.Definitions exposing (..)
import Expect exposing (Expectation)
import Fuzz exposing (Fuzzer)
import Json.Decode as Decode
import Test exposing (..)


colorFuzzer : Fuzzer Color
colorFuzzer =
    Fuzz.oneOf
        [ Fuzz.constant Red
        , Fuzz.constant Yellow
        , Fuzz.constant Green
        , Fuzz.constant Blue
        ]


encodeDecodeColorTest : Test
encodeDecodeColorTest =
    fuzz colorFuzzer "can encode and decode Color object" <|
        \color ->
            color
                |> encodeColor
                |> Decode.decodeValue colorDecoder
                |> Expect.equal (Ok color)


pointFuzzer : Fuzzer Point
pointFuzzer =
    Fuzz.map2
        Point
        Fuzz.float
        Fuzz.float


encodeDecodePointTest : Test
encodeDecodePointTest =
    fuzz pointFuzzer "can encode and decode Point object" <|
        \point ->
            point
                |> encodePoint
                |> Decode.decodeValue pointDecoder
                |> Expect.equal (Ok point)

Finally, js2e also generates package config files, package.json and elm.json, and a .tool-versions file, making it easy to test that the generated Elm code is behaving as expected. Note that the .tool-versions file is not a file required by elm nor elm-test but instead a file used by the asdf version manager, https://github.com/asdf-vm/asdf, to install and run the correct compiler versions of node and elm specified in the .tool-versions file for a given project.

Thus, if we supply the following directory structure to js2e in the above case:

.
└── js2e_input/
    ├── definitions.json
    └── circle.json

the following new directory structure is generated:

.
└── js2e_output/
    ├── .tool-versions
    ├── package.json
    ├── elm.json
    ├── tests/
    │   └── Data/
    │       ├── Circle.elm
    │       └── Definitions.elm
    └── tests/
        └── Data/
            ├── CircleTests.elm
            └── DefinitionsTests.elm

containing the files described above along with the needed package config files to compile and run the tests.

Error reporting

Any errors encountered by the js2e tool while parsing the JSON schema files or printing the Elm code output, is reported in an Elm-like style, e.g.

--- UNKNOWN NODE TYPE -------------------------------------- all_of_example.json

The value of "type" at '#/allOf/0/properties/description' did not match a known node type

    "type": "strink"
            ^^^^^^^^

Was expecting one of the following types

    ["null", "boolean", "object", "array", "number", "integer", "string"]

Hint: See the specification section 6.25. "Validation keywords - type"
<http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.25>

or

--- UNRESOLVED REFERENCE ----------------------------------- all_of_example.json


The following reference at `#/allOf/0/color` could not be resolved

    "$ref": #/definitions/kolor
            ^^^^^^^^^^^^^^^^^^^


Hint: See the specification section 9. "Base URI and dereferencing"
<http://json-schema.org/latest/json-schema-core.html#rfc.section.9>

If you encounter an error while using js2e that does not mimic the above Elm-like style, but instead looks like an Elixir stacktrace, please report this as a bug by opening an issue and includin a JSON schema example that recreates the error.

Contributing

If you feel like something is missing/wrong or if I've misinterpreted the JSON schema spec, feel free to open an issue so we can discuss a solution. Note that the JSON schema parser has been moved to the new project, https://github.com/dragonwasrobot/json_schema, so this repo only implements the Elm code generators.

Please consult CONTRIBUTING.md first before opening an issue.