Skip to main content

Layout file format

DBML describes tables, columns, references, notes and table groups. It has no syntax for where a table sits on the canvas. relvista keeps the .dbml file exactly as dbdiagram.io writes it and stores everything else in a sidecar JSON file named after it: schema.dbml → schema.dbml.layout.json. Deleting the sidecar loses only the arrangement; the diagram is laid out automatically again.

The format is defined by a JSON Schema published at https://relvista.org/schemas/layout-1.json (draft 2020-12). Point $schema at it and editors such as VS Code give you completion and validation while you edit.

Files written before 1.0 may name an older $schema id. They still load, and relvista saves them with $schema unchanged. New files get the current id.

Example​

schema.dbml.layout.json
{
"$schema": "https://relvista.org/schemas/layout-1.json",
"version": 1,
"views": {
"*": {
"nodes": {
"public.users": { "x": 0, "y": 0, "w": 220 },
"public.posts": { "x": 320, "y": 0, "collapsed": true },
"billing.invoices": { "x": 0, "y": 400, "pinned": true },
"note:overview": { "x": -300, "y": 0, "w": 260, "h": 120 },
"group:auth": { "x": -20, "y": -40, "w": 600, "h": 360 },
"group:billing": { "x": 0, "y": 640, "collapsed": true }
},
"viewport": { "x": -40, "y": -40, "zoom": 1 },
"edges": {
"ref:public.posts(user_id)>public.users(id)": {
"waypoints": [{ "x": 260, "y": 40 }],
"sourceSide": "right",
"targetSide": "left"
}
}
},
"billing": {
"nodes": { "public.users": { "x": 600, "y": 400 }, "public.posts": { "collapsed": false } }
}
},
"settings": { "detailLevel": "keys", "theme": { "colorScheme": "auto", "showGrid": true } }
}

Fields​

FieldMeaning
versionAlways 1. A breaking change gets a new schema URL (layout-2.json) and version.
viewsLayouts by view name. "*" is the default view.
views.*.nodesPlacement by stable node id: x/y top-left corner in diagram units; optional w/h size overrides (omit to use the measured size); collapsed (header only); pinned (auto-layout leaves it alone).
views.*.viewportCamera: x/y is the diagram point at the canvas top-left; zoom > 0.
views.*.edgesManual edge routing by ref id: waypoints (bend points, source to target) and the sourceSide/targetSide (top, right, bottom, left) to attach to.
settings.detailLevelall columns, keys only (PK/FK), or table names only.
settings.themeRendering hints (colorScheme, showGrid, edgeStyle). Viewers may ignore them.
x-*Extension keys, allowed at the top level and in settings. Tools preserve them and never interpret them.

Everything else is rejected, so typos show up as errors.

Notes and groups​

  • Sticky notes (note:<name>) take w and h as their size: the text wraps at the width, which is kept between 120 and 640, and h is the box height as is (at least 64). The editor writes both when you resize a note. Without them a note is 220 wide and as tall as its text.
  • Table groups (group:<name>) with "collapsed": true are drawn as one card (the group's name and "3 tables") instead of the box with its tables; refs to its tables attach to the card, and x/y place the card. Collapsing is per view like everything else, so a named view can show a group collapsed that "*" shows open. On a table, collapsed keeps only its header.

Views​

A named view inherits from "*": its effective layout is the default view with the named view's entries merged over it, field by field. A named view therefore stores only what differs: its node entries may omit x/y (for example only collapsed), and then a later move in "*" is inherited. In "*" every node entry needs x and y. A node that only a named view mentions, without a position, is placed by auto-layout. The viewport comes from the named view when it has one.

Stable ids​

ElementIdExample
Tableschema.table, schema always written, public when the DBML omits itpublic.users
Table with a dotted quoted nameSegments that need it are double-quoted (see below)x."y.z"
Sticky note (Note name { ... })note:<name>note:overview
Table groupgroup:<name>group:auth

A table-id segment (schema or table name) is written as is unless it is empty, contains one of . " \ : , ( ), or starts with < > - ?. Then it is wrapped in ", with " and \ escaped by a backslash: Table x."y.z" → x."y.z", Table "x.y".z → "x.y".z. So two tables never share an id, and a table id never looks like a note: or group: id.

Edge keys are ref ids, derived from both endpoints and the relationship operator (also for named refs): ref:<tableId>(<columns>)<op><tableId>(<columns>), for example ref:public.posts(user_id)>public.users(id). #2, #3, … is appended only when refs have exactly the same endpoints and operator.

Ids come from names, so renaming a table in the DBML renames its entries, and entries for removed elements can be dropped.

Deterministic output​

The file is meant to live in git next to the DBML, so tools write it the same way every time: keys sorted, numbers rounded to 2 decimals (zoom keeps 4 significant digits), 2-space indent and a trailing newline. Moving one table changes one or two lines.

Using a layout file in the docs​

Put the file in static/ and pass its URL:

```dbml layout="/layouts/schema.dbml.layout.json"
...
```

See Usage → Layout files.