Coreex Refdata

---
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"]
---

<!--
  AI workflow asset — dual-audience notice:
  - In the Avanade/CoreEx repository: this file is the authored source. Edit it here.
  - In a consumer repository: this file was generated by `dotnet new coreex-ai` (or refreshed via
    `dotnet new coreex-ai --force` / the `/coreex-docs-sync` skill). Do not hand-edit it directly —
    propose the change upstream in Avanade/CoreEx instead, then refresh once it is released.
-->

# 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`](references/workflow.md).

## Key References

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