Create a new Doclific document. Navigates the doclific directory structure, selects an appropriate icon, and creates the document using insert-doc.js.

2026-01-2640

name	generate-doclific-erd-json
description	Generate JSON for ERD (Entity Relationship Diagram) components. Use when creating database schema diagrams in Doclific documentation.

Generate Doclific ERD JSON

Overview

This skill helps you generate the JSON for ERD (Entity Relationship Diagram) components in Doclific MDX documentation.

Instructions

When the user asks you to create an ERD diagram:

Gather requirements: Ask the user about their database schema - tables, columns, and relationships.
Generate the JSON: Create properly formatted JSON for the tables and relationships attributes.
Output the MDX: Provide the complete <ERD> component with the generated JSON.

ERD Component Structure

<ERD tables="[JSON array of tables]" relationships="[JSON array of relationships]"></ERD>

Tables JSON Structure

Each table object must have:

{
	"id": "unique-table-id",
	"type": "tableNode",
	"data": {
		"name": "table_name",
		"columns": [
			{
				"name": "column_name",
				"dataType": "varchar",
				"isPrimaryKey": false,
				"isNullable": true
			}
		]
	},
	"position": {
		"x": 50,
		"y": 50
	}
}

Table fields:

id (string): Unique identifier for the table (e.g., "t1", "users-table")
type (string): The type of node, must be "tableNode"
data (object): The data for the table
data.name (string): The actual table name in the database
data.columns (array): Array of column definitions
position (object): The position of the table
position.x (number): Horizontal position for diagram layout (start at 50, increment by 300 for each table), maximum 1000, minimum -1000
position.y (number): Vertical position for diagram layout (typically 50-100), maximum 1000, minimum -1000

Columns JSON Structure

Each column object must have:

{
	"name": "column_name",
	"type": "varchar",
	"primaryKey": false,
	"nullable": true
}

Column fields:

id (string): Unique identifier for the column (e.g., "c1", "users-id")
name (string): The column name
type (string): PostgreSQL data type (see list below)
primaryKey (boolean): true if this is the primary key
nullable (boolean): true if the column allows NULL values

Supported data types:

Numeric: smallint, integer, bigint, decimal, numeric, real, double precision, smallserial, serial, bigserial
Monetary: money
Character: char, varchar, text
Binary: bytea
Date/Time: date, time, timetz, timestamp, timestamptz, interval
Boolean: boolean
Network: inet, cidr, macaddr, macaddr8
Bit strings: bit, bit varying
UUID: uuid
JSON: json, jsonb
Arrays: array

Relationships JSON Structure

Each relationship object must have:

{
	"table1": "table-name",
	"column1": "column-name",
	"table2": "table-name",
	"column2": "column-name",
	"cardinality": "1:N"
}

Relationship fields:

table1 (string): Name of the source table (the "one" side)
column1 (string): Name of the source column (usually the primary key)
table2 (string): Name of the target table (the "many" side)
column2 (string): Name of the target column (the foreign key)
cardinality (string): Cardinality of the relationship (one of "1:1", "1:N", "N:N", "N:1")

Example

See the example.json file in this directory for a complete example.

Workflow

User describes their database schema
Identify all tables and their columns
Identify relationships between tables
Generate unique IDs for tables, columns, and relationships
Calculate x/y positions (space tables horizontally)
Write JSON to temporary file: Create a temporary JSON file containing the tables and relationships arrays in the format described above
Validate and encode: Run the validate-and-encode.js script with the temporary file path as an argument:
```
node skills/generate-doclific-erd-json/validate-and-encode.js <temp-file-path>
```
The script will:
- Validate the JSON against the zod schema
- HTML encode both the tables and relationships JSON arrays
- Return a JSON object with tables and relationships properties containing the encoded strings
Output the MDX: Use the returned encoded strings as the tables and relationships props in the <ERD> component:
```
<ERD tables="{encoded_tables_string}" relationships="{encoded_relationships_string}"></ERD>
```
Clean up: Delete the temporary JSON file after use