jsony - SKILL.md Agent Skill

name: jsony description: Fast JSON parsing and serialization for Nim with automatic derived hooks license: MIT compatibility: opencode metadata: audience: developers workflow: data-parsing

What I do

jsony is a high-performance JSON library for Nim that provides:

Automatic derivation of JSON parsers/serializers for custom types
Customizable hooks for fine-grained control (parseHook, dumpHook, renameHook, etc.)
Zero-copy parsing where possible
No external dependencies

When to use me

Use jsony when you need to:

Parse JSON into Nim types (objects, seqs, arrays, tables, enums, tuples)
Serialize Nim types to JSON
Handle nested or complex JSON structures
Customize field names, default values, or validation

Basic usage

Parsing JSON into types

import pkg/jsony

type MyObject = object
  name: string
  value: int

let json_str = """{"name": "test", "value": 42}"""
let obj = json_str.fromJson(MyObject)

Serializing types to JSON

let obj = MyObject(name: "test", value: 42)
let json_str = obj.toJson()

Supported types

seq[T] - Parses JSON arrays into sequences
array[N, T] - Fixed-size arrays
object - JSON objects map to object fields
ref object - Pointer types
enum - String or integer enum values
tuple - Named or unnamed tuples
Table[K, V] / OrderedTable - JSON objects
set[T] / HashSet - JSON arrays
Option[T] - Nullable values (null maps to none)
bool, int, float, string, char - Primitives
JsonNode - Raw JSON parsing

Custom hooks for fine-grained control

renameHook - Map JSON keys to different field names

proc renameHook*(v: var MyObject, key: string) =
  if key == "my_name":
    key = "name"

enumHook - Custom enum parsing

proc enumHook*(strVal: string, v: var MyEnum) =
  if strVal == "ACTIVE":
    v = MyEnum.active

newHook - Initialize fields with defaults

proc newHook*(v: var MyObject) =
  v.value = 100  # Default value

postHook - Validate after parsing

proc postHook*(v: var MyObject) =
  if v.value < 0:
    raise newException(ValueError, "Value must be positive")

skipHook - Skip specific fields during parsing

proc skipHook*(T: typedesc[MyObject], key: string): bool =
  key == "internal_field"  # Skip this field

Example from Constantine tests

From t_ethereum_bls_signatures.nim and t_ethereum_evm_precompiles.nim:

import pkg/jsony

type
  PubkeyField = object
    pubkey: array[48, byte]
  DeserG1_test = object
    input: PubkeyField
    output: bool

# Custom parsing for byte arrays from hex strings
proc parseHook*[N: static int](src: string, pos: var int, value: var array[N, byte]) =
  var str: string
  parseHook(src, pos, str)
  value.paddedFromHex(str, bigEndian)

# Parse test vectors
let testFile = readFile(testDir / filename)
let testData = testFile.fromJson(DeserG1_test)

# Use parsed data
let status = pubkey.deserialize_pubkey_compressed(testData.input.pubkey)

Dealing with extra JSON fields

By default, jsony ignores unknown fields:

fromJson[T]() ignores extra JSON fields
Missing fields keep their default values (use newHook to set defaults)

Performance tips

For large JSON, use parseHook instead of generic parsing
distinct types automatically derive serialization
Compile with -d:release for optimized parsing

Error handling

try:
  let obj = json_str.fromJson(MyObject)
except JsonError as e:
  echo "JSON parse error: ", e.msg

Recursive parseHook - Nested complex structures

From t_hash_to_curve.nim and t_ec_sage_template.nim:

type
  EC_G1_hex = object
    x: string
    y: string

  EC_G2_hex = object
    x: Fp2_hex  # Nested object
    y: Fp2_hex

  Fp2_hex = object
    c0: string
    c1: string

  TestVector[EC: EC_ShortW_Aff] = object
    P: EC          # Recursive generic type
    Q0, Q1: EC
    msg: string
    u: seq[string]

  HashToCurveTest[EC: EC_ShortW_Aff] = object
    L, Z, dst: string
    curve: string
    field: FieldDesc
    vectors: seq[TestVector[EC]]

# Recursive parseHook for elliptic curve points
proc parseHook*(src: string, pos: var int, value: var EC_ShortW_Aff) =
  when EC_ShortW_Aff.F is Fp:
    var P: EC_G1_hex
    parseHook(src, pos, P)           # Recursive call
    let ok = value.fromHex(P.x, P.y)
  elif EC_ShortW_Aff.F is Fp2:
    var P: EC_G2_hex
    parseHook(src, pos, P)           # Recursive call
    let ok = value.fromHex(P.x.c0, P.x.c1, P.y.c0, P.y.c1)

# Generic bigint parsing
proc parseHook*(src: string, pos: var int, value: var BigInt) =
  var str: string
  parseHook(src, pos, str)           # Parse string first
  value.fromHex(str)                 # Then convert

# Usage with generic test vectors
let vec = loadVectors(HashToCurveTest[EC_ShortW_Aff[Fp[BLS12_381], G1]], filename)

for i in 0 ..< vec.vectors.len:
  var P: EC
  P.fromAffine(vec.vectors[i].P)     # Nested parsing

Working with conditional fields and generics

From t_ec_sage_template.nim:

type
  ScalarMulTestG2[EC: EC_ShortW_Aff, bits: static int] = object
    curve, group, modulus: string
    # Conditional fields based on generic parameter
    when EC.F is Fp:
      non_residue_twist: int
    else:
      non_residue_twist: array[2, int]
    vectors: seq[TestVector[EC, bits]]

# Load vectors with generic type
proc loadVectors(TestType: typedesc): TestType =
  const group = when TestType.EC.G == G1: "G1" else: "G2"
  const filename = "tv_" & $TestType.EC.F.Name & "_scalar_mul_" & group & "_" & $TestType.bits & "bit.json"
  let content = readFile(TestVectorsDir/filename)
  result = content.fromJson(TestType)

# Usage
let vec = loadVectors(ScalarMulTestG2[EC_ShortW_Aff[Fp2[BLS12_381], G2], 256])

Advanced patterns

Static if/when in hooks

proc parseHook*(src: string, pos: var int, value: var MyGeneric[T]) =
  when T is SomeNumber:
    # Parse numeric type
    var num: T
    parseHook(src, pos, num)
    value = MyGeneric[T](data: num)
  elif T is string:
    # Parse string type
    var str: string
    parseHook(src, pos, str)
    value = MyGeneric[T](data: str)

Multiple dispatch with static parameters

proc parseHook*[EC: static typedesc](src: string, pos: var int, value: var EC) =
  # Static dispatch based on EC type
  when EC.G == G1:
    var P: EC_G1_hex
    parseHook(src, pos, P)
    discard value.fromHex(P.x, P.y)
  else: # EC.G == G2
    var P: EC_G2_hex
    parseHook(src, pos, P)
    discard value.fromHex(P.x.c0, P.x.c1, P.y.c0, P.y.c1)

Integration with other code

jsony works seamlessly with:

Standard library types (tables, sets, options)
Custom serialization libraries (via parseHook/dumpHook)
Test frameworks for parsing test vectors
FFI code for parsing C/interop data structures
Generic parameterized types and static dispatch