Skip to main content

The .asciid Format

ASCII Diagram stores diagrams in a structured JSON document with a versioned schema.

This is the canonical source format for the app.

Root shape​

At a high level, a document looks like this:

{
  "$schema": "asciidiagram/v1",
  "version": 1,
  "metadata": {
    "name": "Request Flow",
    "createdAt": "2026-04-01T12:00:00.000Z",
    "modifiedAt": "2026-04-01T12:05:00.000Z"
  },
  "objects": [],
  "relations": [],
  "groups": []
}

Top-level fields​

$schema​

The schema identifier for tooling and validation.

Current value:

"asciidiagram/v1"

version​

The schema version number.

Current value:

1

metadata​

Document metadata currently includes:

  • name
  • createdAt
  • modifiedAt
  • optional author

objects​

The array of diagram objects. Current object types are:

  • box
  • text
  • arrow

relations​

Relations connect one object port to another so arrows can stay attached as the diagram moves.

groups​

Groups provide named collections of objects that can be manipulated together.

Why JSON?​

JSON is not glamorous, but it is a strong fit here:

  • easy to inspect
  • easy to diff
  • easy to version
  • easy to migrate later
  • easy to manipulate from other tools

Source vs. output​

It is important to separate two things:

  • the .asciid file is the source
  • rendered ASCII is an output produced from that source

That means the file can preserve structure the exported text cannot, such as:

  • stable object IDs
  • relations
  • z-index
  • grouping
  • metadata

Learn more​