synx-format 3.7.1

Main SYNX site: https://synx.aperturesyndicate.com/

Built for AI and humans by APERTURESyndicate.

Frozen reference (3.6) + additions (3.7)

As of April 2026, SYNX 3.6 is frozen as the canonical interoperability baseline: the normative definition is docs/spec/SYNX-3.6-NORMATIVE.md, and the reference implementation is synx-core 3.6.x checked by tests/conformance/. PATCH releases may only restore that contract (bugs, spec alignment); new surface syntax stays additive and arrives in new normative version files. Full policy: docs/spec/CORE-FREEZE.md.

SYNX 3.7 (docs/spec/SYNX-3.7-NORMATIVE.md) is the first additive revision. It introduces a single new construct — |+, an indent-preserving multiline opener — and inherits every other rule from 3.6 verbatim. A 3.6 parser remains conformant for any document that does not use a 3.7-only construct.

3.7.0 (2026-07-30) — two additions.

1. |+, an indent-preserving multiline opener. Required when embedding indent-sensitive content (code, SYNX examples, AI-prompt scaffolds) inside a SYNX value; plain | still trims each continuation line. Implemented in every parser shipped from this repo (Rust core, JS/TS, C++, Dart, .NET, Go, Java, Swift, plus all FFI bindings into the Rust core).
2. SYNXL (.synxl), a new record-stream format for datasets — the SYNX-native counterpart of JSONL and CSV. Own version axis, own normative spec: docs/spec/SYNXL-1-NORMATIVE.md. See SYNXL — record streams below.

See CHANGELOG.md.

3.6.3 (2026-05-19) — cross-implementation parity hot-fix release plus a structural shift: C++, Dart, Go, Java, Swift, and a new Godot/GDScript engine now ship as native parsers under parsers/ (and integrations/godot/synx-gdscript/); the old bindings/{cpp,go,swift} FFI wrappers are retired in favour of these from-scratch implementations. The release also closes 17 cross-parser divergences uncovered by a code-review pass — three of them security-relevant (Go :include symlink jail bypass, .NET Secret leaking to JSON, .NET missing __proto__ filter). See CHANGELOG.md.

Documentation and repo map

• docs/SYNX_AT_A_GLANCE.md — single-page overview: paths, parsers, fuzz/C#, AI/Claude, benchmarks, verification scripts
• docs/README.md — index of guides, specification, and benchmark docs
• docs/repository-layout.md — full tree (parsers, integrations, bindings)
• parsers/README.md — native parser implementations (Rust, TypeScript, C++, Dart, C# / .NET, Go, Java, Swift); FFI bindings are listed separately in bindings/
• integrations/README.md — VS Code, Visual Studio, Sublime, Neovim, Godot, MCP, LSP
• docs/anthropic/claude.md — Claude Desktop (MCP), Anthropic prompt helpers, tokenizer notes
• docs/dev/plugins-roadmap.md — planned registry / plugins (stub only; not shipped in the engine yet)
• docs/spec/SYNXL-1-NORMATIVE.md — normative spec for SYNXL (.synxl), the record-stream format; conformance cases in tests/conformance-synxl/cases/

SYNXL — record streams (.synxl)

New in 3.7.0. SYNXL ("SYNX Lines") is a separate format on its own version axis — the SYNX-native counterpart of JSONL and CSV. A document declares its fields once, then carries records; each record projects to a JSON object and the whole document to a JSON array. Normative definition: docs/spec/SYNXL-1-NORMATIVE.md (format version 1, embedding SYNX 3.7 for block fields).

A SYNXL document is not a SYNX document — its root is a sequence of records rather than an object — so Synx.parse will not read one. Use the SYNXL entry points below.

!synxl 1
!fields id[type:int, required] ; score[type:float] ; messages[block]

1 ; 0.91
  messages
    - role system
      content You are a helpful assistant.
    - role user
      content |+
          def f(x):
              return x + 1

2 ; 0.74
  messages
    - role user
      content Привет

→ [{"id":1,"messages":[{"content":"You are a helpful assistant.","role":"system"},{"content":"def f(x):\n return x + 1","role":"user"}],"score":0.91}, …]

• Inline fields are ;-delimited and positional; an empty part is null, "" is the empty string — the ambiguity CSV never resolved.
• A [block] field takes its value from the record's indented block, parsed by the ordinary SYNX 3.7 parser — so nesting, lists and |+ all work there, and long text stays readable instead of \n-escaped.
• Directives are disabled inside a block, so an untrusted dataset row can never become an !include file-read primitive.
• A new !fields line mid-file replaces the schema for records after it: datasets stay append-safe across schema evolution.
• Malformed structure is reported as a diagnostic, never dropped silently — a dataset that quietly loses a column is worse than one that fails loudly.

Reading it from code

// Rust — synx-core
use std::fs::File;
use std::io::BufReader;
use synx_core::synxl::{self, SynxlStreamReader};

// Whole document in memory
let doc = synxl::parse_lines(&std::fs::read_to_string("chat.synxl")?)?;
println!("version {}, {} records", doc.version, doc.len());

let first = doc.records[0].as_object().unwrap();   // records are Value::Object
println!("{:?}", first.get("id"));                 // Some(Int(1))
println!("{}", doc.to_json());                     // canonical JSON array (§12.1)
println!("{}", doc.to_ndjson());                   // one object per line (§12.2)
for d in &doc.diagnostics { eprintln!("{d}"); }    // §11.2 — never dropped silently

// Streaming off disk — live memory is one record, whatever the file size
for record in SynxlStreamReader::new(BufReader::new(File::open("chat.synxl")?))? {
    let record = record?;                          // Err ends the document (§11.1)
    let obj = record.value.as_object().unwrap();   // + record.index / .line / .diagnostics
    println!("{:?}", obj.get("id"));
}

// Writing (§14) — quoting and block promotion are automatic
let text = synxl::write_lines(
    &[synxl::FieldDecl::new("id"), synxl::FieldDecl::new_block("messages")],
    &doc.records,
)?;

// Opt-in constraint checking (§8.4, off by default)
let checked = synxl::parse_lines_with(&src, &synxl::SynxlOptions { validate: true })?;

// TypeScript / JavaScript — @aperturesyndicate/synx-format
import { Synx } from '@aperturesyndicate/synx-format';

const doc = Synx.parseSynxl(text);
doc.version;                     // 1
doc.records[0].values.id;        // 1
doc.records[0].values.messages;  // [{ role: 'system', content: '…' }, …]
doc.diagnostics;                 // SynxlDiagnostic[] — §11.2

Synx.synxlToJSON(text);          // canonical JSON array (§12.1)
Synx.synxlToNDJSON(text);        // one object per line (§12.2)

// Streaming — sync over text, async over a file or a chunk stream
for (const record of Synx.streamSynxl(text)) console.log(record.values.id);
for await (const record of Synx.streamSynxlFile('chat.synxl')) console.log(record.values.id);

// From disk
const fromDisk = Synx.loadSynxlSync('chat.synxl');   // or: await Synx.loadSynxl('chat.synxl')

// Writing (§14) and opt-in validation (§8.4)
Synx.writeSynxl([{ id: 1, messages: [{ role: 'user', content: 'Hi' }] }]);
Synx.parseSynxl(text, { validate: true }).diagnostics;

# Python — synx_native
import synx_native as synx

doc = synx.synxl_parse(text)
doc.version                      # 1
len(doc)                         # 2
doc.records[0]["id"]             # 1 — records are plain dicts
doc.records[0]["messages"]       # [{'role': 'system', 'content': '…'}, …]
doc.diagnostics                  # list of dicts — §11.2
doc.to_json(); doc.to_ndjson()   # §12.1 / §12.2

doc = synx.synxl_load("chat.synxl")

# Streaming — one record in memory at a time
for record in synx.synxl_stream(text): ...
for record in synx.synxl_stream_file("chat.synxl"): ...

# The *_records variants yield SynxlRecord objects instead of bare dicts
for record in synx.synxl_stream_records(text):
    print(record.index, record.line, record["id"], record.diagnostics)

# Writing (§14) and opt-in validation (§8.4); hard errors raise synx.SynxlError
synx.synxl_write(records, fields=["id", {"name": "messages", "block": True}])
synx.synxl_parse(text, validate=True).diagnostics

# CLI — every input is streamed, so memory stays at one record
synx synxl parse chat.synxl                    # canonical JSON array (§12.1)
synx synxl parse chat.synxl --format ndjson    # one object per line (§12.2)
synx synxl validate chat.synxl --strict        # exit 0 ok · 1 spec violation · 2 I/O failure
synx synxl convert chat.synxl --to jsonl       # also: --to csv --block-json
synx synxl convert data.jsonl --to synxl       # jsonl→synxl and csv→synxl too
synx synxl split chat.synxl -n 10000 --output-dir shards/

Implementation status

SYNXL is currently implemented in Rust, TypeScript, Python, and the CLI. The native parsers under parsers/ read SYNX 3.7 — including |+ — but do not read .synxl.

See it in action

Writing data — clean and simple

Just key, space, value. No quotes, no commas, no braces:

!active Mode

Add !active on the first line and your config comes alive — with logic built right into the format:

Features

This extension provides complete SYNX v3.6 language support for Visual Studio Code:

Commands

All commands also available via right-click context menu on .synx and .json files.

CLI (Rust)

A single native binary for all platforms, built on synx-core:

# Install from source
cargo install --path crates/synx-cli

# Parse → JSON
synx parse config.synx

# Validate (exit 1 on errors)
synx validate config.synx --strict

# Convert JSON → SYNX
synx convert data.json --format synx

# Parse !tool call
synx tool call.synx

# Compile / decompile binary .synxb
synx compile config.synx
synx decompile config.synxb

# Structural diff
synx diff old.synx new.synx

# Query by dot-path (supports array indices)
synx query server.host config.synx

# Canonical formatting
synx format config.synx --write

# SYNXL datasets (.synxl) — streamed, memory stays at one record
synx synxl parse chat.synxl --format ndjson
synx synxl validate chat.synxl --strict
synx synxl convert chat.synxl --to jsonl
synx synxl split chat.synxl -n 10000 --output-dir shards/

Language Server (LSP)

synx-lsp is a standalone Language Server that speaks LSP over stdio, built on tower-lsp-server + synx-core. One binary serves every editor:

Capabilities: real-time diagnostics (15 checks), completion (markers, constraints, directives), document symbols (outline tree).

cargo install --path crates/synx-lsp

Full editor matrix: crates/synx-lsp/README.md.

Claude & MCP

Use docs/anthropic/claude.md to connect Claude Desktop (or any MCP client) to integrations/mcp/synx-mcp — validate / parse / format .synx from the agent without guessing syntax.

GitHub Action

Validate .synx files in CI:

- uses: ./.github/actions/synx
  with:
    files: 'config/**/*.synx'
    strict: true

See .github/actions/synx/action.yml for all inputs.

Tree-sitter

Syntax highlighting for Neovim, Helix, Zed, Emacs — and future GitHub code rendering:

cd tree-sitter-synx
npm install && npx tree-sitter generate

See tree-sitter-synx/README.md. Queries live in tree-sitter-synx/queries/ (highlights.scm, folds.scm).

Fuzzing

Three cargo-fuzz targets exercise the parser, binary codec, and formatter:

cd crates/synx-core
cargo +nightly fuzz run fuzz_parse -- -max_total_time=60

In practice we’ve run fuzz_parse at scale (≈ 50M executions across a large corpus); the parser/engine held up after fixing a single root-cause formatting panic.

See crates/synx-core/fuzz/README.md and the checked-in coverage report at crates/synx-core/fuzz/coverage/fuzz_parse/html/.

Architecture (VS Code extension)

Source: integrations/vscode/synx-vscode/. The extension is zero-dependency — no external runtime, no native modules. Everything runs as pure TypeScript inside VS Code:

integrations/vscode/synx-vscode/src/
├── extension.ts      # Entry point — registers all providers
├── parser.ts         # AST-like parser with position info (SynxNode, ParsedDoc)
├── diagnostics.ts    # 15 diagnostic checks with severity levels
├── completion.ts     # IntelliSense (12 markers, 7 constraints, types, hover)
├── navigation.ts     # Document symbols, Go to Definition, Find References
├── formatter.ts      # Formatting provider (2-space indent, trim)
├── commands.ts       # Convert, Freeze, Preview commands
├── colors.ts         # Color provider (#hex inline swatches)
└── inlay-hints.ts    # Inlay hints for :calc results

Diagnostics

The extension validates your .synx files in real time:

Performance

SYNX v3.6 uses a unified Rust core with native bindings. Real benchmark results on a 110-key config (2.5 KB):

Rust (criterion, direct)

Node.js (50K iterations)

Python (10K iterations)

SYNX parses 67× faster than YAML in Python. In Node.js, the pure TS parser matches Rust direct speed at ~39 µs.

LLM SYNX Format Compatibility

How well different LLM models understand and work with SYNX format:

Parsing & Generation Tests

We benchmark how well LLMs can:

• Parse: Read SYNX format and convert to JSON
• Generate: Create SYNX from English descriptions

Test corpus now has 250 total cases:

• 125 parsing tests (SYNX -> JSON)
• 125 generation tests (Description -> SYNX)

What is inside the test texts:

• Parsing texts include simple key-value pairs, nested blocks (2-4 levels), arrays, mixed scalar types, null values, comments (//, /* */), strings with spaces, and configuration-like documents (service/database/deployment shapes).
• Generation prompts include practical tasks: app/service configs, ports, replicas, regions, booleans, arrays of features, and nested objects with explicit required fields.
• Many cases are near-duplicates with controlled value changes (names, numbers, ports, regions) to test consistency instead of single-shot luck.
• Expected outputs are checked structurally: exact JSON equality for parsing tests and required token/key presence for generation tests.

Example compatibility snapshot (illustrative):

gemini-2.0-flash
→ Parsing      ████████████████████  100.0% (125/125)
→ Generation   ████████████████████  100.0% (125/125)

claude-opus
  Parsing      ███████████████████░   96.0% (120/125)
  Generation   ██████████████████░░   88.0% (110/125)

claude-sonnet
  Parsing      ██████████████████░░   90.4% (113/125)
  Generation   ████████████████████  100.0% (125/125)

gemini-1.5-pro
  Parsing      ███████████████████░   96.0% (120/125)
  Generation   ██████████████████░░   88.0% (110/125)

gpt-4o
  Parsing      ██████████████████░░   90.4% (113/125)
  Generation   ██████████████████░░   88.0% (110/125)

claude-haiku-4-5
  Parsing      ████████████████░░░░   80.0% (100/125)
  Generation   ███████████████░░░░░   76.0% (95/125)

Failed Test Analysis (Typical LLM Errors)

Analysis of failed cases (usually the remaining 4-12%) shows that errors are mostly caused by cross-format habits from YAML/JSON/TOML, not by SYNX complexity itself.

1. Syntactic Interference Problem: the model hallucinates : after keys and adds unnecessary quotes in YAML/JSON style. Example: server host localhost becomes server: host: "localhost".

2. Indentation Flattening Problem: nested SYNX blocks are flattened into one level, which breaks the structure. Example: database -> connection -> port is emitted as sibling top-level keys.

3. Array Shape Drift Problem: arrays are rewritten using another format (- item, JSON-like lists with quotes/commas, or mixed syntax).

4. Type Coercion Bias Problem: true, 42, 3.14, and ~ are sometimes interpreted as strings instead of bool/number/null depending on prompt wording.

5. Marker/Template Normalization Problem: SYNX-specific constructs are "normalized" into familiar syntax and lose their intended semantics.

6. Over-Helpful Rewriting Problem: the model adds wrappers, comments, and readability edits that fail strict structural validation.

Run Your Own Benchmarks

Test any LLM against SYNX format. See benchmarks/llm-tests/README.md for details:

cd benchmarks/llm-tests
pip install -r requirements.txt

# Set your API keys (one time setup)
export ANTHROPIC_API_KEY=your_key
export GOOGLE_API_KEY=your_key
export OPENAI_API_KEY=your_key

# Run full benchmark suite
python llm_benchmark.py

# Format and pretty-print results
python format_results.py llm_results.json

See benchmarks/llm-tests/GUIDE.md for advanced options and detailed results interpretation.

Install (v3.7)

One-line installs (published names):

npm install @aperturesyndicate/synx-format
pip install synx-format
cargo add synx-core    # or: cargo add synx-format
cargo install synx-cli --locked   # CLI binary: synx

# C# / .NET 8 — NuGet (package ID is not Synx.Core; that ID is taken on nuget.org)
dotnet add package APERTURESyndicate.Synx
# Browse: https://www.nuget.org/packages/APERTURESyndicate.Synx

Until APERTURESyndicate.Synx appears on nuget.org, consume the library from this repo: dotnet add reference parsers/dotnet/src/Synx.Core/Synx.Core.csproj, or dotnet pack parsers/dotnet/src/Synx.Core/Synx.Core.csproj -c Release -o artifacts/nuget and add artifacts/nuget as a local feed. Details: parsers/dotnet/README.md.

Maintainer: publish C# to NuGet

dotnet pack parsers/dotnet/src/Synx.Core/Synx.Core.csproj -c Release -o artifacts/nuget then dotnet nuget push "artifacts/nuget/APERTURESyndicate.Synx.*.nupkg" -k "$env:NUGET_API_KEY" -s https://api.nuget.org/v3/index.json --skip-duplicate. Clear stale *.nupkg in artifacts/nuget before pack; push only APERTURESyndicate.Synx.*.nupkg.

Ready to git push or ship?

• Run quality checks when you change core behavior: scripts/verify-release-quality.ps1 / scripts/verify-release-quality.sh as appropriate.
• Do not commit secrets (NUGET_API_KEY, PyPI tokens); artifacts/ is gitignored.
• For a new NuGet version, bump Version in parsers/dotnet/src/Synx.Core/Synx.Core.csproj, then run the dotnet pack + dotnet nuget push pair above.

API Parity (v3.7)

Unified API surface across runtimes. Since 3.6.3, C++, Dart, Go, Java, and Swift ship as native from-scratch parsers under parsers/ (no synx-c / libsynx runtime dependency); bindings/ is reserved for surfaces that still need to call into the Rust engine via FFI/WASM.

Native parsers — parsers/ and crates/

FFI / bridge bindings — bindings/

Behavior notes:

• The tables above cover the SYNX API. SYNXL (.synxl) is a separate surface, currently implemented only in synx-core, the CLI, packages/synx-js, and bindings/python — see Implementation status.
• Browser WASM runs without host filesystem/env integration by default.
• C FFI, Kotlin/JVM (JNA), and WASM stringify use JSON strings at the boundary for stable cross-language interop.
• This table documents API compatibility only; it does not change parser performance characteristics.

Quick SYNX Syntax Reference

Basic (always works)

# Key-value pairs (first space separates key from value)
name John
age 25
phrase I love programming!

# Nesting (2-space indent)
server
  host 0.0.0.0
# Lists
inventory
  - Sword
  - Shield

# Type casting
zip_code(string) 90210
# Multiline text — `|` joins lines, trimming each one
description |
  This is a long text
  that spans multiple lines.

# Multiline text — `|+` keeps indentation relative to the first line (3.7)
prompt |+
  Outline:
    - step one
    - step two
  End.

# Comments
# hash comment
// slash comment

Markers (require !active)

!active

port:env PORT
port:env:default:8080 PORT
boss_hp:calc base_hp * 5
greeting:random
  - Hello!
  - Welcome!
loot:random 70 20 10
  - common
  - rare
  - legendary
support_email:alias admin_email
api_key:secret sk-1234567890
tags:unique
  - action
  - rpg
  - action
database:include ./db.synx
theme:default dark
greeting:template Hello, {first_name} {last_name}!
colors:split red, green, blue
csv:join
  - a
  - b
  - c
currency:geo
  - US USD
  - EU EUR
prompt_block:prompt:AppConfig
  app_name MyCoolApp
  version 2.1.0
ref_value:ref:calc:*2 base_rate
label:i18n
  en Hello
  ru Привет
volume:clamp:0:100 150
price:round:2 19.999
price:format:%.2f 19.9
result:map:status_labels
  - 200
  - 404
instance_id:once:uuid
app_ok:version:>=:1.0.0 1.2.3
flags:watch ./flags.synx
config:fallback:./defaults.synx ./overrides.synx
api:spam:5:60 https://api.example.com
banner:vision ./sunset.png
recording:audio ./welcome.mp3
db:import ./config/db.synx
production:inherit base
  host prod.example.com
shouted:replace:l:L Hello there
ranked:sort:desc
  - 5
  - 1
  - 3
total:sum
  - 19.99
  - 29.99
  - 5.50

Constraints (require !active)

!active

volume[min:1, max:100] 75
api_key[required]:env API_KEY
max_players[type:int] 16
country_code[pattern:^[A-Z]{2}$] US
version[readonly] 3.0.0
password[required, min:8, max:64, type:string] MyP@ssw0rd

LLM Tool Use (!tool) ⚡NEW

!tool
web_search
  query latest Rust release
  lang en
  max_results 5

→ { "tool": "web_search", "params": { "query": "latest Rust release", "lang": "en", "max_results": 5 } }

Combine with !schema for tool definitions, or with !active for dynamic parameters. See GUIDE.md for full documentation.

📖 Documentation / Guides

Complete SYNX guides with all 28 markers, benchmarks, code examples, and architecture:

🔒 Security

SYNX is designed to be safe by default — no code execution, no eval, no network calls from the parser.

What SYNX does NOT do

Built-in protections (v3.5.0+)

Configuration

// JS/TS
Synx.parse(text, { maxIncludeDepth: 32 }); // default: 16

// Rust
Options { max_include_depth: Some(32), ..Default::default() }

Full Specification

• SPECIFICATION_EN.md (English)
• SPECIFICATION_RU.md (Russian)

How this repo is organized: docs/repository-layout.md.

Links

• GitHub Repository
• npm — @aperturesyndicate/synx-format
• PyPI — synx-format
• crates.io — synx-core
• APERTURESyndicate

MIT — © APERTURESyndicate