GLYPH Format

GLYPH is a token-efficient serialization format designed for AI agents. It eliminates JSON’s redundant syntax while maintaining human readability.

Core Syntax

Scalars

GLYPH supports six primitive types:

_        // Preferred
∅        // Unicode alternative (input only)

GLYPH uses _ for null (not null), t/f for booleans (not true/false), and allows bare strings when safe.

Collections

Lists
Maps
Structs

Lists use space-separated elements:

[]                    // Empty
[1 2 3]              // Numbers
[_ t 42 hello]       // Mixed types
[[1 2] [3 4] [5 6]]  // Nested

No commas between elements

Maps use = and sorted keys:

{}                           // Empty
{a=1}                       // Single entry
{name=Alice age=30 active=t} // Multiple fields
{x={y={z=42}}}              // Nested

Keys are always sorted by UTF-8 byte order

Structs have type names:

User{name=Alice age=30}
Point{x=10 y=20}
Result{status=success data=[1 2 3]}

Structs enable schema validation.

JSON vs GLYPH

Here’s a side-by-side comparison:

{
  "action": "search",
  "query": "weather in NYC",
  "max_results": 10
}

Token savings: 41%

Syntax Differences

Feature	JSON	GLYPH	Tokens Saved
Key quotes	`"key":`	`key=`	2 per key
Separator	`:`	`=`	Same
Delimiter	`,`	space	1 per field
Booleans	`true`/`false`	`t`/`f`	2-3 per value
Null	`null`	`_`	3 per value

Bare String Rules

A string can be written without quotes if:

Non-empty
First character: Unicode letter or _
Remaining characters: Unicode letter, digit, _, -, ., /
Not a reserved word: t, f, true, false, null, none, nil

Otherwise, use double quotes with minimal escaping.

hello
hello_world
hello-2.0
file.txt
src/main.go

Canonical Form

GLYPH has a deterministic canonical form, crucial for hashing and state verification.

Float Formatting

Rules
Examples

Zero: Always 0 (not -0 or 0.0)
Threshold: Use exponent when exp < -4 or exp >= 15
Format: 2-digit minimum exponent (1e-06, not 1e-6)
Rejected: NaN and Infinity (not JSON-compatible)

0.000001              →  1e-06
100000000000000       →  1e+14
0.0001                →  0.0001  (no exponent)
10000000000000000     →  1e+16  (exponent)
-0                    →  0      (normalized)

Key Ordering

Map keys are sorted by bytewise UTF-8 comparison:

Input:  {"b":1,"a":2,"aa":3,"A":4,"_":5}
Output: {A=4 _=5 a=2 aa=3 b=1}

UTF-8 byte order: A (0x41) < _ (0x5F) < a (0x61)

This ensures the same data always produces the same output across all implementations (Go, Python, JavaScript, Rust, C).

Duplicate Keys

Last-wins policy: When duplicate keys exist, the last value is used.

Input:  {"k":1,"k":2,"k":3}
Output: {k=3}

Extended Types

GLYPH includes types beyond JSON’s capabilities:

References
Timestamps
Bytes

Typed references with namespace prefixes:

^user:abc123
^session:xyz789
^doc:draft-001

Format: ^<prefix>:<value>

ISO-8601 format:

2025-01-13T12:00:00Z
2025-01-13T12:00:00-05:00

Base64-encoded binary data:

b64"SGVsbG8gV29ybGQ="

LOOSE MODE

LOOSE MODE is GLYPH’s schema-optional subset, designed as a drop-in JSON replacement.

Design Goals

From the LOOSE_MODE_SPEC:

Drop-in JSON replacement - Any valid JSON is valid input
Deterministic canonical form - Same data → same output
Cross-language parity - Go, JS, Python produce identical output
Token efficiency - More compact than JSON

Key Features

JSON Compatible

Accept any JSON, emit valid JSON. Perfect round-trip.

Deterministic

SHA-256 hashing for state verification and conflict detection.

Compact

40-60% fewer tokens than JSON for typical data.

Cross-language

Byte-identical output across all implementations.

Usage Examples

import glyph

# JSON to GLYPH
data = {"action": "search", "query": "AI agents", "limit": 5}
glyph_str = glyph.json_to_glyph(data)
# Result: {action=search limit=5 query="AI agents"}

# GLYPH to JSON
original = glyph.glyph_to_json(glyph_str)

Type System

GLYPH supports constraints for validation:

Integer Constraints

limit int<1,100>        // min=1, max=100
port int<1024,65535>    // Valid port range
age int<0,150>          // Reasonable age

String Constraints

query str<1,500>        // min_len=1, max_len=500
username str<3,20>      // Username length
email str<5,255>        // Email length

Enum Constraints

units enum[celsius,fahrenheit]
status enum[pending,active,complete,failed]
mode enum[read,write,admin]

Real-World Example

Here’s a complex nested structure:

{
  "user": {
    "id": "usr_123",
    "name": "Alice Johnson",
    "email": "[email protected]",
    "active": true,
    "roles": ["admin", "user"],
    "metadata": {
      "created": "2025-01-01T00:00:00Z",
      "last_login": "2025-01-13T12:00:00Z",
      "login_count": 142
    }
  },
  "permissions": [
    {"resource": "users", "actions": ["read", "write"]},
    {"resource": "posts", "actions": ["read"]}
  ]
}

Token reduction: 41% (189 tokens saved)

Summary

GLYPH Format Benefits

40-60% fewer tokens than JSON
Deterministic canonical form for hashing
Human-readable text format
Cross-language compatible (Go, Python, JS, Rust, C)
Drop-in JSON replacement (LOOSE MODE)
Rich type system with constraints

Next Steps

Token Savings

Learn how GLYPH reduces token usage

Streaming Validation

Validate as tokens stream from LLMs

Tabular Mode

Compress homogeneous lists automatically

LOOSE MODE Spec

Complete technical specification

Get Started

Core Concepts

Guides

Language SDKs

Advanced

GLYPH Format

Core Syntax

Scalars

Collections

JSON vs GLYPH

Syntax Differences

Bare String Rules

Canonical Form

Float Formatting

Key Ordering

Duplicate Keys

Extended Types

LOOSE MODE

Design Goals

Key Features

JSON Compatible

Deterministic

Compact

Cross-language

Usage Examples

Type System

Integer Constraints

String Constraints

Enum Constraints

Real-World Example

Summary

Next Steps

Token Savings

Streaming Validation

Tabular Mode

LOOSE MODE Spec

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Language SDKs

Advanced

​Core Syntax

​Scalars

​Collections

​JSON vs GLYPH

​Syntax Differences

​Bare String Rules

​Canonical Form

​Float Formatting

​Key Ordering

​Duplicate Keys

​Extended Types

​LOOSE MODE

​Design Goals

​Key Features

JSON Compatible

Deterministic

Compact

Cross-language

​Usage Examples

​Type System

​Integer Constraints

​String Constraints

​Enum Constraints

​Real-World Example

​Summary

​Next Steps

Token Savings

Streaming Validation

Tabular Mode

LOOSE MODE Spec

Build docs developers (and LLMs) love

Core Syntax

Scalars

Collections

JSON vs GLYPH

Syntax Differences

Bare String Rules

Canonical Form

Float Formatting

Key Ordering

Duplicate Keys

Extended Types

LOOSE MODE

Design Goals

Key Features

Usage Examples

Type System

Integer Constraints

String Constraints

Enum Constraints

Real-World Example

Summary

Next Steps