Scenarios

Scenarios let you document a use-case slice of a schema: which models and enums matter, plus an optional ordered path for ERD highlight simulation. Builders can share flows (billing, issue lifecycle, onboarding) without leaving the docs UI.

Scenarios attach to a catalog version via schemaId. That id is either a standalone source id or a unified[].id.

Example

TypeScript

import { defineProject, prisma, sql } from "ozzyrm";

export default defineProject({
  output: "./.ozzyrm",
  schemas: [
    prisma({ id: "app-prisma", include: ["./prisma"] }),
    sql({ id: "legacy-sql", include: ["./sql/legacy.sql"] }),
  ],
  unified: [
    {
      id: "company-schema",
      sources: ["app-prisma", "legacy-sql"],
      file: "company",
      version: "1.0.0",
    },
  ],
  scenarios: [
    {
      id: "issue-lifecycle",
      label: "Issue lifecycle",
      description:
        "Org owns a project, issues are filed, then discussed via comments.",
      schemaId: "company-schema",
      models: [
        "Organization",
        "Project",
        "Issue",
        "Comment",
        "User",
        "IssueAssignee",
      ],
      enums: ["IssueStatus", "Role"],
      path: ["Organization", "Project", "Issue", "Comment"],
    },
    {
      id: "billing-flow",
      label: "Billing flow",
      description:
        "How invoices hang off an organization down to line items and products.",
      schemaId: "company-schema",
      models: [
        "Organization",
        "BillingAccount",
        "Invoice",
        "InvoiceLine",
        "Product",
        "Price",
        "Subscription",
      ],
      enums: ["InvoiceStatus", "SubscriptionStatus"],
      path: ["Organization", "Invoice", "InvoiceLine", "Product"],
    },
  ],
});

Scenario fields

Field	Type	Required	Notes
`id`	`string`	yes	Kebab-case only (`billing-flow`). Must be unique
`label`	`string`	yes	Non-empty display title
`schemaId`	`string`	yes	Catalog version id (source `id` or unified `id`)
`models`	`string[]`	yes	At least one model name that exists on that schema
`description`	`string`	no	Short summary in the UI
`enums`	`string[]`	no	Enum names that exist on that schema
`path`	`string[]`	no	Ordered model names for ERD path highlight

Path rules

When you set path:

Every model in path must exist on the schema
Every model in path must also appear in models (PATH_MODEL_NOT_IN_SCENARIO)
Adjacent hops must have a relation in the graph (PATH_RELATION_MISSING)

The resolved scenario stores pathEdges for the ERD highlight.

Validation (fail closed)

Invalid scenarios reject the whole catalog load with aggregated diagnostics:

Code	When
`INVALID_SCENARIO_ID`	Missing id or not kebab-case
`DUP_SCENARIO_ID`	Two scenarios share the same id
`INVALID_SCENARIO_LABEL`	Empty label
`UNKNOWN_SCHEMA_ID`	`schemaId` not in the catalog
`EMPTY_SCENARIO_MODELS`	No valid models
`UNKNOWN_MODEL`	Model missing from schema
`UNKNOWN_ENUM`	Enum missing from schema
`PATH_MODEL_NOT_IN_SCENARIO`	Path model not listed in `models`
`PATH_RELATION_MISSING`	No relation between adjacent path models

Scenario config is validated together with unified merge rules. Fix diagnostics before the docs UI can load a fresh catalog.

What you see in the UI

Scenario entries appear in the schema sidebar for that catalog version
Opening a scenario shows the filtered model set and description
The ERD can highlight the path when relations exist between hops

Example

Scenario fields

Path rules

Validation (fail closed)

What you see in the UI

Related

On this page