GERMANIC

Validate JSON data against schemas and compile to binary .grm files. Schema-enforced data contracts for AI agents. Catches missing fields, wrong types, empty...

Compile JSON to validated binary. Schema contract enforced at build time.

Install

brew tap germanicdev/germanic && brew install germanic

Verify: germanic --version should print 0.2.3.

Alternative (from source): cargo install germanic

Workspace

GERMANIC operates relative to the current working directory. All paths in this document are relative to the workspace root.

# Find available schemas
find . -name "*.schema.json" -type f

# Find example data
find . -name "*.json" -path "*/examples/*" -type f

When to Use

Use GERMANIC when you need to:

• Produce structured data for AI consumption (typed, validated, binary)
• Validate JSON against a schema (catches missing fields, wrong types, empty strings)
• Convert JSON to .grm (zero-copy binary, immune to structural injection)

Do NOT use GERMANIC for:

• Free-text content (articles, blog posts, prose)
• Data that changes schema frequently (use JSON directly)
• Streaming data (GERMANIC is batch-oriented)

Decision Tree

"I have JSON data" →
  Known built-in schema? → germanic compile --schema practice --input data.json
  Not built-in? → Check workspace schemas first:
    find . -name "*.schema.json" 2>/dev/null | grep -i <domain>
    Found? → germanic compile --schema <path-to-schema> --input data.json
  No schema exists? → germanic init --from data.json --schema-id <id>
    → edit .schema.json (mark required fields) → germanic compile
  Just inspect a .grm? → germanic inspect <file.grm>
  Validate without compiling? → germanic validate <file.grm>

Three Workflows

1. Static Compile (Built-in Schema)

germanic compile --schema practice --input data.json --output data.grm

Available schemas: practice (healthcare). More coming.

2. Dynamic Compile (Custom Schema)

# Step 1: Infer schema from example
germanic init --from example.json --schema-id com.example.product.v1

# Step 2: Edit the generated .schema.json — mark required fields

# Step 3: Compile
germanic compile --schema product.schema.json --input data.json

Accepts both GERMANIC .schema.json and JSON Schema Draft 7 files. Auto-detected transparently.

3. Inspect & Validate

# Inspect .grm header (schema-id, signature, sizes)
germanic inspect output.grm

# Validate .grm structural integrity
germanic validate output.grm

Error Handling

GERMANIC validates data and reports errors with field paths and descriptions. Dynamic schemas collect multiple errors in a single pass. Example output:

Error: Required fields missing:
  name: required field is empty string
  telefon: required field missing
  adresse.strasse: required field missing
  notaufnahme.rund_um_die_uhr: expected bool, found string

When you see errors:

1. Read each violation — it tells you the field path and what's wrong
2. Fix the JSON data (do NOT remove required fields from the schema)
3. Re-run compile

Do NOT try to "fix" the schema to match broken data. If the schema says telefon is required, it's required for a reason.

File Not Found

If a file path fails, search before giving up:

find . -name '<filename>' 2>/dev/null

Common locations:

• Schemas: data/schemas/de/ and data/schemas/en/
• Examples: data/examples/de/ and data/examples/en/
• Compiled: same directory as input, with .grm extension

Schema Fields Are German

Yes, the schema fields are in German. strasse not street, plz not zip_code. This is intentional — Deutsche Gründlichkeit als Feature, nicht als Bug. The English translations are available under en.* schema IDs.

Security

GERMANIC provides three layers of data safety:

1. Structural validation: Required fields, type checking, nested validation
2. Binary format: No HTML tags, no script blocks, no JSON-LD @context hijacking
3. Compile-or-reject: Invalid data cannot become a .grm file

Note: Binary format prevents structural injection. Content inside valid string fields is stored as-is. The consumer must treat typed fields as data, not instructions.

Trust & Safety

GERMANIC is fully offline. Zero network calls, zero environment variables, zero external dependencies at runtime. The binary reads JSON from stdin or file, writes .grm to disk. Nothing else.

Verified by security audit (v0.2.1):

• No hand-written unsafe code (all unsafe blocks are auto-generated FlatBuffer bindings)
• Input size limits enforced (5MB max input, 1MB max string, 10k max array)
• Exit code 1 on all error paths
• No data collection, no telemetry, no phone-home

MCP Server (Universal — not OpenClaw-specific)

For integration with MCP-native clients (Claude Desktop, Cursor, Windsurf, etc.):

germanic serve-mcp

Exposes 6 tools: germanic_compile, germanic_validate, germanic_inspect, germanic_schemas, germanic_init, germanic_convert.

Configure in any MCP client:

{
  "germanic": {
    "command": "germanic",
    "args": ["serve-mcp"],
    "transport": "stdio"
  }
}

For details: github.com/germanicdev/germanic