Schema Definitions

Schemas are Tauq's superpower for token efficiency. Define field names once, then use compact positional values.

Defining Schemas with !def

Basic Syntax

Use !def to define a schema with a name and field list:

!def SchemaName field1 field2 field3 ...

# Example: User schema
!def User id name email role

# Now use positional values
1 Alice alice@example.com admin
2 Bob bob@example.com user
3 Carol carol@example.com user

Each line after the schema becomes an object with named fields.

Equivalent JSON

The above Tauq produces this JSON:

[
  {"id": 1, "name": "Alice", "email": "alice@example.com", "role": "admin"},
  {"id": 2, "name": "Bob", "email": "bob@example.com", "role": "user"},
  {"id": 3, "name": "Carol", "email": "carol@example.com", "role": "user"}
]

Token Savings

JSON: 68 tokens | Tauq: 28 tokens | 59% reduction

Using Schemas with !use

Explicit Schema Application

Use !use to apply a schema to subsequent records:

# Define schemas at the top
!def User id name email
!def Product id name price

# Section separator
---

# Apply User schema
users [
  !use User
  1 Alice alice@example.com
  2 Bob bob@example.com
]

# Apply Product schema
products [
  !use Product
  101 "Widget A" 29.99
  102 "Widget B" 39.99
]

Implicit Schema Use

When there's only one schema, records after --- automatically use it:

!def User id name email
---
1 Alice alice@example.com
2 Bob bob@example.com
3 Carol carol@example.com

Nested Data with Schemas

Schemas Inside Objects

!def OrderItem product_id quantity price
---
order {
  id 12345
  customer "Acme Corp"
  items [
    !use OrderItem
    101 2 29.99
    102 1 49.99
    103 5 9.99
  ]
  total 159.92
}

Multiple Nested Arrays

!def Author id name
!def Book id title year
---
library {
  name "City Library"
  authors [
    !use Author
    1 "Jane Austen"
    2 "Mark Twain"
  ]
  books [
    !use Book
    101 "Pride and Prejudice" 1813
    102 "Tom Sawyer" 1876
  ]
}

Best Practices

1. Define Schemas at Document Top

Keep all schema definitions together for clarity and reuse.

# Good: All schemas at top
!def User id name email
!def Order id user_id total
!def Product id name price
---
# Data follows...

2. Use Descriptive Schema Names

Schema names should clearly indicate what data they represent.

# Good
!def CustomerRecord id name email tier
!def TransactionLog timestamp action user_id

# Avoid
!def D1 a b c d
!def Rec x y z

3. Keep Field Order Consistent

Put frequently accessed or identifying fields first.

# Good: ID first, then key fields, then details
!def User id name email role created_at

# The most important fields come first for easy scanning

4. Use Schemas for 3+ Records

Schemas shine with repetitive data. For 1-2 records, inline objects may be clearer.

Schema vs Inline Objects

Use Schemas When:

• 3+ objects with same structure
• Tabular/columnar data
• Token efficiency is critical
• Data will be streamed

!def User id name email
1 Alice alice@ex.com
2 Bob bob@ex.com
3 Carol carol@ex.com

Use Inline Objects When:

• 1-2 objects only
• Heterogeneous structures
• Deeply nested config
• Readability over efficiency

config {
  server { host localhost port 8080 }
  database { url "postgres://..." }
}

Try Schemas in the Playground

Experiment with schema definitions and see real-time token counts.

Open Playground Type System