Specification v1.0

1. Introduction

ISON (Interchange Simple Object Notation) is a minimal, human-readable data serialization format optimized for Large Language Model (LLM) comprehension.

1.1 Purpose

ISON is designed to serve as the primary data interchange format for:

• LLM prompt engineering
• RAG (Retrieval-Augmented Generation) pipelines
• Multi-agent AI systems
• Database query outputs (relational, vector, graph)
• Tool and function call results
• Knowledge base serialization
• Any system exchanging structured data with language models

1.2 Goals

• Minimal syntax: Reduce punctuation overhead that wastes tokens
• LLM-optimized: Maximize comprehension with minimal cognitive load
• Token-efficient: Fit more data in context windows than JSON allows
• Relational: Native support for references and relationships
• Human-readable: Clear structure without visual noise

2. Design Principles

1. Whitespace as delimiter: Fields separated by spaces/tabs, not commas
2. Quotes only when necessary: Unquoted values are the default
3. Tables over nesting: Prefer normalized tables to deeply nested structures
4. Explicit references: Graph edges expressed via :ID notation
5. Type inference: Parsers infer types from value patterns

3. Lexical Structure

3.1 Character Set

ISON documents MUST be encoded in UTF-8.

3.2 Whitespace

• Field separator: One or more spaces (U+0020) or tabs (U+0009)
• Line terminator: LF (U+000A) or CRLF (U+000D U+000A)
• Leading and trailing whitespace on lines is ignored

3.3 Reserved Characters

4. Block Structure

An ISON document consists of one or more blocks. Each block represents a logical data unit.

4.1 Block Syntax

kind.name
field1 field2 field3
value1 value2 value3
...

4.2 Block Components

1. Header line: kind.name (required)
2. Field line: Space-separated field names (required)
3. Data lines: Space-separated values (zero or more)

4.3 Block Kinds

4.4 Multiple Blocks

Blocks are separated by one or more blank lines:

object.config
key value
timeout 30

table.users
id name
1 Alice
2 Bob

5. Data Types

ISON supports the following primitive types:

5.1 Type Annotations in Headers

Field headers MAY include optional type annotations using the field:type syntax:

table.products
id:int name:string price:float in_stock:bool category:ref
1 Widget 29.99 true :CAT-1
2 Gadget 49.99 false :CAT-2

Supported type hints:

• int - Integer values
• float - Floating point numbers
• string - Text values
• bool - Boolean (true/false)
• ref - Reference to another record
• computed - Derived/calculated field
• node - Graph node reference
• edge - Graph edge reference

Type annotations are for documentation and validation; parsers MAY use them for type checking.

5.2 Computed Fields

Fields may be marked as computed (derived from other values):

table.orders
id subtotal tax_rate tax:computed total:computed
1 100.00 0.08 8.00 108.00
2 50.00 0.08 4.00 54.00

5.3 Summary Rows

Tables MAY include a summary row after a --- separator:

table.sales_by_region
region q1 q2 q3 q4 total
Americas 1.2M 1.4M 1.5M 1.8M 5.9M
EMEA 0.8M 0.9M 1.0M 1.1M 3.8M
APAC 0.5M 0.6M 0.7M 0.9M 2.7M
---
TOTAL 2.5M 2.9M 3.2M 3.8M 12.4M

Summary rows are stored separately from data rows and provide aggregated information.

6. Type Inference Rules

For unquoted tokens, parsers MUST apply these rules in order:

1. If token equals true → boolean (true)
2. If token equals false → boolean (false)
3. If token equals null → null
4. If token matches ^-?[0-9]+$ → integer
5. If token matches ^-?[0-9]+\.[0-9]+$ → float
6. If token starts with : → reference
7. Otherwise → string

6.1 Forcing String Type

To represent literal values that match other patterns, use quotes:

table.flags
name value
enabled true      # boolean
label "true"      # string "true"
code "123"        # string "123"
count 123         # integer 123

7. Quoting and Escaping

7.1 When to Quote

Values MUST be quoted if they contain:

• Spaces
• Double quotes
• Characters that would trigger incorrect type inference

7.2 Escape Sequences

Inside quoted strings, the following escape sequences are recognized:

7.3 Examples

table.messages
id text
1 "Hello, how are you?"
2 "I said \"hello\" back"
3 "Line 1\nLine 2"

8. References

References express relationships between records, enabling graph semantics. ISON's graph references are a key differentiator for database-to-LLM workflows.

8.1 Basic Reference

A reference is an unquoted token starting with ::

:10
:user_101
:abc-123

8.2 Namespaced Reference

For disambiguation, references MAY include a type prefix (lowercase):

:team:10
:user:101
:product:SKU-123

8.3 Relationship-Typed Reference

References can include relationship types (UPPERCASE) to express graph edges semantically:

:MEMBER_OF:10
:REPORTS_TO:102
:IS_A:C1
:ENABLES:C2

This enables LLMs to understand the nature of relationships, not just their existence.

8.4 Reference Examples

object.team
id name
10 "AI Research"

table.users
id name team
101 Mahesh :MEMBER_OF:10
102 Priya :LEADS:10

Here, :MEMBER_OF:10 semantically indicates "member of team 10", while :LEADS:10 indicates "leads team 10".

8.5 Knowledge Graph Example

table.concepts
id name category
:C1 "Machine Learning" field
:C2 "Deep Learning" subfield
:C3 "Neural Networks" technique

table.relationships
from to type strength
:C2 :C1 :IS_A 1.0
:C3 :C2 :ENABLES 0.8
:C3 :C1 :RELATED_TO 0.6

9. Complete Examples

9.1 Simple Table

table.products
id name price inStock
1 Widget 9.99 true
2 Gadget 19.99 false
3 "Super Gizmo" 29.99 true

9.2 Nested Fields

object.order
id customer.name customer.address.city total
5001 Mahesh Dallas 125.50

9.3 Graph with References

table.departments
id name budget
10 Engineering 500000
20 Marketing 300000

table.employees
id name department manager
1 Alice :10 null
2 Bob :10 :1
3 Carol :20 null
4 Dave :20 :3

9.4 E-commerce System

# Customer information
object.customer
id name email address.city address.state
1001 "John Smith" john@example.com "New York" NY

# Orders
table.orders
id customerId date total status
5001 :1001 2025-01-15 125.50 completed
5002 :1001 2025-01-20 89.99 processing

# Line items
table.order_items
orderId sku name qty unitPrice
5001 A1 Widget 2 25.00
5001 B2 Gadget 1 75.50
5002 C3 "Deluxe Widget" 3 29.99