Format 1.0
The TakeSix format
A TakeSix diagram is one JSON file: a tree of blocks, never more than six side by side, and the arrows between them. This page explains it in plain words. The exact specification is FORMAT.md, with a JSON Schema for editors and agents.
The idea
A long explanation is hard to read because everything is on the page at once. TakeSix splits it into screens:
- One screen, at most six blocks. The top level is the whole answer in six blocks or fewer.
- Every block can open. Its children are the next screen, again at most six. Depth is not limited, so a big system still reads one small screen at a time.
- Arrows show how parts connect, between the blocks of one screen.
- Long text is a level of its own. A card shows a title and a short line; a block that needs explaining opens into its text in Markdown, the way other blocks open into blocks.
The file is plain JSON, so people edit it by hand, agents write it, and any program can read it. One HTML file with the JSON and a viewer inside opens as a diagram in any browser.
A first diagram
An online shop in three blocks. The API opens into two more, and two arrows connect the parts:
{
"$schema": "https://takesix.vapnik.de/schema/takesix-1.0.schema.json",
"takesix": "1.0",
"title": "Online shop",
"blocks": [
{ "id": "web", "at": "A1:C1", "icon": "🖥", "title": "Web app", "description": "React SPA" },
{
"id": "api",
"at": "D1:F1",
"title": "API",
"description": "Public HTTP API",
"children": [
{ "id": "auth", "at": "A1:B1", "title": "Auth" },
{ "id": "orders", "at": "C1:F1", "title": "Orders", "details": "Handles **checkout** and refunds." }
]
},
{ "id": "db", "at": "A2:F2", "title": "Database" }
],
"links": [
{ "id": "l1", "from": "web", "to": "api", "label": "REST" },
{ "id": "l2", "from": "api", "to": "db", "label": "SQL" }
]
}The top screen of this file:
A1:C1APID1:F1DatabaseA2:F2Open API and you see Auth and Orders. The arrows link blocks of the top screen: Web app to API, and API to Database.
Blocks
A document has a title and its top-level blocks:
| Field | What it is |
|---|---|
takesix | The format version, "1.0". Required. |
title | The name of the diagram. Required. |
blocks | The top level, one to six blocks. Required. |
links | All arrows of the document, on every level, in one list. |
description | A line under the title on the top screen. |
Each block is a card on the screen:
| Field | What it is |
|---|---|
id | A name that arrows use to point at the block, unique in the whole file. Required. |
title | The heading of the card. Required. |
at | Where the card sits on its screen, like "A1:C2"; see the grid. Required. |
description | A short line of plain text on the card. |
details | Long text in Markdown: lists, code, links. The block opens into it instead of child blocks, so a block has children or details, never both. |
icon | An emoji or one character before the title. |
shape | A flowchart symbol, such as "decision"; see flowcharts. A plain card when left out. |
children | The blocks inside, at most six. They make the screen that opens on a click. Never together with details. |
Ids never change. Arrows, comments and shared editing refer to blocks by id, so a tool renames the title, not the id. Short readable ids such as "orders-db" are the easiest to edit by hand.
The grid
Every screen is a grid of 6 columns and 6 rows, named like a spreadsheet: columns A–F, rows 1–6. A block takes one cell, such as "B3", or a rectangle from its top-left to its bottom-right cell, such as "A1:C2" (three columns wide, two rows tall).
- Blocks of one screen never overlap. Cells nobody takes stay empty.
- The width of a block is its share of the screen: all six columns are equally wide. Rows grow with the text.
- Only
atplaces a block; the order in the file does not matter. Screen readers and text versions read a screen row by row, left to right, and editors keep the file in that order.
Three shapes cover most diagrams:
A1:F1Step 2A2:F2Step 3A3:F3A1:B1TwoC1:D1ThreeE1:F1FourA2:B2FiveC2:D2SixE2:F2A1:D3HelperE1:F1HelperE2:F2HelperE3:F3Arrows run straight between blocks in one row or one column, so put connected blocks next to each other. Empty cells between small blocks leave room for arrows that branch and for their labels.
Links
Arrows live in one list, links, next to the blocks. Each one goes from a block to another, by id:
label: a few words on the arrow, such as"REST".description: a longer explanation of the connection.direction:"forward"(the default, from → to),"both"or"none"for a plain line.style:"solid"(the default),"dashed"or"dotted".id: optional, editors set it so an arrow can be changed later.
A link joins two blocks of one screen, children of the same block. To connect parts deeper inside, link the blocks that hold them, on the screen they share, as API → Database does.
- Several links between the same two blocks merge into one arrow; two opposite ones make a two-way arrow.
- A straight arrow with a block in its way goes around it, beside the column or below the row.
- A link between blocks of different screens is never drawn. Validators warn about it, and editors do not create it.
Flowcharts
An algorithm draws its steps with shape, in the symbols of ISO 5807 (ГОСТ 19.701-90, close to DIN 66001), only the common ones:
| shape | Drawn as | For |
|---|---|---|
process | a plain card (the default) | a step that does something |
terminator | round ends | start and end |
decision | a diamond | a condition: label each exit, like "yes" and "no" |
io | a parallelogram | data in or out |
subprocess | double sides | a step whose children are its own steps |
loop-start, loop-end | cut corners, top or bottom | the two ends of a loop |
Unlike the standard, every arrow has a head, and a long algorithm becomes subprocesses that open into their steps instead of pages joined by connectors: a screen still holds six blocks at most. Validators warn when a decision has no 2 or 3 labelled exits, or a screen has more than one start.
Checking a diagram
A diagram that breaks these rules is rejected, with the place of each problem in the JSON:
- a required field is missing or empty, or has the wrong type;
atis not a cell or a rectangle of the 6×6 grid, or two blocks of one screen take the same cell;- a screen has more than six blocks;
- a block has both
childrenanddetails: it opens into blocks or into text, not both; - two blocks or two links share an id;
- a link points at an id that is not a block, or from a block to itself;
direction,styleorshapehas an unknown value, or the version is not1.x.
Unknown fields are only a warning: they are often typos. The JSON Schema is stricter and rejects them, which catches mistakes while an agent writes a diagram.
Ways to check a file:
- Add
"$schema"as in the example, and editors such as VS Code underline mistakes as you type. - Agents call the
validatetool of the MCP server; see the guide. - In code,
validateDocument()from @takesix/core checks everything, including what JSON Schema cannot: unique ids, link ends and overlapping blocks.lintLayout()also warns when an arrow runs through a third block or two arrows cross.
Extensions and versions
Tools keep their own data in meta on the document, a block or a link, under keys with the tool’s name: { "meta": { "confluence.pageId": "123" } }. Every tool keeps the meta it does not understand, so data survives a trip through another editor.
The version is "major.minor". A minor version only adds optional fields, so a 1.0 reader opens any 1.x file. A new major version is a breaking change, and readers refuse majors they do not know.
Try it: open the editor and build a diagram by hand, or connect your AI agent and let it write one. The full specification is FORMAT.md.