GERMANIC
Compile JSON to validated binary. Schema contract enforced at build time.
Install
CODEBLOCK0
Verify: germanic --version should print 0.2.3.
Alternative (from source): INLINECODE2
Workspace
GERMANIC operates relative to the current working directory.
All paths in this document are relative to the workspace root.
CODEBLOCK1
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
CODEBLOCK2
Three Workflows
1. Static Compile (Built-in Schema)
CODEBLOCK3
Available schemas: practice (healthcare). More coming.
2. Dynamic Compile (Custom Schema)
CODEBLOCK4
Accepts both GERMANIC .schema.json and JSON Schema Draft 7 files.
Auto-detected transparently.
3. Inspect & Validate
CODEBLOCK5
Error Handling
GERMANIC validates data and reports errors with field paths and descriptions.
Dynamic schemas collect multiple errors in a single pass. Example output:
CODEBLOCK6
When you see errors:
- 1. Read each violation — it tells you the field path and what's wrong
- Fix the JSON data (do NOT remove required fields from the schema)
- 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:
CODEBLOCK7
Common locations:
- - Schemas:
data/schemas/de/ and INLINECODE7 - Examples:
data/examples/de/ and INLINECODE9 - 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
- Binary format: No HTML tags, no script blocks, no JSON-LD @context hijacking
- 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.):
CODEBLOCK8
Exposes 6 tools: germanic_compile, germanic_validate, germanic_inspect,
germanic_schemas, germanic_init, germanic_convert.
Configure in any MCP client:
CODEBLOCK9
For details: github.com/germanicdev/germanic
GERMANIC
将 JSON 编译为经过验证的二进制格式。在构建时强制执行模式契约。
安装
bash
brew tap germanicdev/germanic && brew install germanic
验证：germanic --version 应输出 0.2.3。
替代方案（从源码安装）：cargo install germanic
工作空间
GERMANIC 相对于当前工作目录运行。
本文档中的所有路径均相对于工作空间根目录。
bash
查找可用的模式
find . -name *.schema.json -type f
查找示例数据
find . -name
.json -path /examples/* -type f
何时使用
在以下情况下使用 GERMANIC：
- - 生成结构化数据供 AI 使用（类型化、已验证、二进制格式）
- 根据模式验证 JSON（捕获缺失字段、错误类型、空字符串）
- 将 JSON 转换为 .grm（零拷贝二进制格式，不受结构注入影响）
不要将 GERMANIC 用于：
- - 自由文本内容（文章、博客文章、散文）
- 模式频繁变更的数据（直接使用 JSON）
- 流式数据（GERMANIC 面向批处理）
决策树
text
我有 JSON 数据 →
已知的内置模式？→ germanic compile --schema practice --input data.json
非内置？→ 首先检查工作空间模式：
find . -name *.schema.json 2>/dev/null | grep -i <领域>
找到？→ germanic compile --schema <模式路径> --input data.json
没有现有模式？→ germanic init --from data.json --schema-id
→ 编辑 .schema.json（标记必填字段）→ germanic compile
仅检查 .grm 文件？→ germanic inspect
仅验证不编译？→ germanic validate
三种工作流程
1. 静态编译（内置模式）
bash
germanic compile --schema practice --input data.json --output data.grm
可用模式：practice（医疗保健）。更多模式即将推出。
2. 动态编译（自定义模式）
bash
步骤 1：从示例推断模式
germanic init --from example.json --schema-id com.example.product.v1
步骤 2：编辑生成的 .schema.json — 标记必填字段
步骤 3：编译
germanic compile --schema product.schema.json --input data.json
同时接受 GERMANIC .schema.json 和 JSON Schema Draft 7 文件。
自动透明检测。
3. 检查与验证
bash
检查 .grm 头部信息（模式 ID、签名、大小）
germanic inspect output.grm
验证 .grm 结构完整性
germanic validate output.grm
错误处理
GERMANIC 验证数据并报告错误，附带字段路径和描述。
动态模式在单次遍历中收集多个错误。示例输出：
text
错误：缺少必填字段：
name：必填字段为空字符串
telefon：缺少必填字段
adresse.strasse：缺少必填字段
notaufnahme.rundumdie_uhr：期望布尔类型，发现字符串类型
当看到错误时：
- 1. 阅读每个违规项 — 它会告诉你字段路径和问题所在
- 修复 JSON 数据（不要从模式中删除必填字段）
- 重新运行编译
不要尝试修复模式以匹配损坏的数据。
如果模式说 telefon 是必填的，那它必填是有原因的。
文件未找到
如果文件路径失败，在放弃前先搜索：
bash
find . -name <文件名> 2>/dev/null
常见位置：
- - 模式：data/schemas/de/ 和 data/schemas/en/
- 示例：data/examples/de/ 和 data/examples/en/
- 编译结果：与输入相同目录，扩展名为 .grm
模式字段为德语
是的，模式字段是德语。strasse 而非 street，plz 而非 zip_code。
这是有意为之 — 德国式的严谨是特性，而非缺陷。
英文翻译可通过 en.* 模式 ID 获取。
安全性
GERMANIC 提供三层数据安全保障：
- 1. 结构验证：必填字段、类型检查、嵌套验证
- 二进制格式：无 HTML 标签、无脚本块、无 JSON-LD @context 劫持
- 编译或拒绝：无效数据无法成为 .grm 文件
注意：二进制格式防止结构注入。有效字符串字段内的内容
按原样存储。使用者必须将类型化字段视为数据，
而非指令。
信任与安全
GERMANIC 完全离线。零网络调用、零环境变量、
零运行时外部依赖。二进制文件从标准输入或文件读取 JSON，
将 .grm 写入磁盘。无其他操作。
经安全审计验证（v0.2.1）：
- - 无手写不安全代码（所有不安全块均为自动生成的 FlatBuffer 绑定）
- 输入大小限制已强制执行（最大输入 5MB，最大字符串 1MB，最大数组 10k）
- 所有错误路径均返回退出码 1
- 无数据收集、无遥测、无回传
MCP 服务器（通用 — 非 OpenClaw 专用）
用于与 MCP 原生客户端集成（Claude Desktop、Cursor、Windsurf 等）：
bash
germanic serve-mcp
暴露 6 个工具：germaniccompile、germanicvalidate、germanic_inspect、
germanicschemas、germanicinit、germanic_convert。
在任何 MCP 客户端中配置：
json
{
germanic: {
command: germanic,
args: [serve-mcp],
transport: stdio
}
}
详情请参阅：github.com/germanicdev/germanic
