Welcome to the succinctly documentation! This page helps you find what you need.
Succinctly uses semi-indexing to process JSON, YAML, and CSV/TSV files with dramatically less memory than traditional parsers:
| vs Traditional Parsers | Memory | Speed |
|---|---|---|
| vs serde_json, simd-json | 18-46x less memory | 3-5x faster |
| vs jq (JSON queries) | 5-25x less memory | 1.2-6.3x faster |
| vs yq (YAML queries) | similar memory | 16-40x faster |
How it works: Instead of building a full DOM tree, succinctly builds a lightweight structural index (~3-6% overhead) and extracts values lazily only when accessed. This is ideal when queries touch a small fraction of the document.
See architecture/semi-indexing.md for technical details, or benchmarks/ for full performance data.
Start here: Getting Started Guide
Learn the basics:
Using succinctly in your Rust project:
Want to contribute?
- CONTRIBUTING.md - Start here
- Developer Guide - Codebase architecture and workflow
- Release Guide - Release process (for maintainers)
Optimizing performance:
- Optimization Techniques - 11 comprehensive guides
- Quick Reference - One-page technique lookup table
- Benchmarks - Performance comparisons vs other tools
Understanding internals:
- Architecture - Design decisions and core concepts
- Architecture Decisions - ADRs: why key designs were chosen, and what was rejected
- Parsing Implementation - JSON/YAML/DSV parser internals
- Reference - jq and yq language documentation, environment variables
- Implementation Plans - Feature planning documents
- CLAUDE.md - Comprehensive guide for AI assistants
Quick tutorials for new users. Start here if you've never used succinctly.
Practical how-to documentation:
- API usage (api.md)
- CLI tool (cli.md)
- Development (developer.md)
- Releases (release.md)
Design documentation:
- Core concepts (BitVec, BalancedParens, semi-indexing)
- Module structure
- Implementation decisions
Architecture Decision Records:
- Core design choices (semi-indexing, PFSM JSON parser, YAML oracle)
- Rejected optimizations (why P2.6/P2.8/P3/P5/P6/P7/P8 were not adopted)
- Status-tracked, one decision per record
Parser implementation details:
- JSON semi-indexing
- YAML parser with P0-P10 optimizations
- DSV (CSV/TSV) parsing
Performance optimization techniques:
- 11 comprehensive technique guides
- Decision framework
- Successes AND failures documented
Performance comparisons:
- vs jq (JSON queries)
- vs yq (YAML queries)
- vs Rust JSON parsers (serde_json, sonic-rs, simd-json)
- Cross-language parser comparisons
- DSV performance
Implementation plans for major features (all implemented).
Specification compliance documentation:
- YAML 1.2 - type handling, Norway problem, booleans
- YAML Known Limitations - YAML Test Suite conformance, unsupported features, why validation is opt-in
- jq Known Limitations - jq error-message conformance against pinned jq, and the behaviour gaps behind the rest
I want to...
- Install and try succinctly -> getting-started/
- Use BitVec or BalancedParens -> guides/api.md
- Query JSON files -> guides/cli.md
- Query YAML files -> guides/cli.md
- Configure an environment variable -> reference/environment-variables.md
- Understand YAML 1.2 type handling -> compliance/yaml/1.2.md
- Know what the YAML parser does not support -> compliance/yaml/limitations.md
- Know where jq error messages diverge -> compliance/jq/limitations.md
- Understand how JSON indexing works -> parsing/json.md
- See YAML optimization journey -> parsing/yaml.md
- Learn SIMD techniques -> optimizations/simd.md
- Compare performance -> benchmarks/
- Contribute code -> CONTRIBUTING.md + guides/developer.md
- Release a new version -> guides/release.md
- Understand why AVX-512 was rejected -> optimizations/history.md
Found a typo or want to improve docs? See CONTRIBUTING.md.
Documentation follows these conventions:
- US spelling (optimize, not optimise)
- Breadcrumbs at top of nested docs
- Links use descriptive text (not "click here")
- Code examples are tested and runnable