Coreex Contract

---
name: coreex-contract
description: "Create or modify a hand-authored contract (DTO/entity) in a CoreEx domain. USE FOR: new root entity contract, new subordinate/request contract, modifying an existing contract (add property, add interface, wire ref-data), extracting a shared base class. DO NOT USE FOR: reference-data contracts (generated via coreex-refdata / *.CodeGen), Infrastructure persistence models (generated by *.Database CodeGen)."
argument-hint: "Optional: contract name, domain, root or subordinate, properties, identifier type"
tags: ["contracts", "dto", "source-generation", "coreex", "partial", "etag", "changelog"]
---

<!--
  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: Contract

Guides you through creating or modifying a hand-authored contract (DTO/entity) in `*.Contracts`. Covers root entities, subordinate types, request/response objects, and base class extraction.

## When to Use

- New root entity contract — independently identifiable, persisted, has its own API endpoint
- New subordinate, line-item, or request/response contract (accessed via a parent — may still carry its own identifier)
- Adding or changing properties on an existing contract
- Wiring a ref-data navigation property (`[ReferenceData<T>]`) on an existing contract
- Extracting a shared base class when ≥2 contracts repeat the same fields

## When Not to Use

- Reference data contracts (generated by `*.CodeGen` from `ref-data.yaml`) — use `coreex-refdata`
- Infrastructure persistence models (generated by `*.Database` CodeGen from `dbex.yaml`)
- Domain aggregates, entities, value objects — see `coreex-domain.instructions.md` and the `coreex-aggregate` skill (DDD domains only)

## Quick Reference

**Clarifying questions to ask before emitting any code:**
0. **Resolve from state first.** Read the solution-root `AGENTS.md` **Feature Configuration** for `refdata-enabled` (whether `[ReferenceData<T>]` wiring applies) and check whether a `*.Domain` project exists (aggregate-mapping context). Only ask for what is unresolved; re-state resolved values for confirmation.
1. Root or subordinate? (if not explicit)
2. Identifier type? (default `string?` — confirm before using any other type)
3. `IETag` needed? (default yes for root contracts — omit only on explicit request)
4. `IChangeLog` needed? (ask for root contracts — add when created/updated audit trail is required)
5. Sub-folder within `*.Contracts`? (default: flat root — only create one if requested)
6. `[Schema]` override? (only if user explicitly requests a custom event schema name/version)

**Key rules at a glance:**
- `[Contract]` + `partial` on **all** contract classes by default
- Only `[ReferenceData<T>]` properties are `partial` — never make plain properties `partial` (CS9248)
- `[ReadOnly(true)]` on all server-assigned fields (`Id`, `ETag`, `ChangeLog`, computed/derived)
- Every property needs a `<summary>` XML doc comment
- Same contract type for both API response and event payload — never split them

For full workflow, decision trees, and code examples see [`references/workflow.md`](references/workflow.md).

## Key References

- [`/.github/instructions/coreex-contracts.instructions.md`](/.github/instructions/coreex-contracts.instructions.md) — full contract conventions: interfaces, source generation, property rules, localization, inheritance
- [`/.github/instructions/coreex-conventions.instructions.md`](/.github/instructions/coreex-conventions.instructions.md) — XML doc comments, expression bodies, brace style
- Related skills: [`coreex-refdata`](../coreex-refdata/SKILL.md) (generated ref-data contracts), [`coreex-aggregate`](../coreex-aggregate/SKILL.md) (DDD domain object the contract maps to), [`coreex-repository`](../coreex-repository/SKILL.md) (mapping), [`coreex-app-service`](../coreex-app-service/SKILL.md) (consumes contracts)
- Illustrative examples (CoreEx sample — not present in your project):
  - [multi-contract examples](https://github.com/Avanade/CoreEx/tree/main/samples/src/Contoso.Products.Contracts) — base class, root entity, subordinate, ref-data extension
  - [request/response and subordinate contracts](https://github.com/Avanade/CoreEx/tree/main/samples/src/Contoso.Shopping.Contracts)