aurora-schema

---

name: aurora-schema description: > Aurora YAML schema analysis and editing. Validates field names, descriptions, types, and module semantics following DDD best practices. Trigger: When analyzing or editing *.aurora.yaml files, improving field naming, adding descriptions, or validating schema semantics. license: MIT metadata: author: aurora version: "1.0" auto_invoke: "Analyzing or editing *.aurora.yaml files, schema validation, field semantics" allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task

When to Use

Use this skill when:

• 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
• Reviewing data type appropriateness
• Checking cross-module consistency

Always combine with:

• aurora-cli skill when regenerating after YAML changes
• aurora-project-structure skill for locating YAML files
• conventional-commits skill when committing schema changes

---

Critical Patterns

Module Description (REQUIRED)

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

Copy# ✅ 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

Copy# ❌ INCORRECT - Missing description
version: 0.0.1
boundedContextName: iam
moduleName: permission
aggregateProperties:
  - name: id

Description should explain:

1. What the module contains (main entity)
2. What it's used for (purpose)
3. How it relates to other modules in the bounded context

---

Field Naming Conventions

Anti-patterns:

Copy# ❌ BAD
- name: stat          # → status
- name: dt            # → createdAt
- name: qty           # → quantity
- name: active        # → isActive (boolean prefix)
- name: author        # → authorId (if it's a foreign key)
  type: id
- name: displayOrder  # → sort (standard name for ordering)
- name: order         # → sort (ambiguous, conflicts with order entity)
- name: position      # → sort (use sort for UI ordering)

# ✅ GOOD
- name: status
- name: createdAt
- name: quantity
- name: isActive
- name: authorId
  type: id
- name: sort          # Standard field for UI display ordering
  type: smallint
  unsigned: true

---

Field Descriptions (MANDATORY)

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

Copy# ❌ BAD - States the obvious
- name: price
  type: decimal
  description: The price of the book

# ✅ GOOD - Explains context and usage
- name: price
  type: decimal
  decimals: [10, 2]
  description: >
      Retail price in the store's base currency (configured in settings). Does
      not include taxes or discounts. Used as base for price calculations.

Include:

• Business context and constraints
• Default values and behavior
• Validation rules
• Examples for complex formats

Copy- name: isbn
  type: varchar
  maxLength: 17
  index: unique
  description: >
      International Standard Book Number in ISBN-13 format. Must be unique
      across all books. Validated against checksum algorithm. Example:
      978-3-16-148410-0

---

Type Selection Guide

---

Varchar Length Standards (Byte-Optimized)

IMPORTANT: When defining varchar fields, ALWAYS use one of these standard lengths.

These lengths are optimized for PostgreSQL byte storage efficiency:

Why these specific lengths?

1. Byte alignment: PostgreSQL stores varchar with a length prefix. These values optimize storage blocks.
2. Index compatibility: Lengths ≤ 2046 can be indexed efficiently in PostgreSQL.
3. UTF-8 consideration: Lengths account for multi-byte characters (up to 4 bytes per char).
4. URL compatibility: 2046 is just under the 2048 practical limit for URLs (IE/Edge limit, SEO sitemaps).

Selection guide:

Copy# ❌ Bad - arbitrary lengths
- name: username
  type: varchar
  maxLength: 50

- name: description
  type: varchar
  maxLength: 500

# ✅ Good - byte-optimized lengths
- name: username
  type: varchar
  maxLength: 64
  description: >
      User's display name. Max 64 characters.

- name: description
  type: varchar
  maxLength: 510
  description: >
      Brief description of the item. Max 510 characters.

Quick reference for common fields:

---

ID Fields (CRITICAL RULE)

Fields of type id MUST NOT have a length property.

Copy# ✅ CORRECT
- name: id
  type: id
  primaryKey: true
  description: >
      Unique identifier for the record. UUID v4 format, generated automatically
      on creation.

# ❌ INCORRECT - Remove length property
- name: id
  type: id
  length: 36  # ← DELETE THIS
  primaryKey: true

---

Cross-Module Consistency

Use the same field names across ALL modules for common concepts:

Copy# Standard 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

---

Analysis Workflow

1. Locate YAML Files

Copy# Find all Aurora YAMLs
fd -e yaml -e yml aurora

# Find specific module
fd "book.aurora.yaml"

2. Read and Analyze

Check for:

• Module has description before aggregateProperties
• All fields have meaningful descriptions
• Field names follow conventions (camelCase, boolean prefixes)
• No id type fields have length property
• Descriptions explain WHY, not WHAT
• Enum values are documented
• Types are appropriate for use case
• Consistency with similar modules

3. Generate Report

Copy## Analysis of [module].aurora.yaml

### Summary
- Total fields: X
- Fields without description: Y
- Naming improvements needed: Z
- Module has description: Yes/No

### Module Description ❌ (if missing)
**Suggested:**
```yaml
description: >
    [Purpose and role within bounded context]

Fields Without Description ❌

Naming Improvements ⚠️

Type Issues ⚠️

Copy
---

## Editing Workflow

### Creating Fields

```yaml
- name: publishedAt
  type: timestamp
  nullable: true
  description: >
      Timestamp when the book was published. NULL indicates unpublished.
      Automatically set when status changes to PUBLISHED.

Checklist:

• Name follows camelCase convention
• Boolean names have is*/has*/can* prefix
• Type is appropriate for use case
• Description explains context and usage
• No length property on id type fields
• Consistent with similar fields in other modules

Editing Fields

Only modify requested attributes:

Copy# Before
- name: status
  type: varchar

# After (changing to enum)
- name: status
  type: enum
  enumOptions: [DRAFT, PUBLISHED, ARCHIVED]
  description: >
      Current publication status. DRAFT: Not ready. PUBLISHED: Available to
      readers. ARCHIVED: Preserved but no longer available.

Deleting Fields

Always check dependencies first:

Copy# Search for field references
rg "fieldName" cliter/ -g "*.aurora.yaml"

If field is referenced in relationships:

1. Alert the user
2. Confirm deletion
3. Document affected modules

---

Common Patterns

Status Fields with Enum

Copy- name: status
  type: enum
  enumOptions: [PENDING, APPROVED, REJECTED, CANCELLED]
  defaultValue: PENDING
  description: >
      Workflow status. PENDING: Awaiting review. APPROVED: Accepted and active.
      REJECTED: Denied (see rejectionReason). CANCELLED: Withdrawn by user.

Soft Delete Pattern

Copy- name: deletedAt
  type: timestamp
  nullable: true
  description: >
      Soft delete timestamp. NULL means active record. When set, record is
      excluded from normal queries. Enables audit trail and recovery.

Money Fields

Copy- name: amount
  type: decimal
  decimals: [12, 2]
  description: >
      Monetary amount in smallest currency unit with 2 decimal places.
      Currency determined by currencyCode field.

- name: currencyCode
  type: char
  length: 3
  description: >
      ISO 4217 currency code (USD, EUR, GBP). Must be valid and supported.

Sort Order Fields

Copy- name: sort
  type: smallint
  unsigned: true
  nullable: true
  description: >
      Sort order for displaying records in user interfaces. Lower numbers
      appear first. NULL indicates no specific order preference (alphabetical
      fallback). Used to prioritize items in selection lists and forms.

Note: Always use sort instead of displayOrder, order, position, or sortOrder.

URL-Friendly Slugs

Copy- name: slug
  type: varchar
  maxLength: 2046
  index: unique
  description: >
      URL-friendly identifier. Lowercase, hyphenated. Auto-generated from name
      if not provided. Example: "my-awesome-product". Max 2046 chars for URL
      compatibility.

---

Commands

Copy# Find all Aurora YAMLs
fd -e yaml aurora

# Search for fields without descriptions
rg -A1 "^  - name:" cliter/ -g "*.aurora.yaml" | rg -v "description:"

# Find id fields with length (incorrect)
rg -A2 "type: id" cliter/ -g "*.aurora.yaml" | rg "length:"

# Check for missing module descriptions
rg -L "^description:" cliter/ -g "*.aurora.yaml"

# Search for field usage across modules
rg "fieldName" cliter/ -g "*.aurora.yaml"

# Validate YAML syntax
yamllint cliter/**/*.aurora.yaml

---

Decision Trees

Should I Edit or Just Analyze?

CopyUser explicitly requested edit? ────YES───> Edit mode
      │
      NO
      │
Is this an analysis request? ────YES───> Analysis mode
      │
      NO
      │
Ask user for clarification

What Type Should This Field Be?

CopyIs it a UUID identifier? ────YES───> type: id (NO length!)
      │
      NO
      │
Is it true/false? ────YES───> type: boolean (use is*/has*/can* prefix)
      │
      NO
      │
Is it money? ────YES───> type: decimal with decimals: [12, 2]
      │
      NO
      │
Fixed set of options? ────YES───> type: enum with enumOptions
      │
      NO
      │
Date and time? ────YES───> type: timestamp
      │
      NO
      │
Short text (< 255 chars)? ────YES───> type: varchar with maxLength
      │
      NO
      │
Long text? ────YES───> type: text
      │
      NO
      │
Review use case and choose appropriate type

---

Anti-Patterns to Avoid

---

Change Log Template

When making modifications:

Copy## Schema Changes - 2026-01-17

### tesla/model.aurora.yaml

#### Created
- `isActive` (boolean) - Flag to indicate if model is currently available

#### Modified
- `status`: Changed type from `varchar` to `enum` with options [ACTIVE, INACTIVE, DISCONTINUED]
- Module: Added `description` property explaining module purpose

#### Deleted
- `legacyCode` (varchar) - Removed after confirming no dependencies

#### Fixed
- `id`: Removed `length: 36` property (not needed for id type)

---

Resources

• Aurora Docs: Check aurora-cli skill for regeneration commands
• Project Structure: Use aurora-project-structure skill to locate YAMLs
• YAML Syntax: Run yamllint to validate syntax
• Cross-References: Search with rg to find field usage

---

Related Skills