Implementation of JSON5.

json, json5, nim
nimble install samson



Samson is a library for serializing and deserializing JSON5, a superset of JSON. This library is still a work in progress and some features are missing.


The main API consists of only two procs: toJson5 and fromJson5.

Simple example

import samson

type User = object
    name: string
    age: range[0..high(int)]
    timezone: Option[string]

let input = """
    {"name": "John Doe", age: 25},
    {"name": "Jane Doe", age: 22, timezone: "Europe/Stockholm"}

let parsed = fromJson5(input, seq[User])
echo parsed
# => @[(name: "John Doe", age: 25, timezone: None[string]), (name: "Jane Doe", age: 22, timezone: Some("Europe/Stockholm"))]
echo toJson5(parsed)
# => [{"name": "John Doe", age: 25, timezone: null}, {"name": "Jane Doe", age: 22, timezone: "Europe/Stockholm"}]

Advanced example

Pragma annotations can be used to control how an object type is serialized and deserialized. These are defined and documented in the samson / pragmas module.

import std/times, samson, samson/pragmas

type Advanced = object
    nimField {.jsonFieldName: "jsonField".}: int
    hidden {.jsonExclude.}: int
    date {.jsonDateTimeFormat: "yyyy-MM-dd".}: DateTime

let x = Advanced(
    nimField: 1,
    hidden: 2,
    date: initDateTime(1, mJan, 2010, 12, 00, 00, utc())
echo toJson5(x)
# => {"jsonField": 1, date: "2010-01-01"}

Supported types

The following types in the standard library have special support in Samson:

  • int8, int16, int32, int, and int64
  • uint8, uint16, and uint32 (note: uint and uint64 are not supported for now)
  • float32 and float64
  • string
  • char
  • enum
  • seq
  • array
  • bool
  • range (with range checking)
  • options.Option (maps to null when empty)
  • times.Time
  • times.DateTime
  • tables.Table and tables.OrderedTable (maps to object)
  • set, sets.HashSet, and sets.OrderedSet

Samson also supports custom object (mapped to objects in JSON5) and tuple (mapped to arrays in JSON5) types.

Generated docs

Planned features

  • Stream based API.
  • Support for type variants.
  • Support for pretty printing.
  • Support for dynamic JSON.
  • A strict JSON mode which doesn't support JSON5 features.