GSL

The source of truth for the graphs behind your diagrams.

Architecture diagrams go stale. Not because drawing is hard — because the picture becomes the thing everyone maintains, while the information it represents has no authoritative home. Change a service boundary and you edit N diagrams by hand; "what breaks?" gets answered by gut feel.

GSL makes the graph itself the source of truth — a canonical, diffable text format for graph-shaped knowledge (architectures, dependencies, workflows, organisational and relationship structures), kept in version control like any other source. Every diagram, subset, report or analysis is a view derived from that one graph:

One graph, many views. The diagram is a view; the graph is the asset.

graph in Git
   ├── architecture diagram
   ├── team view
   ├── blast radius
   ├── dependency report
   └── or consumed directly by other tooling

Renderers like Mermaid, D2 and Graphviz draw one view extremely well. GSL is for the different case: the graph is the durable asset, the views are many, and they are derived from one source — in sync by construction rather than by discipline. A diagram is one possible consumer of that graph, not the reason it has to exist: the same structure can feed a report, a CI check or a language model directly, with no picture involved.

Status: looking for early feedback. The implementation and specification are mature and heavily tested; the idea itself is experimental, young and unproven in the real world — whether this model genuinely helps people remains an open question. Evaluate it on its merits; Project status is the honest detail.

---

Try it in 30 seconds

Suppose you model a small retail platform. One file, model.gsl, is the whole story:

set critical

node gateway [team="gateway"] @critical
node orders [team="orders"] @critical
node orders_db [text="PostgreSQL", team="platform"] @critical
node payments [team="payments"]
node users [team="identity"]

gateway -> orders [protocol="http"]
orders -> payments [protocol="grpc"]
orders -> users [protocol="grpc"]
orders -> orders_db [protocol="sql"]

Now ask the graph a question: "If we retire orders, which @critical parts are affected?"

(subgraph node.id == "orders" traverse in all) as BLAST | from * | (subgraph node in @critical) as CRIT | BLAST & CRIT

Read the pipeline left to right: BLAST grabs everything that transitively depends on orders; CRIT isolates the @critical nodes; the & keeps only what appears in both. The answer comes back as canonical, diffable GSL:

set critical

node gateway [team="gateway"] @critical
node orders [team="orders"] @critical

gateway->orders [protocol="http"]

Retiring orders breaks the @critical gateway — a fact you derived from the model, not from gut feel. Re-run it any time the model changes; the answer stays in sync. If the diagram were the source of truth, that is a trail you'd trace by eye across every outdated picture in your wiki.

This is the whole idea. Everything below shows it at scale.

---

Why GSL?

Every picture is an output. GSL makes the graph the first-class thing you keep: questions about your system become queries, and all the pictures you need are re-derived, not re-drawn:

• A component diagram for each audience
• The blast radius of retiring a service
• A per-team dependency view
• A migration backlog for deprecated components
• A text report consumed by other tooling

The same graph answers all of them. Nothing to hand-maintain.

Concretely, GSL gives you:

• Truth you can diff. Deterministic serialisation means small, reviewable diffs in git — a PR that renames a dependency is one line, not a picture you redraw.
• Answers, not eyeballing. Ask "what depends on this?" and get a canonical subgraph back, not a path traced by a human.
• One source, many views. Derive whatever subset, summary or diagram you need from a single graph — no duplicated structure, no drift.
• Relationships between relationships. Edges can declare dependencies on other edges (a promotion that waits on an approval), so workflow prerequisites are data, not a hand-drawn arrow.
• Structure without a schema. Carry arbitrary attributes (team, protocol, owner, confidence) and query on them. No schema step, no database to stand up.
• Text, not a picture. The structure is plain text: a PR can review it, CI can check it, other tooling can consume it — and when a language model needs to understand a system, the graph itself is what it reads, not an image of it.

Honest boundaries: GSL is a file format and a derivation tool. It does not do graph layout, schema validation, persistence or database-scale querying — and it does not try to. See Project status and Compared with alternatives for where that is a feature and where someone else is the better fit.

---

What can I use it for?

GSL is a graph language. It is not software-only: the same text format, query language and derived views describe financial networks, organisational structures and any other relationship-shaped knowledge. Whatever the domain, the point is the same: the graph is the asset; the views are derived.

---

Flagship examples

Five complete, runnable narratives — problem → model → query → derived view — each with a two-minute test you can run. They are the best place to understand why GSL exists, end to end. See the flagships index.

The architecture archaeology study is the advanced continuation: provenance for one undocumented system, then for an enterprise recovered across many repositories.

01 — one graph, many views is the hero example: a single model.gsl for a retail platform.

---

Try it

You need Go 1.26 or newer to install from source. The reference implementation has no build-time magic — standard compiler, single step.

go install github.com/dnnrly/gsl-lang/cmd/gsl-query@latest
go install github.com/dnnrly/gsl-lang/cmd/gsl-diagram@latest

Prebuilt binaries for Linux, macOS and Windows are attached to the GitHub releases page (no Go required).

Thirty seconds with a real example

Clone the repository (or copy the examples from it) and point the tools at a flagship model:

git clone https://github.com/dnnrly/gsl-lang
cd gsl-lang/examples/flagships/01-service-many-views

# 1. The graph, as durable text — canonicalised for stable git diffs
gsl-query "" < model.gsl

# 2. A derived view: "what breaks if we retire legacy-orders?"
gsl-query '(subgraph node.id == "legacy_orders" traverse in all) as BLAST | from * | (subgraph node in @critical) as CRIT | BLAST & CRIT' < model.gsl

# 3. A diagram of the full model (Mermaid component view)
gsl-query 'from *' < model.gsl | gsl-diagram -f mermaid -t component

# 4. The same graph as PlantUML source — a second diagram dialect
gsl-query 'from *' < model.gsl | gsl-diagram -f plantuml

Every command outputs canonical GSL or diagram source (.mmd/.puml) — stable, reviewable, diffable. gsl-diagram supports Mermaid (component, graph, sequence) and PlantUML (component, sequence); see cmd/gsl-diagram/README.md for the full converter reference. The output is diagram source; pipe it to your usual renderer (mermaid-cli, plantuml) when you want a picture.

The two-minute test

The flagship examples are self-checked: every committed result is byte-compared against the real CLI on every test run.

go test ./examples -run Flagship -v

---

GSL compared with alternatives

GSL is not "better" than these — it is different: model-first, render-later. Choose GSL when the graph is an asset you will version, query and reshape. Choose the alternative when it is the fastest path to the thing you need.

The converters mean these compose rather than compete: a GSL graph can become a Mermaid or PlantUML view. The composition is the point.

---

Learn GSL

Ordered for learning, not for reference completeness:

1. Documentation — the learning journey: Getting Started → Concepts → Tutorials → Cookbook, with the guides and specifications as reference tiers.
2. Flagship examples — why GSL exists, problem-first; the narratives the documentation links back to.
3. GSL Guide — the language in one self-contained document (syntax, semantics, design notes).
4. Query tutorial — a step-by-step learning path for GQL, the query language.
5. GQL Guide — GQL as a self-contained reference.
6. Go reference — the Go API and algorithm patterns, for programmatic use.
7. Examples — a catalog of graphs demonstrating individual language features.

Targeted at AI and LLM tooling: start at llms.txt for the agent-oriented index.

---

Specification

GSL is defined by a normative, RFC 2119-style specification, not by the implementation:

• SPEC.md — the authoritative language specification (v1.0.0 Draft): grammar, semantics, canonicalisation guarantee.
• GRAMMAR.md — the formal grammar, for implementing a parser.
• QUERY_SPEC.md — the query language specification (v0.4.0 Revised Draft).
• QUERY_GRAMMAR.md — the formal GQL grammar.

Every gsl and gql code block in this repository's markdown — at the root and under docs/ — is automatically parsed on test. The documentation cannot drift from the language it describes.

---

Implementations

• Go library — the reference implementation; a hand-written parser with a canonical-form guarantee (parse(serialize(parse(x))) == parse(x)), standard-library core only. go get github.com/dnnrly/gsl-lang.
• gsl-query — run GQL pipelines (subgraph, traverse, make, remove, collapse, graph algebra) against a GSL graph; emits canonical GSL.
• gsl-diagram — render any GSL document (or derived view) to Mermaid or PlantUML.
• gsl-lsp — a language server for GSL and GQL (completion, hover, diagnostics, formatting). Source lives in lsp/; a preliminary VS Code extension is in editors/vscode/.

The CLI tools are Unix-composable: GSL in, canonical GSL or a diagram out, via stdin/stdout.

---

Project status

The implementation is mature; the adoption question is open. The specification and reference implementation are small, disciplined and heavily tested — every claim here is enforced by tests, not by description — but this is an honest experiment, not an established standard. What remains genuinely open is whether the model proves useful to people beyond this repository.

What GSL deliberately is not — and why that is by design:

• Not a layout engine. Diagram output exists; appearance is a view, not the product. Render through Mermaid, PlantUML and others.
• Not a schema or validation framework. Graphs are accepted as written, with non-fatal warnings. Staying small is the point.
• Not a database. No persistence, indexing or live multi-user querying. Queries are file-in, file-out transformations.
• Not a general data format. GSL is for graph-shaped knowledge only.

The closest thing to a gotcha: GQL is the differentiator, and it is honestly labelled a Revised Draft. The flagship examples only use behaviour covered by its tested fixtures.

---

Contributing

The parser is hand-written, the core is standard-library-only, and the tests run against the language itself. Contribution guidance and project conventions live in AGENTS.md. The code of conduct applies.

---

Licensing

The original GSL work is authored and maintained by Pascal Dennerly, who holds its copyright. The repository is intentionally dual-licensed so that code and documentation can be reused under the terms that best fit each:

Individual files carry an SPDX header identifying their licence; where a document is CC-BY-4.0, fenced code blocks embedded in it remain Apache-2.0. Reuse the prose under CC-BY-4.0 and the code under Apache-2.0. The CLI tools report their licence in version output, and the embedded guides ship under CC-BY-4.0 with the binaries.

These licences cover the material published in this repository. They grant permission to use that material; they do not claim ownership of, or restrict independent implementations of, the GSL language itself.