| name | coreex-refdata |
| description | Add or modify a reference data type in a CoreEx domain. USE FOR: new ref-data entity (new table + seed rows + CodeGen), adding extra properties to an existing type, adding seed rows for an existing type, wiring an existing ref-data type into a contract. DO NOT USE FOR: non-reference-data entity tables (use coreex-db-migration), hand-authoring generated .g.cs contracts (always use CodeGen). |
| argument-hint | Optional: entity name(s), domain, extra properties beyond standard Code/Text, seed rows |
| tags | ["refdata","codegen","database","contracts","reference-data","coreex"] |
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 database side (*.Database) 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
- 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
(SQL Server / PostgreSQL — drives casing and script extension). 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 DB up to date (inspect-safe baseline) | *.Database | dotnet run -- database |
| Inspect table state | *.Database | dotnet run -- inspect <schema> <table> |
| New ref-data migration script | *.Database | dotnet run -- script refdata <schema> <table> |
| Add/amend seed rows | *.Database | Edit Data/ref-data.seed.yaml |
| Register table in EF model | *.Database | Edit dbex.yaml → tables: |
| Apply DB + regenerate EF models | *.Database | dotnet run -- All |
| Add/update entity definition | *.CodeGen | Edit ref-data.yaml → entities: |
| Generate all ref-data artefacts | *.CodeGen | dotnet run |
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 | Casing | Script ext |
|---|
| PostgreSQL | snake_case | .pgsql |
| SQL Server | PascalCase | .sql |
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
