AIR-DML

AI-Ready Data Modeling Language

The Open Standard for AI-Ready Data Modeling

AIR-DML is an extended DBML (Database Markup Language) parser designed for AI-driven development. It adds powerful features for modern data modeling while maintaining full backward compatibility with standard DBML.


Used In Production

Mode-ai - AI-Powered Data Modeling Tool

Generate ER diagrams from natural language using AI. Mode-ai is the reference implementation of AIR-DML, showcasing the full potential of AI-ready data modeling.

- Natural language to ER diagram generation
- Interactive visual editor with drag & drop
- Export to SQL, DBML, and more

Features

✨ AI-Optimized: Designed for AI language models to understand and generate database schemas
🏗️ Domain-Driven Design: Built-in support for bounded contexts via Area
🌍 Multilingual: Logical names (aliases) in any language
🎨 Visual Design: Coordinate and color information for diagram rendering
🔄 Polyglot Persistence: Different database types per area
📦 Extends DBML: Fully compatible with standard DBML syntax
💬 Comment Preservation: Leading comments are preserved and associated with elements

Installation

``bash
npm install air-dml
`

Quick Start

`typescript
import { parseAirDML, exportToAirDML } from 'air-dml';

// Parse AIR-DML text
const airDmlText =
Project "My Project" {
database_type: 'PostgreSQL'
}

// ユーザー管理
Table users [alias: "ユーザー", pos_x: 100, pos_y: 100, color: "#1976D2"] {
id serial [pk, alias: "ユーザーID"]
username varchar(100) [not null, unique, alias: "ユーザー名"]
email varchar(255) [not null, unique, alias: "メールアドレス"]
created_at timestamp [not null, alias: "作成日時"]
}

// プロフィール情報
Table profiles [alias: "プロフィール", pos_x: 500, pos_y: 100] {
id serial [pk, alias: "プロフィールID"]
user_id integer [fk, not null, unique, alias: "ユーザーID"]
full_name varchar(200) [alias: "氏名"]
bio text [alias: "自己紹介"]
}

Ref: profiles.user_id - users.id

Area "User Management" [
pos_x: 50,
pos_y: 50,
width: 600,
height: 300,
color: "#1976D2"
] {
users
profiles

database_type: "PostgreSQL"

CommonColumns: [
created_at timestamp [not null, alias: "作成日時"]
updated_at timestamp [not null, alias: "更新日時"]
]

Note: "ユーザー管理領域"
}
;

const diagram = parseAirDML(airDmlText);
console.log(diagram);

// Export back to AIR-DML
const output = exportToAirDML(diagram);
console.log(output);
`

AIR-DML Syntax

$3

`dbml
Table table_name [alias: "論理名", pos_x: 100, pos_y: 200, color: "#1976D2"] {
column_name data_type [constraints, alias: "カラム論理名"]

Note: "テーブルの説明"
}
`

$3

| Constraint | Description | Example |
|------------|-------------|---------|
| pk | Primary Key | id serial [pk] |
| fk | Foreign Key (use with Ref) | user_id integer [fk] |
| unique | Unique constraint | email varchar [unique] |
| not null | NOT NULL constraint | name varchar [not null] |
| increment | Auto increment | id integer [pk, increment] |
| alias: "name" | Logical name | [alias: "ユーザーID"] |
| note: "desc" | Column description | [note: "説明"] |

$3

`dbml
Ref: table_a.column > table_b.column // Many-to-One (A → B)
Ref: table_a.column < table_b.column // One-to-Many (A ← B)
Ref: table_a.column - table_b.column // One-to-One
Ref: table_a.column >< table_b.column // Many-to-Many
Ref: table_a.column ~ table_b.column // AI-inferred (undetermined)
`

$3

`dbml
Area "Area Name" [
pos_x: 50,
pos_y: 50,
width: 600,
height: 300,
color: "#1976D2"
] {
table1
table2

database_type: "PostgreSQL"

CommonColumns: [
created_at timestamp [not null, alias: "作成日時"]
updated_at timestamp [not null, alias: "更新日時"]
]

Note: "Area description"
}
`

AI Generation Guidelines

When using AI to generate AIR-DML, follow these rules:

Required:
- Use double quotes for alias values: alias: "論理名" ✅
- Do NOT use single quotes: alias: '論理名' ❌
- Mark foreign key columns with [fk]
- Define relationships separately with Ref:
- Do NOT add inline comments after column definitions

Example Output:

`dbml
// 定期購入機能
Table subscriptions [alias: "定期購入"] {
id serial [pk, alias: "定期購入ID"]
user_id integer [fk, not null, alias: "ユーザーID"]
product_id integer [fk, not null, alias: "商品ID"]
status text [not null, alias: "ステータス"]
created_at timestamp [not null, alias: "作成日時"]
}

Ref: subscriptions.user_id > users.id
Ref: subscriptions.product_id > products.id
`

For complete AI generation guidelines, see SPECIFICATION.md Section 5.

API Reference

$3

Parse AIR-DML text into a Diagram object.

Parameters:
- airDmlText - AIR-DML formatted text
- diagramId - Optional diagram ID

Returns: Diagram object

$3

Export a Diagram object to AIR-DML text.

Parameters:
- diagram - Diagram object

Returns: AIR-DML formatted text

Type Definitions

`typescript
interface Diagram {
id: string;
name: string;
project?: string;
database?: string;
tables: Table[];
references: Reference[];
areas?: Area[];
createdAt?: string;
updatedAt?: string;
note?: string;
}

interface Table {
id: string;
name: string;
logicalName?: string; // alias
columns: Column[];
color?: string;
pos?: Position;
areaIds?: string[];
note?: string;
leadingComments?: string[]; // v1.2.0+
}

interface Column {
name: string;
logicalName?: string; // alias
type: DataType;
typeParams?: string;
pk?: boolean;
fk?: boolean;
unique?: boolean;
notNull?: boolean;
increment?: boolean;
note?: string;
leadingComments?: string[]; // v1.2.0+
}

interface Reference {
id: string;
fromTable: string;
fromColumn: string;
toTable: string;
toColumn: string;
type: RelationshipType;
swapEdge?: boolean;
leadingComments?: string[]; // v1.2.0+
}

interface Area {
id: string;
name: string;
tables: string[];
color?: string;
pos?: Position;
width?: number;
height?: number;
labelHorizontal?: 'left' | 'center' | 'right';
labelVertical?: 'top' | 'center' | 'bottom';
databaseType?: string;
commonColumns?: Column[];
note?: string;
leadingComments?: string[]; // v1.2.0+
}
`

Comparison: DBML vs AIR-DML

| Feature | DBML | AIR-DML |
|---------|------|---------|
| Focus | Database schema | AI-ready + Business context |
| Logical names | ❌ | ✅ alias attribute |
| Area management | TableGroup (basic) | Area (extended: CommonColumns, database_type) |
| Visual info | ❌ | ✅ Coordinates, colors, sizes |
| Multi-DB | Project-level | Area-level (polyglot persistence) |
| AI optimization | ❌ | ✅ LLM-friendly design |
| Comment preservation | ❌ | ✅ Leading comments (v1.2.0+) |

Changelog

$3

- Breaking: Removed default column constraint from syntax
- Simplified parser by removing inconsistent quote handling for default values

$3

- Major: Replaced @dbml/core dependency with custom hand-written recursive descent parser
- Full AIR-DML syntax support without external dependencies
- Improved error messages in Japanese
- Better handling of Japanese identifiers and comments

$3

- Bug fixes for Area parsing with Japanese names
- Improved comment preservation
- Added AI generation guidelines to specification

$3

- Added leading comment preservation for Tables, References, and Areas
- Added leadingComments field to type definitions
- Export comments back to AIR-DML format

$3

- Added labelHorizontal and labelVertical attributes for Areas
- Added swapEdge` attribute for References
- Improved Area attribute parsing

$3

- Initial release
- Core AIR-DML parsing and export
- Support for alias, pos_x, pos_y, color attributes
- Area with CommonColumns and database_type

Specification

For the complete AIR-DML specification, see SPECIFICATION.md.

License

Apache-2.0 License - see LICENSE file for details.

AIR-DML extends DBML (also Apache-2.0).

Credits

- Created by: Data-mination Partners
- Technical collaboration: Claude Opus 4.5 (Anthropic)
- Based on: @dbml/core by Holistics

Links

- GitHub Repository
- npm Package
- AIR-DML Specification
- Mode-ai - Reference implementation (AI-Powered Data Modeling Tool)

---

Trademarks

AIR-DML™ (AI-Ready Data Modeling Language) is a trademark of Datamination Partners Co., Ltd.
Trademark Application No. 2026-000274 (Japan)

AIR-DML™ — The Open Standard for AI-Ready Data Modeling.