The Three Specs

# Problems with traditional approach
API docs say: POST /users requires email field
Database has: users.email_address column
Test code: request.put("mail", value)  ← Inconsistent across all three

# entity_to_table_mapping.yml
entity_to_table_mapping:
  - user: users

-- DDL (schema.sql)
CREATE TABLE users (user_id INT PRIMARY KEY, email VARCHAR(255) NOT NULL);

# api-spec.yml
paths:
  /users:
    post:
      summary: create user
      requestBody:
        properties:
          email:
            type: string

When (No Actor) create user, call table:       # ← Maps to API Spec (summary: create user)
  | email             |
  | alice@example.com |

Then should exist a user, with table:           # ← Maps to Entity Spec (user → users)
  | email             |
  | alice@example.com |

API Spec adds required field: requestBody.properties adds department (required)
            ↓
Lint checks .feature: whether all "create user" call tables include the department field

DDL column change: users table renames email to email_address
            ↓
Lint checks .feature: whether all "user" with tables use the correct column name

Phase 1: Product Manager defines API Spec
         ↓
Phase 2: DBA designs database tables, creates Entity Spec
         ↓
Phase 3: QA writes .feature tests (tests will fail at this point)
         ↓
Phase 4: Developer implements features to make tests pass

src/test/resources/specs/api/
├── api-spec.yml          # Can be split into multiple files
├── auth-api.yml          # e.g., split by module
└── ...

openapi: 3.0.0
info:
  title: My Application API
  version: 1.0.0

paths:
  /punch:
    post:
      summary: punch          # ← Identifier for ApiCall and ResponseValidate instructions
      operationId: punch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agentId
                - punchType
              properties:
                agentId:
                  type: integer
                punchType:
                  type: string
                  enum: [IN, OUT]
                punchTime:
                  type: string
                  format: date-time
      responses:
        "200":
          description: Punch successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  recordId:
                    type: integer
                  agentId:
                    type: integer
                  punchType:
                    type: string
                  punchTime:
                    type: string
                  dailyWorkHours:
                    type: number

When (UID="$Agent.id") punch, call table:
  | agentId      | punchType | punchTime              |
  | $Agent.id    | IN        | @time("2026-01-27T09:00:00") |

Then punch(200) response, with table:
  | recordId | agentId | punchType |
  | &isNotNull | 1       | IN        |

src/test/resources/specs/data/
└── primary/
    ├── entity_to_table_mapping.yml   # Entity mapping
    ├── agents.sql                    # DDL (any filename, *.sql, multiple files supported)
    └── punch_records.sql

# entity_to_table_mapping.yml
entity_to_table_mapping:
  - agent: agents
  - punch record: punch_records

-- agents.sql
CREATE TABLE agents (
    agent_id INT PRIMARY KEY,
    name     VARCHAR(100) NOT NULL,
    email    VARCHAR(255) NOT NULL
);

-- punch_records.sql
CREATE TABLE punch_records (
    record_id  INT PRIMARY KEY,
    agent_id   INT NOT NULL,
    punch_type VARCHAR(10),
    punch_time DATETIME
);

Given prepare an agent, with table:
  | name    | email               |
  | Manager | manager@company.com |

Then should exist a punch record, with table:
  | agentId | punchType |
  | 1       | IN        |

Gherkin: agentId    → DB: agent_id
Gherkin: punchType  → DB: punch_type
Gherkin: punchTime  → DB: punch_time

src/test/resources/isa.yml

config:
  api:
    resource_path: specs/api                          # classpath, used by framework at runtime
    project_path: src/test/resources/specs/api        # source path, used by Lint for error reporting
  data:
    source:
      - name: primary
        resource_path: specs/data/primary             # classpath, used by framework at runtime
        project_path: src/test/resources/specs/data/primary  # source path, used by Lint for error reporting
        db_type: mssql

instructions:
  - name: Time control
    format: ^current time is "(?P<time>[^"]+)"$
    instruction_type: time_control

  - name: Data preparation
    format: ^prepare a (?P<entity>[\w\s]+), with table:$
    instruction_type: entity_setup

  - name: API call
    format: ^\((?:No Actor|UID="(?P<userId>\$[\w.]+)")\) (?P<summary>.+?), call table:$
    instruction_type: api_call

  - name: Response validation with API summary and status code
    format: ^(?P<summary>.+?)\((?P<status_code>\d{3})\) response,?\s*with table:$
    instruction_type: response_validate
    data_format: data_table

  - name: Database validation
    format: ^should exist a (?P<entity>[\w\s]+), with table:$
    instruction_type: entity_validate

  - name: Database non-existence validation
    format: ^should not exist a (?P<entity>[\w\s]+), with table:$
    instruction_type: entity_non_existence_validate

1. Add path definition in API Spec
2. Write .feature tests
3. Implement the API
4. Run tests to verify

1. Update DDL (*.sql)
2. If table name changes, update entity_to_table_mapping.yml mapping
3. If column name changes, update column names in .feature files
4. Run Lint to check consistency
5. Run tests to verify

1. Update request/response schema in api-spec.yml
2. Update expected results in related .feature tests
3. Modify API implementation
4. Run tests to verify

# ✅ Good summary: verb + noun, clearly describes the operation
summary: create user
summary: query order list
summary: update product inventory

# ❌ Avoid: too short or too technical
summary: create
summary: POST user
summary: updateInventoryById

# ✅ Use names familiar to business team
entity_to_table_mapping:
  - member: members
  - order: orders
  - product: products

# ❌ Avoid technical names
entity_to_table_mapping:
  - member_entity: members
  - tbl_order: orders

# Add Lint step in CI
# TODO: Command to be added

mvn test

dotnet test