When to Use

• Analyzing *.aurora.yaml files for quality and consistency

• Editing YAML schemas (creating, updating, or deleting fields)

• Validating field naming conventions and descriptions

• Ensuring module descriptions explain purpose and context

Reference files (loaded on demand):

• type-reference.md — Type selection guide, varchar lengths, relationship rules

• examples.md — Common patterns, analysis workflow, change log template

Always combine with: aurora-cli , aurora-project-structure , conventional-commits

Critical Patterns

Module Description (REQUIRED)

Every *.aurora.yaml must have a description property before aggregateProperties: .

✅ CORRECT

version: 0.0.1 boundedContextName: iam moduleName: permission description: > Module containing the permissions associated with each bounded context, to be used to manage access to each API. aggregateProperties: - name: id

Description should explain: (1) What the module contains, (2) What it's used for, (3) How it relates to other modules.

Mandatory Fields (REQUIRED in all modules)

Order: id → rowId → ... campos ... → createdAt → updatedAt → deletedAt

• name: rowId type: bigint index: unique autoIncrement: true nullable: false description: > Auto-incrementing sequential identifier for internal ordering and legacy compatibility.

• name: createdAt type: timestamp nullable: true description: Timestamp when the record was created. Part of audit trail.

• name: updatedAt type: timestamp nullable: true description: Timestamp when the record was last modified. Part of audit trail.

• name: deletedAt type: timestamp nullable: true description: Soft delete timestamp. NULL = active record.

Field Naming Conventions

Pattern Use For Examples

camelCase

All field names firstName , orderDate , totalAmount

is* , has* , can*

Boolean flags isActive , hasChildren , canEdit

*At

Timestamps createdAt , updatedAt , publishedAt

*Date

Date-only fields birthDate , startDate , endDate

*Id

Foreign keys authorId , categoryId , parentId

sort

Display/UI ordering sort (NOT displayOrder or order )

Anti-patterns: stat → status , dt → createdAt , qty → quantity , active → isActive

Field Descriptions (MANDATORY)

Every field MUST have a description that explains WHY, not WHAT:

❌ BAD

• name: price type: decimal description: The price of the book

✅ GOOD

• name: price type: decimal decimals: [10, 2] description: > Retail price in the store's base currency. Does not include taxes or discounts. Used as base for price calculations.

ID Fields (CRITICAL RULE)

Fields of type id MUST NOT have a length property.

✅ CORRECT

• name: id type: id primaryKey: true

❌ INCORRECT

• name: id type: id length: 36 # ← DELETE THIS primaryKey: true

Relationship Fields (CRITICAL RULE)

Side Has FK? Use

Child/Many (invoice-line) YES type: id

• relationship block inside

Parent/One (invoice) NO type: relationship (navigation only)

Many-to-many NO type: relationship

• pivot config

⚠️ NEVER define both invoiceId (type: id) AND invoice (type: relationship) in the SAME module.

✅ child.aurora.yaml - ONLY the FK field

• name: parentId type: id relationship: type: many-to-one field: parent aggregateName: MyParent modulePath: my-context/parent

✅ parent.aurora.yaml - ONLY the navigation property

• name: children type: relationship relationship: type: one-to-many aggregateName: MyChild modulePath: my-context/child key: parentId

Cross-Module Consistency

Use the same field names across ALL modules:

• name: id # Not: ID, _id, uuid, identifier
• name: createdAt # Not: created, createdDate, createTime
• name: updatedAt # Not: updated, modifiedAt, updateTime
• name: deletedAt # Not: deleted, removedAt, deletionDate
• name: isActive # Not: active, enabled, status

Index Names (63-char limit)

PostgreSQL limits index names to 63 characters. Use indexName with abbreviated name:

• name: administrativeAreaLevel1Id type: id index: index indexName: bpp_partner_addr_admin_area_lvl1_id

Analysis Checklist

• Module has description before aggregateProperties

• Has rowId , createdAt , updatedAt , deletedAt

• All fields have meaningful descriptions (WHY, not WHAT)

• Field names follow conventions (camelCase, boolean prefixes)

• No id type fields have length property

• Enum values are documented

• Types are appropriate for use case → see type-reference.md

• No duplicate relationship definitions

• Consistency with similar modules

Commands

fd -e yaml aurora # Find all Aurora YAMLs rg -L "^description:" cliter/ -g ".aurora.yaml" # Missing module descriptions rg -L "name: rowId" cliter/ -g ".aurora.yaml" # Missing rowId rg -A2 "type: id" cliter/ -g "*.aurora.yaml" | rg "length:" # id fields with length (bad)

Anti-Patterns

❌ Don't ✅ Do

Skip module description Always add description before aggregateProperties

Skip mandatory fields Always include rowId + timestamps

Use abbreviations (dt, qty) Full words (createdAt, quantity)

Name booleans without prefix Use is*/has*/can* prefix

Add length to id type fields Never specify length for id type

Write "The price" as description Explain context and usage

Use float for money Use decimal with proper scale

Duplicate relationship definitions FK side: type: id , inverse: type: relationship

Related Skills

Skill When to Use Together

aurora-cli

After editing YAML, regenerate with aurora load back module

aurora-project-structure

To locate YAML files in correct directories

conventional-commits

When committing schema changes