This repository contains a documentation-first specification for a compact binary format for structured data.
The format is intended to remain easy to use in schema-less workflows while targeting materially smaller output than plain MessagePack when repeated structure, repeated strings, homogeneous arrays, batching, or session reuse is present.
Twilic is named after Old English twilic, the root of the modern word twill.
Twill is a weave built from repeated threads, often forming a diagonal pattern. The name reflects Twilic's core idea: repeated data shapes, keys, and values should not be sent again and again as independent structures, but woven together into a compact binary representation.
In other words, Twilic treats structured data less like isolated messages and more like a fabric of recurring patterns.
The etymology follows Merriam-Webster, which traces twill to Old English twilic (“having a double thread”).
- reduce repeated object-key overhead
- support schema-aware compact encoding when schemas are available
- support learned structure in dynamic mode
- support row-wise, schema-aware columnar, and stateful compression strategies
- keep deterministic wire behavior within a fixed profile
- replacing every existing JSON or binary protocol
- defining application semantics
- mandating a single transport handshake for every deployment
twilic/
├ README.md
├ LICENSE
├ CONTRIBUTING.md
├ SPEC.md
├ docs/
│ ├ format.md
│ ├ encoding.md
│ └ transport.md
├ versions/
│ ├ v1.md
│ ├ v2.md
│ └ v3.md
├ examples/
│ ├ README.md
│ ├ basic.json
│ └ schema-example.json
├ diagrams/
│ ├ protocol-flow.md
│ └ encoding-structure.md
├ .editorconfig
├ .gitignore
├ .markdownlint.jsonc
├ .prettierrc.json
└ package.json
SPEC.mdfor the core model and format overview.docs/format.mdfor top-level kinds, object forms, batches, patches, and resets.docs/encoding.mdfor scalar rules, vector codecs, string modes, and compression.docs/transport.mdfor session-scoped state and transport assumptions.versions/v3.mdfor the compact schema-aware interoperability profile.examples/anddiagrams/for small concrete artifacts.
This repository includes profiles in versions/.
versions/v2.mdrecords the previous interoperability profile.versions/v3.mdrecords the schema-aware compact profile for Bound compact record-body bit groups,BOUND_STREAM,SCHEMA_BATCH, and fast-path requirements.
This repository is distributed under CC-BY-4.0. See LICENSE for the full license text.