---
name: domain-modelling
description: Add or change classes in a d2 domain safely: one side per relationship, keys, then check the model and the objects. Use when the user asks to model something new or change a class.
---

# domain-modelling

Needs [[Skill:diesel2]] for the calls.

1. Read the model first: `GET /api/v2/domain/overview`. Reuse existing classes (see [[ModelTour]]) before adding new ones.
2. Pick the key: a stored class needs `@key`. Things that only exist inside another object (an address, a line item) get no key and are contained.
3. Declare each relationship on one side only. The other side is inferred, and the object browser shows it under "Used by".
4. Put the classes in a Spec topic of their own (`Spec:<name>`), or in [[mining-domain]] for this sample, and save it with `PUT`.
5. Check the reply's `domain` list and `GET /api/v2/domain/overview` for `errors`. Fix every error before going on; tell the user about the warnings.
6. If existing objects no longer fit (a new required field, say), either make the field optional with `?` or update the objects; `objects` in the reply lists the ones that failed to load.