slimschema 0.0.1.dev4

Token-efficient schema language for LLMs with fast Zig backend

SlimSchema

SlimSchema is a schema language optimized for LLM token efficiency that converts between YAML, Pydantic, and msgspec.

Core Features

• Token Efficient: Compressed syntax (age: 18..120) saves context window and costs.
• Deep Validation: Recursive validation for nested objects and dictionaries.
• Universal Bridge: Convert between formats (Pydantic ↔ YAML ↔ msgspec).

Quick Start

uv pip install slimschema
pip install slimschema

Example

Define a schema with nested types and defaults, validate data, and get a validated Python object.

from slimschema import to_data, to_pydantic

# 1. Define a compact schema (with nested defaults!)
schema = """
user:
  name: str{3..50}
  role: admin | user | guest = "guest"
  settings:
    theme: str = "dark"
    notifications: bool = true
"""

# 2. Validate JSON data (string or dict/list)
# Input missing 'settings' -> defaults apply automatically
data, error = to_data('{"user": {"name": "Alice"}}', schema)

print(data)
# {
#   "user": {
#     "name": "Alice",
#     "role": "guest",
#     "settings": {"theme": "dark", "notifications": True}
#   }
# }

# 3. Convert to Pydantic for your app
UserModel = to_pydantic(schema)
instance = UserModel(**data)
print(instance.user.settings.theme) # "dark"

Full Spec

# Primitives
field: str | int | float | bool | obj

# Default generators
id: str = uuid                 # UUID v4 string
id_v7: str = uuid7             # UUID v7 (time-ordered)
id_ulid: str = ulid            # ULID (sortable)
id_xid: str = xid              # XID (compact, sortable)
id_nano: str = nanoid          # NanoID (URL-safe)
created: datetime = now        # Current datetime
day: date = today              # Current date
ts: int = epoch                # Unix timestamp (seconds)

# Format types
email: email
website: url
birthday: date
timestamp: datetime

# Collections
items: list[str]
tags: set[str]
coords: tuple[float, float]

# Constraints
name: str{3..50}        # Length 3-50
age: 18..120            # Range
code: /^[A-Z]{3}$/      # Regex

# Enums and Unions
status: active | pending | done    # Enum (Literal)
value: str | int                   # Union

# Typed dictionaries
scores: dict[str, int]             # Key-value types

# Inline objects
user: {name: str, age: int, email?: str}

# Optional vs Nullable
?optional_field: str    # Can omit field entirely
nullable_field: str?    # Field required, value can be null
?both: str?             # Optional AND nullable

Default Syntax

count: int = 0
name: str = "default"
items: list = []
created: str = now              # Current datetime
id: str = uuid                  # UUID v4
id2: str = uuid7                # UUID v7 (time-ordered)
id3: str = ulid                 # ULID (sortable)
id4: str = xid                  # XID (compact)
id5: str = nanoid               # NanoID (URL-safe)
ts: int = epoch                 # Unix timestamp (seconds)

API Functions

from slimschema import (
    parse_slimschema,  # YAML string → Schema IR
    to_schema,         # Any input → Schema IR
    to_data,           # JSON string/dict + schema → (data, error)
    to_pydantic,       # Schema → Pydantic model class
    to_msgspec,        # Schema → msgspec Struct class
    to_yaml,           # Schema → YAML string
    SchemaParseError,  # Exception for parse errors
)

Documentation

Guides

• Syntax Guide: Primitives, constraints, and inline objects.
• Validation Guide: How to_data validates and reports errors.
• Defaults Guide: Handling partial data with scalar and nested defaults.

Integrations

• Pydantic: Round-trip conversion and nested models.
• msgspec: High-performance validation structs.

Reference

• API Reference: Complete function signatures.
• Error Handling: Validation and parsing errors.
• FAQ: Common questions.

API Reference

• to_data(data, schema): Validate JSON string or dict/list against schema.
• to_schema(obj): Convert Pydantic/msgspec/YAML to SlimSchema IR.
• to_yaml(schema): Convert Schema to compact YAML string.
• to_pydantic(schema): Generate Pydantic models.
• to_msgspec(schema): Generate msgspec structs.

License

MIT