CoreEx: Reference Data

Guides you through the complete end-to-end workflow for adding or modifying a reference data (Code/Text lookup) type in a CoreEx domain — covering both the persistence side (*.Database, relational DbEx or Cosmos provisioning) and the CodeGen side (*.CodeGen).

When to Use

• Adding a new reference data type — new table, seed rows, and generated contracts/services/repos
• Adding extra stored properties to an existing type (beyond the standard IReferenceData fields)
• Adding or amending seed rows for an existing type
• Modifying an existing type's pluralization or identifier type
• Making a type mutable (mutability — generated create/patch/activate/deactivate/delete endpoints and service)
• Wiring an existing ref-data type into a new or existing contract via [ReferenceData<T>]

When Not to Use

• Creating a non-reference-data entity table — use coreex-db-migration
• Provisioning the transactional outbox — use dotnet run -- script outbox <schema> <name> directly; see coreex-tooling.instructions.md
• Hand-authoring reference data contract .g.cs files — always go through CodeGen; only hand-author optional partial extension classes on top of the generated output
• Changes to the API controller, service, or repository generated by CodeGen — re-run CodeGen; never edit .g.cs files

Quick Reference

Resolve project-wide choices from state before asking. Read the solution-root AGENTS.md
Feature Configuration for refdata-enabled (gates this whole skill) and data-provider
(SqlServer / Postgres / Cosmos — drives whether the database step is DbEx or Cosmos provisioning, plus casing/seed shape). Only prompt for what is unrecorded;
re-state resolved values for confirmation.

Two separate dotnet run steps in two different projects — never conflate them.

Task	Project	Command / File
Bring persistence baseline up to date	*.Database	Relational: dotnet run -- database; Cosmos: inspect Program.ConfigureProvisionArgs(...) + run dotnet run -- All
Inspect table/container state	*.Database	Relational: dotnet run -- inspect <schema> <table>; Cosmos: review declared container ids + seed files
New ref-data persistence shape	*.Database	Relational: dotnet run -- script refdata <schema> <table>; Cosmos: keep ReferenceDataContainer("ref-data") and update its seed data / accessors
Add/amend seed rows	*.Database	Edit Data/ref-data.seed.yaml (relational or Cosmos ref-data container)
Register table in EF model	*.Database	Relational only: edit dbex.yaml → tables:
Apply persistence + regenerate EF models/accessors	*.Database	Relational: dotnet run -- All; Cosmos: dotnet run -- All (provisions/imports; no EF generation)
Add/update entity definition	*.CodeGen	Edit ref-data.yaml → entities:
Generate all ref-data artefacts	*.CodeGen	dotnet run

Mutability is opt-in and secured by default, but has no referential-integrity protection. Mutable endpoints require authorization by default ([Authorize]); use mutableAttribute to apply a specific policy/role or [AllowAnonymous] only when intentionally public. Delete/deactivate never check whether the code is still referenced elsewhere. Warn the user and point them at the PreCheckAsync hook — see "Mutable types" in references/workflow.md.

The Two YAML Files — Never Confuse Them

File	What it contains
*.CodeGen/ref-data.yaml	Entity/contract definitions (entities: with name, idType, properties)
*.Database/Data/ref-data.seed.yaml	Seed rows (Schema: → - $^Table: → rows)

Putting entity definitions in the seed file, or seed rows in the entity file, is the single most common mistake.

Polyglot Note

Provider	Persistence shape	Seed shape
PostgreSQL	snake_case tables + .pgsql scripts	Data/ref-data.seed.yaml under the schema key
SQL Server	PascalCase tables + .sql scripts	Data/ref-data.seed.yaml under the schema key
Cosmos	ReferenceDataContainer("ref-data") in ConfigureProvisionArgs(...)	Data/ref-data.seed.yaml keyed by ref-data, with grouped $^TypeName entries

Check the project's *.Database/Program.cs to confirm the provider in use.

For the full decision tree, YAML examples, seeding rules, and guardrails see `references/workflow.md`.

Key References

• `/.github/instructions/coreex-tooling.instructions.md` — ref-data.yaml structure, dbex.yaml, seed format, Script/All/Data commands
• `/.github/instructions/coreex-contracts.instructions.md` — [ReferenceData<T>], partial properties, global usings
• Related skills: `coreex-contract` (wires [ReferenceData<T>] into contracts), `coreex-db-migration` (ref-data table schema)
• Illustrative examples (CoreEx sample — not present in your project):
  • PostgreSQL CodeGen definition and its seed file
  • SQL Server CodeGen definition and its seed file
  • Cosmos CodeGen definition and its seed file