A graph specification a machine can check.
TRUGS is a JSON graph format for structured information, and it comes with sixteen validation rules and a reference validator. A graph either satisfies CORE or it does not — the answer is mechanical, and it is the same answer for everyone who asks. The same artifact is also a sentence: TRUGS/L is its human-readable rendering, and the two are one thing written two ways.
A TRUG is a JSON file. Nodes are typed things — functions, pages, chapters, tasks, parties. Edges are named relationships between them. Hierarchy organizes them by parent and child containment, using metric levels as the transition markers.
The specification is the repository. There is nothing to install in order to read it: the Markdown specs and the .trug.json files are the normative text.
The sentence is the program. The graph is the AST. They are one artifact in two renderings.
trug trl command family.TRUGS-TRL and TRUGS-LAW are coming after this release. The payment-schedule example joining TRL and the calculator is coming after this release.
This is the most important thing about TRUGS. A format anyone can interpret differently is a suggestion; a format with a decision procedure is a contract. Conformance here is decidable — sixteen rules, run mechanically, returning one answer.
That single property is what everything else rests on. You can gate on it, so nothing runs until it passes. You can accept a graph from someone you do not trust, because you can check it yourself. You can put it in CI and fail the build when a graph drifts from what it describes.
Those are the nine core structural rules; seven compositional rules complete the sixteen. SPEC_validation.md carries the structural rules, a reference implementation and an error-code reference; CORE defines the compositional rules.
TRUGS and TRUGS/L say the same thing. They are not two languages — they are one artifact in two renderings. The graph is what a machine reads; the sentence is what a person reads. Either can be produced from the other.
TRUG/L is a formalized subset of English drawn from computation, law, and the SI prefixes. Every word is in the vocabulary; nothing outside it parses.
PARTY system SHALL FILTER ALL ACTIVE RECORD THEN SORT RESULT THEN WRITE RESULT TO ENDPOINT output OR RETRY BOUNDED 3 WITHIN 60s.
Because a person has to read it, TRUG/L allows sugar: tokens matching the 'word pattern, which are stripped before parsing. They carry no meaning and appear nowhere in the graph. They exist so a sentence can read like a sentence.
NO PARTY SHALL WRITE CONFIDENTIAL RESOURCE
EXCEPT PARTY owner MAY WRITE CONFIDENTIAL RESOURCE
PROVIDED_THAT PARTY owner AUTHENTICATE TO SERVICE auth.NO PARTY SHALL WRITE CONFIDENTIAL RESOURCE
EXCEPT PARTY owner 'who MAY WRITE 'such CONFIDENTIAL RESOURCE
PROVIDED_THAT PARTY owner 'who AUTHENTICATE TO SERVICE auth.→ both compile to identical graphs
CORE defines the universal structure every TRUG must satisfy — the boundaries, the primitive classes, the validation rules, and the composition type system. It does not change without a spec revision.
BRANCHES define domain-specific vocabularies on top of it. Medical, financial, legal, robotics — whatever your domain needs that CORE does not already carry.
All of it lives in the repository, versioned with the spec. language.trug.json is the opening TRUG — the language defining itself.
| Document | Contents |
|---|---|
| CORE.md | Boundaries, primitive classes, the 16 validation rules, composition type system |
| BRANCHES.md | Domain vocabularies — Python, Web, Writer, Knowledge and others |
| SPEC_fundamentals.md | Core concepts and structure |
| SPEC_validation.md | Validation rules, with implementations |
| SCHEMA.md | JSON schema reference |
| SPEC_vocabulary.md | The 233 words, 9 parts of speech, formal definitions |
| SPEC_grammar.md | BNF grammar and composition rules |
| SPEC_examples.md | 30 parsed examples |
| CHEATSHEET.md | The vocabulary at a glance |
| language.trug.json | The opening TRUG — the language defining itself |
trugs-tools 2.4.0 provides the trug CLI: validation, TRL compile and decompile, graph CRUD and compliance checking. trugs-store 2.2.0 is the shared graph storage layer. trugs-web 2.1.0 describes folders as graphs and queries them. The language and describe tools require Python 3.11 or later.
TRUGS-AGENT is the onboarding kit. Its installer, trugs-agent 2.0.0, places the entry instructions in your project. Install the kit and run its check.
After installing, inspect the language commands:
trug --help trug trl --help
Both commands print usage and available subcommands, then exit with status 0.
Sample TRUGs at varying complexity in the EXAMPLES directory. The repository carries examples to inspect and validate.
folder.trug.json at the repository root is a machine-readable index: every top-level folder, every reference document and every public tool has a node, with typed edges to the specs it implements or describes.
CI checks the repository on every push and pull request. The section list in the README, the specification index, and the tool table all correspond to nodes you can traverse programmatically — and when the graph drifts from the prose or the filesystem, the build fails.
CORE and the language are maintained by TRUGS LLC. The vocabulary, grammar and validation rules are the specification; they do not change without a spec revision.
Branches are where everyone else builds — domain vocabulary layered on CORE for medicine, finance, law, robotics, or whatever CORE does not already carry.
That last step is the one people skip, and it is the one that matters. The division is fixed:
Node identity, edge validity, hierarchy, metric ordering, declared dimensions, required fields, field types, declared extensions, level format.
Universal · unchanged without a spec revision
Whether your domain's vocabulary is used correctly — that an operation spec declares the capability it needs, that your types carry what your domain requires.
Yours to write · yours to maintain
Every TRUG passes CORE validation regardless of branch — so CORE passing is not your branch passing. A branch that ships no validator produces graphs that are structurally sound and semantically unchecked, which forfeits, for your domain, the one property the specification exists to provide.
You don't need permission. Build it, use it, share it.
Once enough people use a branch in the same domain, it can be formalized into the specification through the community. Implementations in any language are welcome — read, write, validate or execute TRUGs however you like. The spec is the contract.
The specification and its reference tools are released under the Apache License 2.0. The standard is stewarded by TRUGS LLC, which maintains CORE and the language and holds the specification neutral of any one implementer.
The published record is DOI 10.5281/zenodo.19379454.
trugs-tools, the trug binaryOne owner holds both TRUGS LLC and Arek Starr LLC. Arek Starr LLC is the only company building TRUGS. TRUGS LLC’s open material needs no Arek Starr LLC product.