ERDL Quickstart Guide

Prerequisites

Make sure you've completed the following:

• Deployed the OpenOBA open-source prototype (see Deployment Guide)
• Confirm the erdl/ directory exists (in the project root)
• Have a text editor ready (VS Code recommended)

Step 1: Create an ERDL File

Create a new file in the erdl/ directory. Naming convention: industry-name.erdl. Example:

# File path: erdl/my-retail.erdl

namespace: industry.my_retail
version: "1.0.0"
name: "My Retail System Definition"

Step 2: Define an Entity

Entities correspond to your business objects. Each entity auto-generates a database table, API, and frontend form.

entity Product:
  productName: String!           # ! means required
  description: String            # no ! means optional
  price: Float!
  category:
    type: String!
    enum: [ELECTRONICS, CLOTHING, FOOD, OTHER]

Type reference:

Type	Description	Example
String!	Required string	Product name
String	Optional string	Notes
Int!	Required integer	Stock quantity
Float!	Required float	Retail price
Boolean	Boolean	Is active

Step 3: Add Industry Aliases

Aliases map your industry jargon to standard field names. When the Agent hears "selling price," it auto-translates to retailPrice.

aliases:
  Product:
    selling price: retailPrice
    item code: productCode
    listing date: listingDate

Step 4: Declare Executable Actions

Actions tell the Agent what it can do with this entity.

actions:
  create_product:
    description: "Create a new product"
    params:
      productName: String!
      price: Float!
      category: CategoryEnum!
    requireApproval: true          # requires human confirmation

  update_price:
    description: "Adjust product price"
    params:
      productCode: String!
      newPrice: Float!
    action constraints (optional, define business rule boundaries)

Step 5: Save & Verify

After saving the file (Ctrl+S), the system will automatically:

1. Parse the ERDL file
2. Register with the ERDL Registry
3. Generate the corresponding database migration
4. Agent can immediately use the new definitions

You can view loaded files and their status in the admin console's ERDL Manager page.

FAQ

Do I need to restart after modifying an .erdl file?

No. ERDL supports Hot Reload—save and it's live.

How many Entities can I define?

Unlimited. Each Entity maps to one database table.

Can I modify enum values?

Yes, but be cautious when adding or removing values—removing an existing enum value may affect existing data.

What constraints do Actions support?

Actions support declarative definition of parameter valid ranges and business boundary conditions. See the whitepaper for full syntax details.