Entity Block

The Entity block lets you embed a dataset entity definition directly inside a narrative. Instead of describing a data structure in prose, you can pull the actual schema — fields, types, and relationships — from a dataset in your project and display it as a formatted reference.

This is particularly useful in API specifications, data flow narratives, and integration designs where the reader needs to understand the structure of the data being exchanged.

Inserting an Entity Block

1. In the narrative editor, click where you want the entity definition to appear.
2. Type / to open the slash command menu.
3. Type entity and select Entity from the list.
4. An empty Entity block is inserted at that position.

Selecting an Entity

When the narrative is in edit mode, the block shows a selection prompt. Click Select Entity to open the entity picker dialog. Browse to the dataset and entity you want to embed, then confirm your selection.

Once selected, the block displays the entity’s schema.

What the Block Displays

The Entity block renders the following content from the chosen entity:

Schema table A structured table listing each field with its name, data type, and any description defined on the entity. Required fields are indicated.

Relationships diagram If the entity has relationships to other entities in the same dataset, a Mermaid entity-relationship diagram is rendered showing those connections.

Sample JSON An example JSON payload representing the entity’s structure, generated from the field definitions. Toggle this on or off using the block’s display options.

Sample CSV A CSV header row and example row for the entity. Toggle this on or off using the block’s display options.

Display Options

In edit mode, the block shows toggle controls to show or hide:

• Relationships — the ER diagram
• Sample JSON — a generated JSON example
• Sample CSV — a generated CSV example

These preferences are saved with the block.

Navigating to the Entity

The block includes a link to the entity’s edit page in the dataset. Click Edit Entity (visible in edit mode) to open the full dataset entity editor in a new tab.

Tips

• Use Entity blocks in API specifications to show the exact request and response payloads without duplicating the schema definition. Note that entities should also be linked to the specification in the Data Use section, but also placing them with the Narrative enables you to contextualise the use of the entity.
• Use the relationships diagram to quickly communicate how entities are connected without writing a separate explanation.
• If the entity definition changes in the dataset, the block automatically reflects the latest version the next time the page is loaded.