How to Define a Custom Domain Model

Built-in presets cover common domains, but most projects need adjustments. This guide shows how to extend a preset with your own roles, relations, and matrices.

Initialize from a preset

Start from the closest built-in preset, then customize:

npx antora-tracer preset init -n requirements-engineering -o ./config/

This writes the preset’s full configuration to ./config/traceability.yml. Edit this file to add your domain-specific roles and relations.

See Presets Reference for the complete structure of each built-in preset.

Add a new role

Say your project uses use cases alongside requirements. Add a use_case role:

roles:
  - requirement
  - design
  - test
  - use_case       (1)
1 New role added to the preset’s existing list

Define relations for the new role

Define which relations connect use_case to other roles. Each relation declares a reverse — the authorable name for the same edge seen from the other side:

relations:
  # ... existing relations from preset ...

  use_case:
    requirement:
      leads_to:
        reverse: is_derived_from   (1)
1 The reverse name. A requirement can author `` — it is allowed automatically.

The leads_to relation is now valid from use_case items. The reverse is_derived_from is valid from requirement back to use_case, without declaring it separately.

Add a custom matrix

Add a matrix that cross-references use cases against requirements:

matrices:
  # ... existing matrices from preset ...
  - name: usecases-to-requirements
    description: "Which requirements each use case motivates"
    rows: use_case
    columns:
      - requirement
    coverageRelations:
      requirement:
        - leads_to

Point your playbook at the custom config

Update antora-playbook.yml:

antora:
  extensions:
    - require: antora-tracer/antora-extension
      config:
        configPath: ./config/traceability.yml

The configPath takes precedence over preset. The extension loads your file and validates it against the schema.

Use the extends field for partial overrides

You don’t need to copy the entire preset. Use extends to only declare what you’re changing:

extends: requirements-engineering   (1)

roles:
  - use_case

relations:
  use_case:
    requirement:
      leads_to:
        reverse: is_derived_from

matrices:
  - name: usecases-to-requirements
    description: "Which requirements each use case motivates"
    rows: use_case
    columns:
      - requirement
    coverageRelations:
      requirement:
        - leads_to
1 Pulls in the full requirements-engineering preset, then merges your changes on top

The extends field deep-merges — your roles are added, relations are merged, and matrices are replaced by name. You only write what’s different from the preset.

Extend a preset from another preset

You can also compose presets: build one preset on top of another instead of copying it. In a preset YAML file, declare the parent with a top-level extends field next to name:

name: medical-safety
version: 1.0.0
description: requirements-engineering plus use-case traceability
extends: requirements-engineering   (1)

traceability:
  roles:
    - use_case

  relations:
    use_case:
      requirement:
        leads_to:
          reverse: is_derived_from

  matrices:
    - name: usecases-to-requirements
      description: "Which requirements each use case motivates"
      rows: use_case
      columns:
        - requirement
      coverageRelations:
        requirement:
          - leads_to
1 Deep-merges the parent’s roles, relations, and matrices under this preset’s overrides

The same merge rules apply as config-level extends: roles are unioned, relations are merged, and matrices are replaced by name. The child wins on conflict. Inheritance chains resolve transitively, and a preset that extends itself — directly or through a chain — is rejected.

Place your custom preset in a presets/ directory, then reference it from traceability.yml with extends:.

Validate your config

After editing traceability.yml, run a validation check:

npx antora-tracer validate -i modules/ --config ./config/traceability.yml

This catches: - Unknown roles referenced in relations - Invalid matrix row/column roles - Missing reverse declarations

Related