Diagnostics panel

The diagnostics panel is a thin horizontal strip across the bottom of the playground. It tells you at a glance whether your schema has problems, and lists each one with click-to-jump-to-source.

📸 Screenshot placeholder

[Screenshot needed] Filename suggestion: diagnostics-panel-errors.png Caption: The diagnostics panel expanded, showing one error and one warning with line and column. Should show: the bottom of the playground UI with the diagnostics panel expanded. The header shows "1 error" in red and "1 warning" in amber. Two rows are visible: one with a red × icon, one with an amber ! icon, each with a message, "Line N, column M" in a smaller grey font, and a code chip such as possible-type-typo.

What the header shows

The header stays visible, about 32 pixels tall, so the layout doesn't shift when a problem appears. It shows one of:

• No issues, in grey, when the schema parses and resolves cleanly.
• An error count, in red with a small × icon: "1 error", "3 errors".
• A warning count, in amber with a small ! icon: "1 warning", "2 warnings".

Errors and warnings are counted separately, so a schema with both shows the two counts side by side. When there is something to list, a caret (▸ or ▾) shows whether the body is collapsed or expanded, the header reads "Click to expand" or "Click to collapse", and a Copy button sits at its right end (see Copying diagnostics).

Errors and warnings

The playground checks your schema in two stages.

Parsing reads the text. A syntax error stops it at the first problem, so the panel lists that one error, and the diagram keeps showing the last schema that parsed. When parsing fails covers recovery.

Resolution runs on a schema that parsed and checks what its names refer to: that a relationship points at an entity and a field that exist, that an injected partial is declared, that a key or index names fields the entity declares, that a foreign key references a key, that a supertype group follows the rules of the specification. It can report several problems at once. Since the schema parsed, the diagram and the inspector keep up with your edits while these diagnostics are listed.

Resolution reports two severities. An error marks something the schema cannot mean as written, such as a relationship to an entity that doesn't exist, or two declarations with the same name. A warning marks something valid that is probably not what you intended. These warnings exist today:

• possible-type-typo: a type name that is not declared, but is close to a declared Type or Enum, such as Adress in a schema that declares Type Address. The message suggests the declared name. Any type name is valid in xDBML, so target-native types such as number, clob or serial raise nothing on their own; the warning appears only for a near miss.
• ambiguous-ref-endpoint: a relationship endpoint that reads both as an entity and as a field of another entity. The field reading is used; rename one of them or qualify the path.
• empty-supertype-group: a supertype group that lists no subtype yet.
• merge-without-roll-up: a merge setting on a supertype group where neither the group nor any subtype uses strategy: roll_up, the only strategy it applies to.
• source-query-in-settings: a View writes source_query in the brackets after its name. The source query belongs in the body, as source_query: '...'; in the brackets it stays an ordinary setting, so the inspector does not show it as the view's query.
• duplicate-source-query: a View declares a second source_query: in its body. The first one is the view's source query.
• duplicate-unique-key: an entity declares the same unique key twice, for example [unique] on a field and the same field as a unique line in constraints. Declare it in one place: inline for a single field without a name, in constraints otherwise.
• name-collision: two declarations share one qualified name, such as a Type and an Entity named customers. Entities, Views, Edges, Types, Enums and EntityPartials share one namespace (spec §15.5): rename one of them. An error from v0.6, a warning in a document declaring an earlier version or none.
• container-target-missing: the Project declares several targets and a Container declares none. Write it after the Container's name, as in Schema core [target: PostgreSQL] { ... } (spec §5.2).
• container-target-not-in-project: a Container's target is not among the Project's targets. Add it to the Project's targets:, or change the Container's target (spec §5.2).

A few conditions change severity with the version the document declares. In an xdbml: 0.6 document they are errors; in a document declaring an earlier version, or none (plain DBML), they are warnings, so a file that was valid under its version stays valid:

• ref-target-not-key: a foreign key references fields that are neither the primary key nor a unique key of an entity that declares keys. A relational database refuses such a foreign key. Declare the fields unique, or reference the key. Relationships to an entity without keys, to or from a document or graph target, many-to-many relationships, foreign master relationships and entity-level relationships are exempt.
• duplicate-primary-key: an entity declares its primary key in two places, for example [pk] on a field and a pk entry in indexes.
• null-in-primary-key: null written on a field of the primary key.
• unresolved-index-field: an index names a field the entity does not declare.
• invalid-tuple-positions: the positions of a tuple, array [ [0] ... [1] ... ], skip a number, repeat one, or do not start at [0]. A tuple of three elements numbers them [0], [1] and [2] (spec §8.6).
• named-type-shadows-builtin: a Type takes the name of a built-in type, such as Type Money or Type varchar, in any letter case. Built-in types take precedence, so the fields typed with that name never reach the Type: rename it (spec §15.2).

The last two are errors in a document declaring v0.6 or later, and warnings in a document declaring an earlier version, since no parser checked them before v0.6.4.

• duplicate-diagram-view-category: a diagram view writes one category twice, or both Schemas and Containers, which are one category. Write each category once. In a document without a version declaration it is a warning, since DBML accepts it, and the two lists combine (spec §18.6).

Diagram views (spec §18) add five errors of their own, whatever version the document declares:

• unresolved-diagram-view-name: a name in a diagram view matches nothing of its category's kind.
• ambiguous-diagram-view-name: an unqualified name, such as orders, matches entities in several Containers and none outside a Container. Write the qualified name, sales.orders.
• diagram-view-wrong-category: a name lists an element under the wrong category, such as a database view under Entities. The message names the right category. An Edge is never listed: it appears when both of its ends do.
• duplicate-diagram-view: two diagram views share one name.

The Containers, Views and SupertypeGroups categories, and a diagram view's note and settings, are xDBML extensions: in a document without a version declaration they raise construct-requires-version. DBML's own name for Containers, Schemas, needs no declaration. See Diagram views.

EntityPartials (spec §17.1), written TablePartial in DBML, add one condition, with the same severity whatever version the document declares:

• partial-injection-in-partial (error): the body of an EntityPartial, or one of its fields, holds a ~name line. A partial does not inject another one; write both ~name lines in the body that needs the fields of both.

Internal definitions (spec §15.8) add five conditions of their own, with the same severity whatever version the document declares, since no parser read a definitions block before 0.6.5:

• definitions-outside-entity (error): an EntityPartial or an Edge holds a definitions block. Internal definitions belong to an entity; declare a shape reused elsewhere as a Type. In a View, the block stops the parse with a message citing §15.8.1.
• duplicate-definitions-block (error): an entity declares a second definitions block. Put every entry in one.
• duplicate-definition (error): two entries of one block share a name.
• definitions-unsupported-target (error): the entity's target takes no internal definitions: a relational target, Cassandra, ScyllaDB, Neo4j, Memgraph, Neptune or JanusGraph. Declare the shape as a Type at the top of the document (spec §15.8.4).
• definition-shadows-type (warning): an entry takes the name of a Type or an Enum declared outside the entity. Inside the entity, the entry wins.

An entry under the name of a built-in type, such as money, raises named-type-shadows-builtin as an error in every version.

From version 0.7, the parser reads the constructs DBML added up to version 10.3, in every document, with conditions of their own.

Records (spec §26):

• duplicate-records-block: an entity holds a second records block, in its body or at the top level. Put every row in one block. An error, as in DBML; a warning in a document declaring v0.6 or an earlier version, which accepted it.

Relationships (spec §11.7):

• cardinality-conflict (warning): a ? marks an end optional, and a source: or target: setting gives that end a minimum of 1 or more. Drop one of the two. The setting applies in a document declaring an xdbml: version, and the mark in one without.

Settings and Metadata blocks (spec §24.5, §24.7):

• duplicate-setting (warning): one settings list writes a setting twice. The first one applies; DBML rejects the list.
• metadata-override (warning): a Metadata block of the document changes a value that the element's own declaration, or a block of an imported file, already set. The block's value applies. See Metadata blocks.
• metadata-custom-property (warning): a Metadata block sets a setting that belongs in the element's brackets, such as tags or pk. In the block it is only a custom property.
• metadata-brackets-ignored (warning): settings in brackets after the target of a Metadata block. They apply nothing, as in DBML; move them into the body.
• unresolved-metadata-target and unknown-metadata-kind (errors): the block names no element of its kind, or a kind that does not exist. An xDBML kind, such as Entity or View, in a document that does not declare xdbml: 0.7 raises construct-requires-version.
• duplicate-metadata-setting and invalid-metadata-value (errors): a block sets one setting twice, or gives note something other than a string, or a color something other than #rgb or #rrggbb.

Sticky notes (spec §19):

• invalid-note-color (error): a sticky note's color is not #rgb, #rrggbb or none.
• duplicate-project-note (warning): a top-level Note without a name, when the Project block or an earlier unnamed Note already carries the note of the project. It applies nothing; give it a name to make it a sticky note. See Sticky notes.

Data lineage (spec §27):

• unresolved-dep-endpoint and invalid-dep-endpoint (errors): an end of a dependency names nothing, or names an Edge, or several fields at once.
• dep-wrong-kind (error): an inline dep on a field names an entity, or one on an entity names a field.
• dep-mixed-downstream (error): the dependencies of one block go to different elements.
• dep-mixed-level (error): in a document without a version declaration, a block mixes dependencies between entities with dependencies naming fields, which DBML rejects. A document that declares a version may mix them.
• dep-self-loop (error): a field depends on itself. An entity may: its rows can come from its own earlier rows.
• duplicate-dep (error): one dependency stated twice, inline and in a Dep, say. In a document that declares a version, the same pair may be stated once for each kind of transformation.
• invalid-dep-color (error): a color other than #rgb or #rrggbb.
• misplaced-dep and dep-in-partial (errors): a dep where no dependency can stand, such as on an Edge, a Type or an EntityPartial.
• invalid-dep-value: a dep whose value is no arrow. An error; in a document declaring v0.6 or an earlier version, a warning, and the value stays a custom property, as it was.
• empty-dep (warning): a block with no dependency. DBML drops it silently.
• ambiguous-dep-endpoint (warning): an end reads both as an entity and as a field of another one. The field reading is used, as for a relationship. See Data lineage.

Source-to-target mapping (spec §27.10, v0.7.2):

• unknown-transformation (error): transformation takes one of identity, calculation, aggregation, join, lookup, filter, group_by and conditional.
• transformation-between-entities (error): a kind other than identity on a dependency between two entities; name the field that takes part.
• transformation-target-mismatch (error): identity, calculation, aggregation or conditional from a field to an entity; these kinds give the value of one field.
• transformation-mismatch (warning): identity with several sources; a copy has one.
• indirect-from-entity (warning): a join, a lookup, a filter, a grouping or a condition starting from a whole entity, which does not say which field takes part.
• source-query-in-settings (warning): source_query in the brackets of a Dep, where it is not the statement; write it in the body of a block, as for a View.

Rows in the body

Each row shows:

• A red × for an error, or an amber ! for a warning.
• The message, for example "Relationship endpoint references unknown entity 'custmers'."
• The source position in grey: "Line 12, column 5".
• For a resolution diagnostic, a short code such as unresolved-entity or possible-type-typo, the same code the MCP validate_xdbml tool reports. Syntax errors carry no code.

Rows are sorted by line, then column, matching the order you'd read them in the source. The body scrolls once the list is taller than about 200 pixels, so a long list doesn't push the diagram off-screen.

Click to jump

Clicking anywhere on a row moves your editor cursor to that line and column, scrolls the editor to bring it into view, and gives the editor focus. Useful when you have many diagnostics, or when one is on a line that's scrolled off-screen.

A click that ends a text selection doesn't jump, so a selection you drag across a row stays in place for copying.

Copying diagnostics

There are two ways to take diagnostics out of the playground, for a bug report or a message to a colleague:

• Select and copy. Drag across the text of one or more rows to select it, then press Ctrl+C (Cmd+C on a Mac).
• Copy everything. Click Copy at the right end of the header. Every diagnostic goes to the clipboard, one per line, in the order of the list: the severity, the line and column, the code when there is one, and the message, as in Error at line 12, column 5 [unresolved-entity]: Relationship endpoint references unknown entity 'custmers'. The button reads "Copied" for two seconds.

How it relates to editor squiggles

The same diagnostics appear in the editor pane as squiggles, red for errors and amber for warnings, with the message and code in a hover tooltip. The two surfaces are complementary:

• Squiggles are visible while you're already looking at the editor, in place at the offending token.
• The diagnostics panel is visible regardless of which pane has your attention, lists every diagnostic compactly, and gives you the counts.

Collapsing the body

The body is expanded by default. Click the header to collapse or expand it; the caret rotates to match, and the playground remembers your choice across reloads. When there is nothing to list, the header doesn't respond to clicks.

When you collapse with diagnostics present, the counts stay visible in the header so you don't forget about them.

What's next

• When parsing fails: broader strategies for recovering from broken schemas.
• Editor pane: the editor side of error reporting, including squiggles and hover tooltips.