Skip to main content

Object Model And Relations

This page explains the main structural pieces of the ASCII Diagram file format.

Shared object fields​

All diagram objects share a few base properties:

  • id
  • type
  • position
  • zIndex
  • optional label
  • optional groupId

position is stored in character-grid coordinates.

Box objects​

Boxes are rectangular nodes with optional title and body content.

Important fields include:

  • width
  • height
  • title
  • content
  • textAlign
  • verticalAlign
  • border
  • optional borderStyle

Example:

{
  "id": "box-1",
  "type": "box",
  "position": {"x": 4, "y": 2},
  "width": 16,
  "height": 5,
  "title": "API",
  "content": "POST /events",
  "zIndex": 1
}

Text objects​

Text objects are freeform text blocks with dimensions and alignment controls.

Important fields include:

  • content
  • width
  • height
  • optional showBorder
  • textAlign
  • verticalAlign

Arrow objects​

Arrows connect points on the grid.

Important fields include:

  • position for the start point
  • end for the end point
  • optional waypoints
  • startHead
  • endHead
  • optional routing
  • optional lineStyle

Routing currently supports:

  • direct
  • orthogonal
  • stepped

Ports and relations​

Relations connect a source object port to a target object port.

This is how ASCII Diagram preserves attachment semantics instead of treating every arrow as a loose line.

Two main port forms exist:

  • anchor for rectangular object edges
  • endpoint for arrow start, end, or waypoint indices

At a high level, a relation says:

  • which object follows
  • which point on that object follows
  • which object it is attached to
  • which point on the target it is attached to

Groups​

Groups are named collections of objects.

They are useful for:

  • moving a cluster together
  • keeping diagram fragments organized
  • preserving intent in more complex documents

Z-order​

Objects also carry zIndex, which controls drawing order.

That matters when objects overlap and when you want the object list to reflect the current stacking order.

Why this structure exists​

The schema is designed to support three things at once:

  • visual editing
  • durable file storage
  • future migrations and tooling

It is intentionally richer than raw pasted ASCII because the app needs enough structure to support editing without turning the file into an opaque binary format.