Guide

WARNING

This documentation is not aimed at teaching you Entity-Relationship modeling concepts, rather than how to represent them using ERML. If you don't know what is Entity-Relationship, you can read about it from here (opens new window)

Table of Content

• Installation
• Entities
• Relationships
  • Participating Entities, and Structural Constraints
  • Relationship's Attributes
• Attributes
• Notes
• Example

Installation

Prerequisites:

• Node version 12.0.0 or higher.
• NPM.

You can install the ERML parser from NPM (opens new window) or yarn (opens new window) via the commands

npm install @erml/parser
yarn add @erml/parser

After that, all you have to do is to execute the parsing function exported by the library

const ERMLParser = require("@erml/parser")
const ast = ERMLParser(`ENTITY Example_entity { SIMPLE "attribute_name" }`)

Entities

Entities can be declared as:

• Independent entities

  ENTITY Entity_name {
    // Set of entity attributes
  }
  

• Dependent/Week entities

  WEAK ENTITY Entity_name OWNER Owner_entity_name {
    // Set of entity attributes
  }
  

Relationships

Relationships can be declared as:

• Normal relationships

  REL Relationship_name {
    // Set of participating entities, structural constraints, and attributes
  }
  

• Identifying relationships

  IDEN REL Relationship_name {
    // Set of participating entities, structural constraints, and attributes
  }
  

Participating Entities, and Structural Constraints

Participating entities are declared inside a relationship as follows

{
  Participating_entity1 /* constraints */
  Participating_entity2 /* constraints */
}

We can declare the constraints of a participating entity using the angle brackets notation <arg1, agr2>. Where arg1 is the participating constraint (TOTAL or PARTIAL), and arg2 is the cardinality ratio constraint (1 or N).

REL User_group {
  // ..
  User <PARTIAL, 1>,
  Group <TOTAL, N>,
  // ..
}

Alternatively, we can use the (min, max) notation. Where min is the minimum number of participating entities (participation constraint), and max is the maximum number of participating entities (cardinality ratio). Such that $0 \leq min \leq max \land max \geq 1$.

REL User_group {
  // ..
  User (0, N),
  Group (5, N),
  // ..
}

Relationship's Attributes

We can set attributes to relationships as follows

{
  ATTRIBUTES {
    // Set of relationship attributes
  }
}

Attributes

Attributes can be set to entities, relationships, and COMPOSITE attribute types. An attribute can take on one of 8 types:

1. SIMPLE / ATOMIC
2. PRIMARY
3. PARTIAL
4. DERIVED
5. MULTIVALUED

The syntax for the mentioned types

{
  // ..
  SIMPLE "DoB",
  DERIVED "age",
  // ..
}

6. COMPOSITE

The syntax for the COMPOSITE attribute type

{
	COMPOSITE "attribute_name" {
		// ..
		SIMPLE "attribute1_name",
		PRIMARY "attribute2_name",
		DERIVED "attribute3_name",
		// ..
	}
}

Notes

• Valid identifier requirements:
  • Maximum of 30 characters.
  • Starts with an uppercase/lowercase letter (a-z, A-Z), or an underscore.
  • Every character after the first should either be a number, an underscore, or an uppercase/lowercase letter.
• ERML is case-sensitive.
• Comments:
  • One-line comments can be achieved by prefixing them with //.
  • Multi-line comments can be achieved by wrapping them between /* */.
• ERML supports trailing commas, which means that these code examples are valid:

  REL Rel_name {
    Participating_entity1 <PARTIAL, 1>,
    Participating_entity2 <TOTAL, 1>,
    ATTRIBUTES {
      SIMPLE "attribute_name",
    },
  }
  

  ENTITY Entity_name {
    COMPOSITE "attribute_name1" {
      SIMPLE "attribute_name2",
      SIMPLE "attribute_name3",
    },
    PRIMARY "attribute_name4",
  }
  

The Complete Code of The Popular Company DB Example

Example

ENTITY Employee {
  PRIMARY "SSN",
  SIMPLE "salary",
  SIMPLE "DoB",
  DERIVED "age",
  COMPOSITE "full_name" {
    SIMPLE "first_name",
    SIMPLE "last_name"
  }
}

ENTITY Department {
  PRIMARY "name",
  PRIMARY "number",
  DERIVED "employees_number",
  MULTIVALUED "locations"
}

ENTITY Project {
  PRIMARY "number",
  PRIMARY "name",
  SIMPLE "location"
}

WEAK ENTITY Dependent OWNER Employee {
  COMPOSITE "key" {
    PARTIAL "name",
    PARTIAL "DoB"
  },
  SIMPLE "relationship",
  SIMPLE "gender"
}

REL Works_for {
  Employee (1, N),
  Department (20, N)
}

REL Manages {
  Employee <PARTIAL, 1>,
  Department <TOTAL, 1>,
  ATTRIBUTES { SIMPLE "start_date" }
}

REL Supervision {
  Employee <PARTIAL, 1>,
  Employee <PARTIAL, N>
}

IDEN REL Dependents_of {
  Employee <PARTIAL, 1>,
  Dependent <TOTAL, N>
}

REL Works_on {
  Employee <PARTIAL, N>,
  Project <TOTAL, N>,
  ATTRIBUTES { SIMPLE "hours" }
}

REL Controls {
  Department <PARTIAL, N>,
  Project <TOTAL, 1>
}