synx-format 3.7.3

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

Surface	SYNX 3.7 (incl. |+)	SYNXL 1
Rust core (synx-core), CLI (synx synxl)	✅	✅
TypeScript (@aperturesyndicate/synx-format)	✅	✅
Python (synx_native)	✅	✅
C++, Dart, .NET, Go, Java, Swift (parsers/), Godot/GDScript	✅	❌ not yet
Node native, WASM, C FFI, Kotlin, Mojo (bindings/)	✅	❌ not yet

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:

Feature	Description
Syntax Highlighting	Keys, values, markers, constraints, comments, types, template placeholders, colors
IntelliSense	Autocomplete for 28 markers, 7 constraints, type casts, template keys, alias keys
Hover Info	Documentation on markers, constraints, !active, key types and values
Diagnostics	Real-time validation: tabs, indentation, duplicate keys, unknown markers, broken refs
Go to Definition	Ctrl+Click on :alias, :template {ref}, :calc variable names, :include file paths
Find References	Find all usages of any key across :alias, :template, :calc
Document Outline	Full symbol tree in the Outline panel and breadcrumbs
Formatting	Normalize indentation (2 spaces), trim whitespace, fix tabs
Color Preview	Inline color swatches for #hex values (3/4/6/8-digit)
Inlay Hints	Computed :calc results shown inline as = 500
Live Preview	Side panel with real-time parsed JSON output
Convert	SYNX → JSON and JSON → SYNX conversion commands
Freeze	Resolve all !active markers into a static .synx
Context Menus	Right-click on .synx / .json files in Explorer or Editor

---

Commands

Command	Shortcut	Description
SYNX: Convert to JSON	Ctrl+Shift+P → type	Parse .synx → save .json alongside it
SYNX: Convert JSON → SYNX	Ctrl+Shift+P → type	Parse .json → save .synx alongside it
SYNX: Freeze	Ctrl+Shift+P → type	Resolve all markers → save .static.synx
SYNX: Preview	Ctrl+Shift+P → type	Open live side panel with parsed JSON

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:

Editor	Setup
Neovim	vim.lsp.start({ cmd = { "synx-lsp" }, filetypes = { "synx" } })
Helix	Add to languages.toml: [language-server.synx-lsp] command = "synx-lsp"
Zed	Settings → Language Servers → add synx-lsp binary path
Emacs	(lsp-register-client (make-lsp-client :new-connection (lsp-stdio-connection '("synx-lsp"))))
JetBrains	Settings → Languages & Frameworks → LSP → add synx-lsp

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:

Check	Severity	Description
Tab characters	Error	SYNX uses spaces, not tabs
Odd indentation	Warning	Indentation should be a multiple of 2
Invalid key start	Error	Keys cannot start with -, #, /, !
Duplicate keys	Warning	Same key at the same indent level
Unknown type cast	Error	Only int, float, bool, string allowed
Unknown marker	Warning	Not one of the 28 known markers
Markers without !active	Info	Markers only work in active mode
:alias broken ref	Error	Referenced key doesn't exist
:calc unknown var	Warning	Variable in expression not defined
:include file missing	Error	Included file not found
:template missing key	Warning	{placeholder} key not found
Constraints without !active	Info	Constraints only work in active mode
Unknown constraint	Warning	Not one of the 7 known constraints
min/max non-numeric	Error	Min/max values must be numbers
enum invalid value	Error	Value not in allowed list

---

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)

Benchmark	Time
Synx::parse (110 keys)	~39 µs
parse_to_json (110 keys)	~42 µs
Synx::parse (4 keys)	~1.2 µs

Node.js (50K iterations)

Parser	µs/parse
JSON.parse (3.3 KB)	6.08 µs
synx-js pure TS	39.20 µs
js-yaml (2.5 KB)	82.85 µs
synx-native parseToJson	86.29 µs
synx-native parse	186.84 µs

Python (10K iterations)

Parser	µs/parse
json.loads (3.3 KB)	13.04 µs
synx_native.parse (2.5 KB)	55.44 µs
yaml.safe_load (2.5 KB)	3,698 µs

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/

Implementation	parse	parse_active	parse_tool	stringify	format	compile	decompile	diff	Notes
Rust core (synx-core)	✅	✅	✅	✅	✅	✅	✅	✅	Canonical reference; full Options
CLI (synx)	✅	✅	✅	✅	✅	✅	✅	✅	synx parse, synx diff, synx query, …
JavaScript / TypeScript (packages/synx-js)	✅	✅	✅	✅	✅	✅	✅	✅	Pure TypeScript — npm @aperturesyndicate/synx-format
C++17 (parsers/cpp)	✅	✅	✅	✅	✅	✅	✅	✅	CMake project; synx_tests.exe 42 / 42
Dart 3 (parsers/dart)	✅	✅	✅	✅	✅	✅	✅	✅	Pure Dart; dart test 37 / 37
C# / .NET 8 (parsers/dotnet)	✅	✅	✅	✅ (ToJson)	✅	✅	✅	✅	NuGet APERTURESyndicate.Synx
Go (parsers/go)	✅	✅	✅	✅	✅	✅	✅	✅	Pure Go (no cgo); go test ./... clean
Java 17 (parsers/java)	✅	✅	✅	✅	✅	✅	✅	✅	Maven com.aperturesyndicate:synx
Swift 5 (parsers/swift)	✅	✅	✅	✅	✅	✅	✅	✅	SwiftPM Synx, no FFI
GDScript / Godot 4 (integrations/godot/synx-gdscript)	✅	✅	✅	✅	✅	✅	✅	✅	Pure GDScript editor plugin; ships as a Godot addon

FFI / bridge bindings — bindings/

Binding	parse	parse_active	parse_tool	stringify	format	compile	decompile	diff	Notes
Python (synx_native, bindings/python)	✅	✅	✅	✅	✅	✅	✅	✅	PyO3 over synx-core
Node native (bindings/node)	✅	✅	✅	✅	✅	✅	✅	✅	N-API; pure TS lives in packages/synx-js
WebAssembly (bindings/wasm)	✅	✅	✅	✅	✅	✅	✅	✅	Browser/edge target of the Rust engine
C FFI (bindings/c-header)	✅	✅	✅	✅	✅	✅	✅	✅	Reference C ABI (synx.h)
Kotlin/JVM (bindings/kotlin)	✅	✅	✅	✅	✅	✅	✅	✅	JNA over synx-c; JVM users on Java can use parsers/java directly
Mojo (bindings/mojo)	✅	✅	✅	✅	✅	✅	✅	✅	Wraps CPython synx_native; experimental

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:

Language	Guide
🇬🇧 English	GUIDE.md

🔒 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

Risk	SYNX	YAML
Code execution from config	No — no !!python/object, no eval, no constructors	Yes — !!python/object/apply can execute arbitrary code
Network/HTTP calls	No — parser is offline-only	Depends on loader
Shell command injection	No — :calc uses a safe recursive-descent parser with whitelist operators (+ - * / %)	Depends on loader

Built-in protections (v3.5.0+)

Protection	Description
Path jail	:include, :import, :watch, :fallback paths cannot escape the project's base directory. Absolute paths, Linux-rooted /foo, Windows-rooted \foo and ../ traversal are all blocked (3.6.2 closed a Windows-only escape).
Include depth limit	Nested includes are limited to 16 levels (configurable). Prevents infinite recursion.
File size limit	Included files > 10 MB are rejected. Prevents memory exhaustion.
Calc expression limit	Expressions longer than 4096 characters are rejected.
Env isolation	When env option is provided, only that map is used — no fallthrough to process.env.
Secret redaction	Values marked :secret are emitted as "[SECRET]" in JSON output of every binding (synx parse, Synx.toJSON, FFI, WASM). Real values are accessible only via the typed Value::Secret API. Fixed in 3.6.2 — earlier versions of the Rust CLI leaked the raw value.
Resource limits everywhere	The pure-TS engine now enforces the same §3 caps as synx-core (16 MiB input, 128 nesting depth, 1 MiB multiline, 1 M list items, …). Browser/Node use is no longer DoS-able by oversized input.

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

---