← Back to DevBytes
Developer Tutorial July 13, 2026 13 min read

Ion Format: A Complete Reference Guide

What Is Ion Format?

Amazon Ion is a richly-typed, self-describing, hierarchical data serialization format. It was developed internally at Amazon to address limitations found in JSON and other data formats when building large-scale, long-lived services. Ion is a superset of JSON, meaning every valid JSON document is also a valid Ion document. But Ion extends JSON significantly by adding a robust type system, binary encoding support, and annotations that make data self-describing without requiring external schema definitions.

The format is both human-readable (text format) and machine-efficient (binary format), and the two representations are losslessly convertible. This dual-mode nature is one of Ion's defining strengths — you can inspect data directly in logs and during debugging, yet transmit the same data efficiently in production.

Why Ion Matters

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

JSON has served the industry well, but it suffers from several well-known shortcomings when applied to complex, evolving systems:

Ion solves all of these problems while maintaining the simplicity and readability that made JSON popular. It's particularly well-suited for event logs, configuration files, scientific data, financial transactions, and inter-service communication where type fidelity and self-describing data are critical.

Ion Data Types

Ion has a rich, closed type system. Every Ion value has a precisely defined type. Here is the complete type taxonomy:

Each type has both a text representation and a binary encoding. Typed nulls are particularly useful: null.timestamp is distinct from null.int, preserving schema-level intent even when data is absent.

Ion Text Format by Example

Here is a sample Ion document demonstrating the text format's expressiveness:

// This is a comment in Ion text
/*
   Block comments are also supported
*/
$ion_1_0   // Ion version marker (optional but recommended)

// A struct (like a JSON object) with rich types
{
  userId: "abc-123",
  temperature_celsius: 23.5,           // decimal
  precise_temp: celsius::23.5012d3,    // annotated decimal with 3 digits of scale
  recorded_at: 2024-01-15T14:30:00.000-05:00,  // timestamp with timezone
  sample_count: 1048576,               // arbitrary-precision integer
  binary_payload: {{ VGhpcyBpcyBiaW5hcnk= }},  // blob (Base64 in text)
  tags: ["sensor", "outdoor", symbol::temperature],  // list with symbols
  metadata: {
    sensor_id: "XYZ-789",
    firmware_version: "2.4.1",
    calibration_factor: 0.998d4
  },
  null_field: null.string,             // typed null
  raw_logs: {{clob "Raw text data"}}   // clob
}

Ion vs JSON: Side-by-Side Comparison

The following table illustrates key differences:

// JSON                          // Ion Equivalent
{                                {
  "price": 19.99,                   price: 19.99,          // decimal, not float
  "quantity": 5,                    quantity: 5,           // int, not float
  "timestamp": "2024-01-15",        timestamp: 2024-01-15T00:00:00Z,
  "data": "SGVsbG8=",              data: {{SGVsbG8=}},    // blob, no quotes needed
  "unit": "celsius",               unit: celsius::null,    // annotation on null
  "value": 100                      value: celsius::100    // annotated int
}                                }

Notice how Ion eliminates the ambiguity: numbers retain their full precision, timestamps are native types, binary data is compact, and annotations carry semantic meaning without structural overhead.

How to Use Ion Format

Getting Started with the Ion CLI

The ion-cli tool (available via package managers or as a Java JAR) lets you convert, validate, and inspect Ion data:

# Install via Homebrew (macOS)
brew install amazon-ion/ion-cli/ion-cli

# Convert Ion text to Ion binary
ionc myfile.ion -o myfile.ionb

# Convert Ion binary back to text
ionc myfile.ionb -o decoded.ion

# Convert Ion to JSON (with type loss)
ionc myfile.ion --output-format json

# Pretty-print Ion with colors
ionc myfile.ion --output-format pretty

Using Ion in Java

The ion-java library is the reference implementation. Add it via Maven or Gradle:

// Maven dependency
// groupId: com.amazon.ion, artifactId: ion-java, version: 1.11.0

// Reading Ion text data
import com.amazon.ion.IonReader;
import com.amazon.ion.IonWriter;
import com.amazon.ion.IonSystem;
import com.amazon.ion.system.IonSystemBuilder;

public class IonExample {
    public static void main(String[] args) {
        // Create an Ion system (thread-safe, share globally)
        IonSystem ion = IonSystemBuilder.standard().build();

        // Parse Ion text into an in-memory value
        String ionText = "{ name: \"Alice\", age: 30, active: true }";
        com.amazon.ion.IonValue value = ion.loader().load(ionText);

        // Navigate the struct
        com.amazon.ion.IonStruct struct = (com.amazon.ion.IonStruct) value;
        System.out.println("Name: " + struct.get("name"));
        System.out.println("Age: " + struct.get("age"));

        // Write Ion data
        java.io.ByteArrayOutputStream out = new java.io.ByteArrayOutputStream();
        IonWriter writer = ion.newTextWriter(out);
        writer.stepIn(IonType.STRUCT);
        writer.setFieldName("message");
        writer.writeString("Hello, Ion!");
        writer.setFieldName("timestamp");
        writer.writeTimestamp("2024-01-15T14:30:00Z");
        writer.stepOut();
        writer.finish();
        System.out.println(out.toString());
    }
}

Using Ion in Python

The amazon-ion package is available via pip:

# Install
pip install amazon-ion

# Python example
import amazon.ion.simpleion as ion
from datetime import datetime, timezone

# Load Ion text
ion_text = '''
{
  sensor_id: "temp-001",
  readings: [22.5d1, 23.1d1, 22.8d1],
  timestamp: 2024-01-15T14:30:00Z
}
'''

# Parse to Python objects (with type preservation)
data = ion.loads(ion_text)
print(data)  # OrderedDict with Ion types preserved

# Access fields
print(data['sensor_id'])       # 'temp-001'
print(data['readings'])        # [Decimal('22.5'), Decimal('23.1'), Decimal('22.8')]
print(data['timestamp'])       # datetime.datetime(2024, 1, 15, 14, 30, tzinfo=timezone.utc)

# Dump Python objects to Ion text
output = ion.dumps({
    'result': 'ok',
    'count': 42,
    'timestamp': datetime.now(timezone.utc).isoformat()
}, binary=False)
print(output)

Using Ion in JavaScript/TypeScript

# Install the ion-js package
npm install ion-js

// JavaScript example
const ion = require('ion-js');

// Parse Ion text
const ionText = '{ name: "Bob", score: 95d2, tags: ["elite", "veteran"] }';
const reader = ion.makeReader(ionText);
const value = ion.loadAll(reader)[0];

// Access as JavaScript objects
console.log(value.get('name').stringValue());   // "Bob"
console.log(value.get('score').decimalValue());  // Decimal(95) with scale 2
console.log(value.get('tags').get(0).stringValue());  // "elite"

// Write Ion from JavaScript
const writer = ion.makeTextWriter();
writer.stepIn(ion.IonTypes.STRUCT);
writer.writeFieldName('status');
writer.writeSymbol('success');
writer.writeFieldName('data');
writer.writeInt(42);
writer.stepOut();
writer.finish();
console.log(writer.getBytesAsString());
// Output: { status: success, data: 42 }

Working with Annotations

Annotations are one of Ion's most powerful features. They allow you to attach metadata to any value without altering its structure:

// Annotations in practice
{
  temperature: celsius::23.5d1,        // annotated decimal
  pressure: hPa::1013.25d2,            // annotated decimal with unit
  sensor_id: uuid::"550e8400-e29b",   // annotated string (UUID semantics)
  coordinates: geo_json::{
    type: "Point",
    coordinates: [-73.935242, 40.730610]
  },
  image_data: mime::image/png::{{iVBORw0KGgo=}}  // chained annotations on blob
}

When reading annotated values in code:

// Java: reading annotations
IonReader reader = ion.newReader(ionText);
reader.next();
reader.stepIn();  // enter struct
while (reader.next() != null) {
    String[] annotations = reader.getTypeAnnotations();
    for (String ann : annotations) {
        System.out.println("Annotation: " + ann);
    }
    System.out.println("Field: " + reader.getFieldName());
    System.out.println("Value: " + reader.stringValue());
}

Ion Binary Format

The Ion binary format is extremely compact and efficient. It uses a type-length-value encoding with symbol tables for string interning. Here's an illustration of the size difference:

# Given this Ion text (147 bytes):
# { name: "Alice", age: 30, email: "alice@example.com", active: true }

# The equivalent Ion binary is approximately 38 bytes
# (symbol table + structured data with field name symbols interned)

# Convert and compare
echo '{ name: "Alice", age: 30, email: "alice@example.com", active: true }' | ionc --output-format binary | wc -c
# Output: 38 (approximately)

# Compare with JSON
echo '{"name":"Alice","age":30,"email":"alice@example.com","active":true}' | wc -c
# Output: 68

The binary format uses a local symbol table that interns field names (like name, age, email) as small integer references, dramatically reducing repeated string overhead in large datasets.

Symbol Tables and Interning

Symbols in Ion are interned strings. When writing many structs with the same field names, symbols drastically reduce payload size. The binary format automatically builds symbol tables:

// Ion text with explicit symbol table declaration
$ion_symbol_table::{
  symbols: ["name", "age", "email", "active"]
}
{
  name: "Alice",
  age: 30,
  email: "alice@example.com",
  active: true
}
{
  name: "Bob",
  age: 25,
  email: "bob@example.com",
  active: false
}

In the binary encoding, after the first struct, subsequent references to name become a single byte index into the symbol table rather than the full string "name".

Best Practices for Ion Format

1. Always Use the Ion Version Marker

Start your Ion text documents with $ion_1_0 to explicitly declare the version. This ensures forward compatibility as the format evolves:

$ion_1_0
{
  // your data here
}

2. Prefer Typed Nulls Over Omitted Fields

Use null.int, null.timestamp, etc., rather than omitting fields. Typed nulls preserve the expected type for schema evolution and consumer expectations:

// Good — type information preserved
{ temperature: null.decimal, recorded_at: null.timestamp }

// Avoid — consumers must guess the type
{}

3. Use Annotations for Semantic Metadata

Annotations are ideal for units, data classifications, provenance, or format hints. They avoid the "wrapping object" anti-pattern:

// Good — clean, direct
{ temp: celsius::23.5d1 }

// Avoid — bloated nesting
{ temp: { value: 23.5, unit: "celsius" } }

4. Choose Decimal for Financial and Scientific Data

Decimals in Ion have arbitrary precision and fixed scale, making them perfect for money, measurements, and calculations where floating-point rounding is unacceptable:

// Precise financial amount
{ amount: 100.50d2, currency: "USD" }  // exactly 100.50, scale 2

// Scientific measurement with 5 decimal places
{ mass_kg: 0.00231d5 }  // exactly 0.00231

5. Use S-Expressions for Domain-Specific Syntax

S-expressions (sexp) are ideal for representing expressions, queries, or DSL fragments within Ion:

{
  filter_expression: (and (>= age 18) (eq status "active")),
  query: (select name email (from users (where (eq role "admin"))))
}

6. Prefer Binary Format for Production Transport

Always use Ion binary for service-to-service communication. It's significantly smaller and faster to parse than Ion text or JSON. Reserve text format for human-facing interfaces like logs, configuration files, and debugging:

// Java: writing binary Ion
IonWriter binaryWriter = ion.newBinaryWriter(outputStream);
// ... write your data ...
// Automatically builds symbol tables and uses compact encoding

7. Handle Symbol Table Evolution Carefully

When using binary Ion across service boundaries, be aware that symbol tables are local to each data stream. If you concatenate binary Ion streams, you may need to re-encode or ensure symbol table continuity:

// Java: appending to existing binary stream
// Use an AppendableByteArrayOutputStream or ensure symbol table imports
// For separate streams, consider using a shared symbol table catalog

8. Validate Early, Validate Often

Use Ion's schema mechanism (Ion Schema Language, or ISL) for structural validation when data contracts matter:

// Ion Schema example (schema.isl)
$ion_1_0
type::{
  name: "SensorReading",
  fields: {
    sensor_id: { type: string, occurs: required },
    temperature: { type: decimal, occurs: required, annotations: [celsius] },
    timestamp: { type: timestamp, occurs: required }
  }
}

9. Leverage the Streaming Reader/Writer APIs

For large datasets, always use streaming APIs rather than loading entire documents into memory. Ion's binary format is designed for efficient incremental parsing:

// Java: streaming read example
IonReader reader = ion.newReader(inputStream);
reader.next();  // top-level value
reader.stepIn(); // enter container
while (reader.next() != null) {
    // Process each field/value incrementally
    // No full document materialization needed
}

Advanced Ion Features

Decimal Precision and Scale

Ion decimals carry explicit scale information. 100.50d2 means the value 100.50 with scale 2 (two decimal places). This is distinct from 100.5d1 even though they are numerically equal — the scale conveys measurement precision:

// Different scales convey different precision semantics
{ price: 19.99d2 }    // scale 2: precise to cents (financial)
{ price: 19.9d1 }     // scale 1: precise to tenths
{ price: 19.99 }      // scale inferred from literal: 2

Timestamp Precision

Ion timestamps support arbitrary fractional second precision:

// Various timestamp precisions
2024-01-15T14:30:00Z                    // second precision
2024-01-15T14:30:00.123Z                // millisecond precision
2024-01-15T14:30:00.123456789Z          // nanosecond precision
2024-01-15T14:30:00.123456789-05:00     // with timezone offset
2024-01-15                              // date only (day precision)

Text vs Binary Round-Trip Fidelity

One of Ion's guarantees is that converting from text to binary and back to text produces semantically identical data (though formatting may differ). This round-trip property is essential for data pipelines:

# Round-trip demonstration
echo '{ value: 42, name: "test" }' | ionc --output-format binary | ionc --output-format pretty
# Output will be semantically equivalent to the input

Integrating Ion with Common Systems

Ion with Apache Spark

You can read Ion data in Spark by using the Ion binary format and custom deserializers, or by converting Ion to Parquet/ORC for analytical workloads. Ion's self-describing nature makes it a good fit for event streams processed by Spark Structured Streaming.

Ion with AWS Services

Several AWS services natively support Ion, including Amazon QLDB (Quantum Ledger Database) which uses Ion as its document format, and Amazon Keyspaces. AWS Lambda events can be processed in Ion format, and CloudWatch Logs Insights supports Ion queries.

Ion with REST APIs

While JSON dominates REST, you can use Ion text as a drop-in replacement wherever JSON is accepted, since Ion text is a superset. For binary transport, use content negotiation with Content-Type: application/ion:

// HTTP request with Ion content type
POST /api/v1/sensors HTTP/1.1
Content-Type: application/ion
Accept: application/ion

$ion_1_0
{
  sensor_id: "temp-001",
  readings: [22.5d1, 23.1d1, 22.8d1],
  timestamp: 2024-01-15T14:30:00Z
}

Ion Schema Language (ISL)

For systems that need structural contracts, Ion Schema Language provides type definitions that can be validated at runtime:

// Schema definition in ISL
$ion_1_0
type::{
  name: "User",
  fields: {
    id: { type: string, occurs: required, annotations: [uuid] },
    name: { type: string, occurs: required },
    email: { type: string, occurs: optional },
    age: { type: int, occurs: optional, valid_values: range::[0, 150] },
    tags: { type: list, occurs: optional, element_type: string }
  }
}

// Valid Ion data conforming to schema
uuid::"550e8400-e29b-41d4-a716-446655440000"
{
  id: uuid::"550e8400-e29b-41d4-a716-446655440000",
  name: "Alice",
  email: "alice@example.com",
  age: 30,
  tags: ["admin", "user"]
}

Performance Considerations

Ion's design prioritizes both human readability and machine efficiency. Key performance characteristics include:

Common Pitfalls and How to Avoid Them

Pitfall 1: Treating Ion Like JSON with Extra Types

While Ion is a JSON superset, its design philosophy differs. Don't simply map JSON patterns to Ion — leverage annotations, typed nulls, and decimals for cleaner data models.

Pitfall 2: Ignoring Typed Nulls

Using untyped null (or omitting fields) discards type information. Always use typed nulls like null.decimal or null.timestamp when data is absent.

Pitfall 3: Mixing Ion Binary Streams Incorrectly

Each Ion binary stream has its own symbol table. Concatenating streams requires either re-encoding or importing symbol tables. Use the Ion catalog pattern for shared symbol tables across streams.

Pitfall 4: Overusing S-Expressions for General Data

S-expressions are powerful but can confuse consumers expecting structs. Reserve sexps for domain-specific expressions (queries, filters, mathematical expressions) rather than general data structuring.

Conclusion

Amazon Ion represents a thoughtful evolution beyond JSON, addressing real-world data fidelity, efficiency, and self-description challenges that arise in large-scale distributed systems. Its dual text/binary format, rich type system, annotation mechanism, and streaming-friendly design make it an excellent choice for event logging, inter-service communication, configuration management, and any domain where data types must be preserved exactly. By following the best practices outlined in this guide — using typed nulls, leveraging annotations for metadata, choosing decimals for precise numeric data, and preferring binary encoding for production transport — you can build systems that are both more robust and more efficient than their JSON-based counterparts. The growing ecosystem of libraries across Java, Python, JavaScript, and other languages, combined with native AWS service integration, makes Ion increasingly accessible for modern development stacks.

🚀 Need a reliable AI agent for your project?

Deploy Hermes Agent in 10 minutes. Managed hosting, zero DevOps.

Get Started — $23.99/mo
← Back to all articles