https://github.com/lpil/json-typedef

Work with JSON using a schema! RFC8927
https://github.com/lpil/json-typedef

Last synced: 23 days ago
JSON representation

Work with JSON using a schema! RFC8927

• Host: GitHub
• URL: https://github.com/lpil/json-typedef
• Owner: lpil
• Created: 2024-09-05T12:19:26.000Z (5 months ago)
• Default Branch: main
• Last Pushed: 2025-01-10T11:18:27.000Z (about 1 month ago)
• Last Synced: 2025-01-19T10:12:49.872Z (26 days ago)
• Language: Gleam
• Homepage: https://jsontypedef.com/
• Size: 105 KB
• Stars: 41
• Watchers: 2
• Forks: 7
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md

Awesome Lists containing this project

• awesome-gleam - json_typedef - [📚](https://hexdocs.pm/json_typedef/) - Work with JSON using a schema! RFC8927 (Packages / JSON)

README

        
# json_typedef

Work with JSON using a schema! 

[![Package Version](https://img.shields.io/hexpm/v/json_typedef)](https://hex.pm/packages/json_typedef)

[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/json_typedef/)

JSON-Typedef is an easy-to-learn, portable, and standardized way to describe the

shape of your JSON data. This library provides encoders and decoders for the

JSON-Typedef schema format, and can generate Gleam encoders and decoders for a

given schema.

- [JSON-Typedef website](https://jsontypedef.com/)

- [RFC8927](https://datatracker.ietf.org/doc/html/rfc8927)

For example, if you have this JSON-Typedef schema:

```json

{

  "properties": {

    "id": { "type": "string" },

    "createdAt": { "type": "timestamp" },

    "karma": { "type": "int32" },

    "isAdmin": { "type": "boolean" }

  }

}

```

Then you can use this package to generate this Gleam source code:

```gleam

import decode

import gleam/json

pub type Data {

  Data(

    created_at: String,

    id: String,

    is_admin: Bool,

    karma: Int,

  )

}

pub fn data_decoder() -> decode.Decoder(Data) {

  decode.into({

    use created_at <- decode.parameter

    use id <- decode.parameter

    use is_admin <- decode.parameter

    use karma <- decode.parameter

    Data(created_at:, id:, is_admin:, karma:)

  })

  |> decode.field("createdAt", decode.string)

  |> decode.field("id", decode.string)

  |> decode.field("isAdmin", decode.bool)

  |> decode.field("karma", decode.int)

}

pub fn data_to_json(data: Data) -> json.Json {

  json.object([

    #("createdAt", json.string(data.created_at)),

    #("id", json.string(data.id)),

    #("isAdmin", json.bool(data.is_admin)),

    #("karma", json.int(data.karma)),

  ])

}

```

## Usage

Everything starts with a string representation of your schema written using the 

[JSON Type Definition Format](https://jsontypedef.com/docs/jtd-in-5-minutes/)

```gleam

let json_schema =

    "{

  \"properties\": {

    \"id\": { \"type\": \"string\" },

    \"createdAt\": { \"type\": \"timestamp\" },

    \"karma\": { \"type\": \"int32\" },

    \"isAdmin\": { \"type\": \"boolean\" }

  }

}"

```

Then you'll need to use the

[gleam/json module](https://hexdocs.pm/gleam_json/gleam/json.html)'s

[decode function](https://hexdocs.pm/gleam_json/gleam/json.html#decode) to

convert your string representation into a usable

[RootSchema](https://hexdocs.pm/json_typedef/json_typedef.html#RootSchema) type

like this:

```gleam

import gleam/json

import json_typedef

let assert Ok(root_schema) = json.decode(json_schema, json_typedef.decoder)

```

Once you have your `root_schema` you can then generate your encoders and or

decoders! That can be achieved like this:

```gleam

json_typedef.codegen()

|> json_typedef.generate_decoders(True)

|> json_typedef.generate_encoders(True)

|> json_typedef.generate(root_schema)

```

you can then save the `Ok(String)` value to a file and use the generated code to

decode and encode any future pieces of json that satisfy your schema.

Further documentation can be found at .