TakeSix

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:

shop.takesix.json
{
  "$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:

ABCDEF12🖥 Web appA1:C1APID1:F1DatabaseA2:F2
The top level: Web app and API share the first row, Database fills the second.

Open 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:

FieldWhat it is
takesixThe format version, "1.0". Required.
titleThe name of the diagram. Required.
blocksThe top level, one to six blocks. Required.
linksAll arrows of the document, on every level, in one list.
descriptionA line under the title on the top screen.

Each block is a card on the screen:

FieldWhat it is
idA name that arrows use to point at the block, unique in the whole file. Required.
titleThe heading of the card. Required.
atWhere the card sits on its screen, like "A1:C2"; see the grid. Required.
descriptionA short line of plain text on the card.
detailsLong text in Markdown: lists, code, links. The block opens into it instead of child blocks, so a block has children or details, never both.
iconAn emoji or one character before the title.
shapeA flowchart symbol, such as "decision"; see flowcharts. A plain card when left out.
childrenThe 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 at places 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:

ABCDEF123Step 1A1:F1Step 2A2:F2Step 3A3:F3
A list: one block per full-width row.
ABCDEF12OneA1:B1TwoC1:D1ThreeE1:F1FourA2:B2FiveC2:D2SixE2:F2
Tiles: three blocks per row.
ABCDEF123MainA1:D3HelperE1:F1HelperE2:F2HelperE3:F3
A main block with helpers beside it.

Arrows 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.

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:

shapeDrawn asFor
processa plain card (the default)a step that does something
terminatorround endsstart and end
decisiona diamonda condition: label each exit, like "yes" and "no"
ioa parallelogramdata in or out
subprocessdouble sidesa step whose children are its own steps
loop-start, loop-endcut corners, top or bottomthe 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;
  • at is 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 children and details: 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, style or shape has an unknown value, or the version is not 1.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 validate tool 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.