Erdplus ERD to Relational Schema Converter

This is a TypeScript project that automatically converts Entity-Relationship Diagrams (ERDs) created in Erdplus into corresponding logical Relational Schemas.

It reads a .erdplus file (which is a JSON export) containing an ER diagram, applies standard database theory mapping rules to 3rd normal form, and outputs a new .erdplus file. This new file contains the equivalent Relational Schema, which can then be re-imported directly into Erdplus for visualization.

Note

The primary goal of this tool is to automate the logical database design phase, allowing you to visualize the resulting relational schema directly within the same application you used for conceptual modeling.

Features

The parser successfully maps the following ER diagram constructs to a relational model:

• Entities and Attributes: Basic entities are mapped to tables and attributes to columns.
• Relationships (1:1, 1:N, M:N):
  • 1:1: Mapped by propagating the primary key as a foreign key to the "optional" side.
  • 1:N: Mapped by propagating the "1" side's primary key as a foreign key to the "N" side.
  • M:N: Mapped to a new associative table containing foreign keys from both participating entities.
• Composite Attributes: "Cascading" attributes are flattened into multiple columns (e.g., address_street, address_city).
• Multivalued Attributes: Mapped to a new table containing a foreign key for the parent entity and a column for the attribute's value.
• Weak Entities: Correctly mapped, with the identifying relationship(s) creating a composite primary key. This includes handling cascades and multivalued attributes on weak entities.
• Supertypes and Inheritance: Handles specialization hierarchies (subtypes) by propagating the supertype's primary key to all subtypes.
• Recursive Relationships: Supported for all cardinalities (1:1, 1:N, M:N).
• Relationship Attributes: Attributes on relationships are correctly assigned:
  • For M:N relationships, attributes are added to the associative table.
  • For 1:N or 1:1 relationships, attributes are added to the table that receives the foreign key.

Note

N-ary Relationships: Per the modern Erdplus format, true n-ary relationships are modeled using an associative entity. The parser correctly supports this standard associative entity pattern.

Tip

The parser automatically generates all the primary keys, so there is no need to include an "column_id" in the ER modeling"

How to Use

The project is set up to batch-process files from the input directory.

1. Place all your .erdplus diagram files into the input/ directory.
2. Install dependencies:

   npm install

3. Run the main script:

   npm start

4. Find your converted files in the output/ directory. Each will be named {original_name}-relational.erdplus.

Warning

This tool does not work with old .erdplus file formats (any file created before November 1st, 2025). It is designed exclusively for the modern JSON structure.

Tip

However, if you upload the file to Erdplus and export it, then the file inherits the new format and this parser works.

Project Structure

.
├── data/
│   ├── tests/              # Test input .erdplus ER diagrams
│   │   └── results/        # Test output .erdplus Relational schemas
├── input/                  # Input .erdplus ER diagrams
├── output/                 # Output .erdplus Relational schemas
└── src/
    ├── core/               # Zod schemas and TypeScript types
    │   ├── common/         # Schemas shared by ER and Relational models
    │   │   └── schemas.ts
    │   ├── er/             # Schemas specific to ER diagrams
    │   │   └── schemas.ts
    │   ├── relational/     # Schemas specific to Relational models
    │   │   └── schemas.ts
    │   └── types.ts        # Combines and exports all types
    ├── io/                 # Utilities for reading/writing .erdplus files
    │   ├── readErdplusFile.ts
    │   └── saveErdplusFile.ts
    ├── parser/             # Core ERD-to-Relational conversion logic
    │   ├── handlers/       # Logic for each ER node type (Entity, Attribute, etc.)
    │   │   ├── attributeHandler.ts
    │   │   ├── entityHandler.ts
    │   │   ├── labelHandler.ts
    │   │   ├── relationshipHandler.ts
    │   │   └── weakEntityHandler.ts
    │   ├── index.ts        # Main parser orchestration
    │   └── parserUtils.ts  # Helper functions for the parser
    ├── utils/              # Utility functions to fix input file inconsistencies
    │   ├── fixAttributes.ts
    │   └── fixIds.ts
    ├── index.ts            # Entry point for batch processing all files in /input
    └── test.ts             # Entry point for batch processing all test files in /data/tests

Current Tests

1. [Passed] Entity-Attribute
2. [Passed] Entity-Relationship
3. [Passed] Attribute cascade
4. [Passed] Recursive relationship
5. [Skipped] N-ary relationship
6. [Passed] Weak entities + (identifying relationships + cascade)
7. [Passed] Relationship attributes
8. [Passed] Supertypes and multi-level inheritance
9. [Passed] Supertype Relationship
10. [Passed] Multivalued Weak Entity Attribute
11. [Passed] Broken erdplus file
12. [Passed] Zod schema validation

Note

As noted in Features, the new Erdplus format no longer uses true n-ary relationships, so a specific test for this legacy construct is not required. The parser handles the modern associative entity equivalent.

Future Work (TODO)

• Implement proper automated unit tests (e.g., using Jest) to validate the output schema structure, rather than relying on manual file comparison.