zon

README

ZON encoding/decoding for Go ⚡

zon is a Go library for marshaling and unmarshaling ZON data, similar in usage to encoding/json.

[!IMPORTANT] This library is not yet battle-tested; consider it more of an experiment :)

Features

• Marshal Go primitives and structs into ZON format
• Unmarshal ZON data into Go values
• Support for Encoder and Decoder
• Handles booleans, numbers, strings, slices, maps, and structs

Installation

go get -u github.com/peterhellberg/zon

Usage

Marshal / Unmarshal

package main

import (
	"fmt"

	"github.com/peterhellberg/zon"
)

type Example struct {
	Name string `zon:"name"`
	Age  int    `zon:"age"`
	List []int  `zon:"list"`
	Omit []int  `zon:"omit,omitempty"`
}

func main() {
	v := Example{Name: "Peter", Age: 42}

	if err := run(v); err != nil {
		panic(err)
	}
}

func run(v Example) error {
	data, err := zon.Marshal(v)
	if err != nil {
		return err
	}

	fmt.Println(string(data))
	// Output: .{.name = "Peter", .age = 42, .list = .{}}

	var v2 map[string]any

	if err := zon.Unmarshal(data, &v2); err != nil {
		return err
	}

	fmt.Printf("%+v\n", v2)
	// Output: map[age:42 list:[] name:Peter]

	return nil
}

Encoder / Decoder

package main

import (
	"bytes"
	"fmt"

	"github.com/peterhellberg/zon"
)

type Example struct {
	Name string `zon:"name"`
}

func main() {
	v := Example{Name: "Peter"}

	if err := run(v); err != nil {
		panic(err)
	}
}

func run(v Example) error {
	var buf bytes.Buffer

	if err := zon.NewEncoder(&buf).Encode(v); err != nil {
		return err
	}

	fmt.Println(buf.String())
	// Output: .{.name = "Peter"}

	var v2 Example

	if err := zon.NewDecoder(&buf).Decode(&v2); err != nil {
		return err
	}

	fmt.Printf("%+v\n", v2)
	// Output: {Name:Peter}

	return nil
}

[!TIP] As a slight convenience, there are zon.Encode and zon.Decode functions;

func run(v Example) error {
	var buf bytes.Buffer

	if err := zon.Encode(&buf, v); err != nil {
		return err
	}

	fmt.Println(buf.String())
	// Output: .{.name = "Peter"}

	var v2 Example

	if err := zon.Decode(&buf, &v2); err != nil {
		return err
	}

	fmt.Printf("%+v\n", v2)
	// Output: {Name:Peter}

	return nil
}

CLI

This library also comes with a small CLI called zon which can be used to convert between ZON and JSON.

$ go install https://github.com/peterhellberg/zon/cmd/zon@latest

JSON to ZON

$ echo '{"langs":["Zig", "Go"],"none":null}' | zon | zq

.{
    .langs = .{
        "Zig",
        "Go",
    },
    .none = null,
}

[!NOTE] zq in the example above is https://codeberg.org/tensorush/zq

ZON to JSON

$ cat testdata/build.zig.zon | zon -j | jq

{
  "dependencies": [],
  "fingerprint": 11089329437232087000,
  "minimum_zig_version": "0.16.0-dev.205+4c0127566",
  "name": "testdata",
  "paths": [
    "build.zig",
    "build.zig.zon",
    "src"
  ],
  "version": "0.0.0"
}

[!NOTE] jq in the example above is https://jqlang.org/

$ cat testdata/comments.zon | tee /dev/stderr | zon -j
// Comment before object
.{
    .field = "with a string", // Trailing comment

    // Comment between fields

    .another = .{
        .value = .{ "first", 2, false },
    },
}

{"another":{"value":["first",2,false]},"field":"with a string"}

License

MIT License

Copyright © 2025 Peter Hellberg - https://c7.se/

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Overview

Package zon provides serialization and deserialization of the ZON data format for Go values.

The package allows converting Go values to ZON and back, supporting basic types (bool, int, uint, float, string), slices, arrays, maps, structs, pointers, and interfaces.

Key features:

• Marshal, Unmarshal, Encode and Decode functions.
• Encoder and Decoder types.
• Support for struct field tags via `zon:"name"` to customize serialized field names.
• Map keys are automatically prefixed with a dot (`.`) unless already present.
• Pointers and interface values are handled transparently, with `nil` encoded as `null`.
• Graceful handling of unknown fields during struct deserialization.
• A simple syntax that uses `.`-prefixed field keys and `=` as a key-value separator.

Index

• func Decode(r io.Reader, v any) error
• func Encode(w io.Writer, v any) error
• func Marshal(v any) ([]byte, error)
• func Unmarshal(data []byte, v any) error
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v any) error
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Encode(v any) error

Functions

func Decode

func Decode(r io.Reader, v any) error

func Encode

func Encode(w io.Writer, v any) error

func Marshal

func Marshal(v any) ([]byte, error)

func Unmarshal

func Unmarshal(data []byte, v any) error

Unmarshal parses the data into the value pointed to by v. v must be a non-nil pointer.

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

func (*Decoder) Decode

func (d *Decoder) Decode(v any) error

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

func (*Encoder) Encode

func (e *Encoder) Encode(v any) error