hex-domain-model
Use when creating or changing a domain entity, value object, enum or filter record — stdlib dataclasses, `__post_init__` invariants, identity versus value equality, when a bare primitive carrying a co
SKILL.mdplugins/pyhouse-hex/skills/hex-domain-model/SKILL.md
GitHubHex — Domain Model
The four data shapes of the domain layer. They share one substrate — stdlib only, no third-party imports — and a change that adds a capability usually adds several of them together, which is why they live in one place.
When to use vs. neighbours
Which of this skill's shapes a thing is → Choosing a shape, at the head of Rules. Outside it:
- The interface a repository or a capability must satisfy →
hex-domain-ports. - A rule needing another aggregate's state, or a domain capability →
hex-domain-service. - The single error catalog →
exception-catalog. - A DTO crossing the application boundary →
hex-application. A filter record may be reused there; the query DTO wraps it, plus the caller's scope where the caller is authenticated. - The request or response model on the wire →
hex-restapi-schema; a domain type is never serialized straight out. - Persistence of any of these →
hex-persistence(a relational store) orhex-store-repository(a client-style store). - The settings class the tunable variant's values come from →
python-settings; the lifetime rules its provider follows →hex-wiring; the provider itself is shown beside the template. - Testing an invariant, identity equality or the pinned enum member set →
hex-test-domain. - What the class and its module are called →
naming; one class per module and the re-export →python-packaging.
Template(s) — stdlib dataclasses and enums
Entity
from dataclasses import dataclass
from uuid import UUID
from ..exceptions import ValidationError
__all__ = ["Foo"]
@dataclass
class Foo:
id: UUID
name: str
note: str | None = None
def __post_init__(self) -> None:
if not self.name:
raise ValidationError("name must be non-empty", {"field": "name"})
def __eq__(self, other: object) -> bool:
if not isinstance(other, Foo):
return NotImplemented
return self.id == other.id
def __hash__(self) -> int:
return hash(self.id)
Every other aggregate — Bar, or Baz in hex-store-repository's key-value example — has this same
form with its own fields, in its own subdomain package. note exists to show an optional field — one a
partial update may leave or set, and a store round trip carries as None; an entity with no
such field has none.
Value object — standard case (value equality across all fields)
from dataclasses import dataclass
from ..exceptions import ValidationError
__all__ = ["FooQuota"]
@dataclass(frozen=True)
class FooQuota:
field_a: str
field_b: int
def __post_init__(self) -> None:
if self.field_b < 0:
raise ValidationError("field_b must be non-negative", {"field": "field_b"})
The @dataclass(frozen=True)-generated __eq__ / __hash__ compare all fields. Do not override them
in the standard case.
When a value object stores both a raw input and a normalized form — an email as typed and its
lowercased form — it overrides __eq__ and __hash__ to compare the normalized field only; otherwise
two semantically equal values compare unequal.
Value object — tunable variant (configuration the domain consumes)
A value object can serve as the domain-shaped view of an environment-tunable threshold (max upload
size, max page size, retention days). The form is identical — frozen dataclass, primitive fields, no
methods. For the file and class names, see naming.
from dataclasses import dataclass
__all__ = ["FooRetentionTunable"]
@dataclass(frozen=True)
class FooRetentionTunable:
retention_days: int
No field carries a default: the value is the deployment's, and a default here would turn a missing
setting into a silent wrong answer (python-settings rule 5).
Distinguishing characteristics:
- Sourced from a settings class at the composition root — a provider of its own reads each field off
the settings object and passes it. The binding, an add-on to
hex-wiring's base composition root, is process-lifetime;FooSettingsstands for whichever settings class declares the field (python-settings), bound inSettingsProviderlike any other:
class FoosProvider(Provider):
@provide(scope=Scope.APP)
def foo_retention_tunable(self, settings: FooSettings) -> FooRetentionTunable:
return FooRetentionTunable(retention_days=settings.foo_retention_days)
- Injected into domain services and application handlers, never into entities. Entities do not read tunables; services do.
- Every value-object rule still applies: frozen, no methods, primitive or VO fields only. Which
builtin each primitive field takes — an exact decimal quantity, an instant with an offset, an
identifier — is
python-style's.
Use this variant only when the value carries no domain meaning beyond "this is a knob to turn". If it
participates in the ubiquitous language — a FooTotal, a RetentionWindow with behaviour — it is an
ordinary value object.
Enum — StrEnum (the default, for string-valued sets)
from enum import StrEnum
__all__ = ["FooStatus"]
class FooStatus(StrEnum):
ALPHA = "ALPHA"
BETA = "BETA"
An enum may carry a pure method over its own values — ordering, ranking, membership — with no IO and
no other aggregate; the rank-ordered Role in hex-restapi-auth is the worked one, its self-reference
quoted because the catalogue bans from __future__ import annotations.
A set whose values are genuinely numeric is a plain Enum of the same form (python-style rule 12).
Filter sort enum
domain/foos/foo_sort.py, beside the filter that imports it (hex-conventions). One member per ordering
the list read offers, each naming a column and a direction; the repository maps every member to its
ordered column (hex-persistence).
from enum import StrEnum
__all__ = ["FooSort"]
class FooSort(StrEnum):
CREATED_AT_DESC = "created_at_desc"
CREATED_AT_ASC = "created_at_asc"
NAME_ASC = "name_asc"
Filter record
from dataclasses import dataclass
from .foo_sort import FooSort
__all__ = ["FooListFilter"]
@dataclass(frozen=True)
class FooListFilter:
name: str | None = None
sort: FooSort = FooSort.CREATED_AT_DESC
limit: int = 50
offset: int = 0
Rules
Choosing a shape
Inside this skill, pick by what the thing is:
- A thing with a UUID and a lifecycle → Entity.
- An immutable type defined by its content, or a primitive that carries a constraint, a unit or a rule → Value object.
- A closed set of named values → Enum. A set whose values are loaded at runtime, from
configuration or a store, is not closed → a Value object, with a lookup repository behind a port
(
hex-domain-ports). - A read-side parameter bag passed to a repository
list/count→ Filter record. - An environment-tunable threshold the domain consumes (max rows, retention days, quotas) → the tunable variant of a value object, not a service and not a settings class.
A predicate over a field carried by both the entity and a read-model of the same aggregate is a module-level function in the aggregate's package, taking the field values as parameters — never the same method written once per type, which drifts, nor a shared base, which the entity and value-object rules forbid.
Entity
- An entity is mutable and stays mutable — a plain
@dataclass, never frozen. An entity has a lifecycle; freezing it forces every state change through a copy, and the copy is a different object to everything holding the old one. - Identity equality is mandatory. Two entities are equal when their
idis equal and for no other reason, and the hash agrees. Field-wise equality makes a loaded row and the same row after an edit two different foos, so a set or a dict keyed by entity silently grows duplicates. - Invariants are checked at construction, in one place —
__post_init__under the dataclass substrate — one raise per rule, usingexception-catalogfor the error class. A rule enforced at the call site instead is a rule the next call site forgets; omit the hook entirely when there are no invariants. - Cross-aggregate rules do not go here. Uniqueness, authorization, "does referenced X exist" → a
domain service (
hex-domain-service). Tunable thresholds → the tunable variant above. An entity only checks invariants it can see from its own fields. - No inheritance. No base classes, no
ABC. Compose by holding other domain objects. - Row timestamps are never entity fields.
created_at/updated_atare a DB-managed table convention. A read that needs them returns a read-model DTO projected from the row.
Value object
- A primitive carrying a constraint, a unit or a rule is a value object, not a bare field. The
test is whether the value can be wrong on its own terms: a string that must match a form, a number
that must stay in a range or is denominated in something, a pair of values only meaningful together.
Left bare, the check lives at whichever call site remembered it, and the next one does not — which
is the same failure the entity's
__post_init__rule exists to prevent, one level down. Give it a type and check it once, at construction. A primitive with nothing but its builtin type behind it stays a primitive: an opaque identifier, a free-text note, a count that is simply a count. Wrapping those buys a name and pays for it in conversions at every boundary. Which builtin a scalar takes in the first place — an exact decimal quantity, an instant with an offset — ispython-style's. - A value object is immutable — a frozen dataclass. An invariant checked at construction stops holding the moment a field can be reassigned, and a mutable value cannot safely be shared or used as a key.
- No identity field. No
id: UUID. If one is called for, this is an entity. - Value equality. Use the dataclass-generated equality. Override
__eq__/__hash__only for the normalized-form escape hatch. - Invariants in
__post_init__. Useexception-catalogfor the error shape. Omit the method when there are none. - No inheritance. Compose, do not inherit.
- No cross-aggregate logic. Anything needing another aggregate's state is a domain service.
Enum
- A member's value is the value that leaves the process; whether the set is a
StrEnumor a plainEnumispython-stylerule 12. Never an integer enum for codes that are really strings — the mismatch surfaces in the database and on the wire, not here. - Member names follow
naming. For aStrEnumthe value is usually identical to the name; do not invent lowercased values unless the wire format requires them. - Module boundaries follow
python-packaging; module names follownaming. - Methods only when pure. Anything touching another aggregate, IO or external state is not an enum
method. Methods receive
selfand other enum values only. - No custom base class. Inherit from
StrEnumorEnumdirectly; no "abstract enum" hierarchies. - No constants pretending to be enums (
python-style).
Filter record
- Frozen dataclass, value equality. Generated
__eq__/__hash__— never override. - A collection-valued filter field defaults to an empty immutable collection, never to a mutable
one — see
python-stylefor the collection types. A mutable default would be one object every filter in the process shares and can change; an immutable default —frozenset()— cannot change, so it is safe to share. - Absence of a constraint is expressed as
None, never a sentinel value such as""or-1, which the adapter cannot distinguish from a caller who meant it. Annotation forms followpython-style. - Sort is an enum reference, never a bare string. See
python-packagingfor its module. - One pagination shape, explicitly. Either
limit: int+offset: int, both defaulted, orcursor: str | None. Never both. If it is not stated which, ask. The default page size is the project's decision, not the catalogue's — pick one bound, state it once, and keep every filter in the service on it. - No methods. A filter record is a passive data bag. Anything computed — translating a sort key to a SQL column, say — belongs in the repository adapter.
- No business invariants. A repository receives whatever the caller passed; range and authorization
checks live in the query handler. Default to no
__post_init__at all.
Inlined typing / import rules
These hold for all four shapes; the full rules are python-style and python-packaging.
- Stdlib only, plus relative domain imports. No third-party libraries — no Pydantic, no SQLAlchemy.
The usable set is
dataclasses,datetime,decimal,enum,uuid,collections.abc,typing; an enum module normally needs onlyenum. - No
from __future__ import annotations, anywhere in the project. X | None, neverOptional[X]. Collection fields arefrozenset[T]/tuple[T, ...], neverset/list.- Full annotations on every field and every method signature, including
-> Noneon__post_init__. - Default to no comments. Add one only when the why is non-obvious, one short line — never a multi-paragraph docstring.
Package wiring
Follow hex-architecture for file placement and python-packaging for module exports, package re-exports,
and imports, including the module-level predicate function above.
Hard stops
- Asked for behaviour that needs another aggregate's state → stop, use
hex-domain-service. - Asked for repository methods or persistence on any of these → stop, use
hex-domain-portsfor the interface andhex-persistencefor the adapter. - Asked for a filter-record method that translates the filter to SQL → stop, use
hex-persistence. - A filter record is asked to validate cross-aggregate state, or to range-check its own fields → stop, use
hex-application. - Asked for enum values persisted to a SQL column → stop, use
hex-persistencefor the column type and its mapping; the enum still belongs here.