python-domain-modeling
/python-domain-modeling
Designs Python type annotations, domain objects, validation boundaries, dataclass/Pydantic models, invariants, interfaces, fixed choices, and object-copy semantics. Use when choosing ABC for owned nominal implementations versus Protocol for third-party structural compatibility, or when changing model behavior and boundary contracts. Never activate for dependency/version updates, translation, documentation-only edits, counting references, isolated syntax, or incidental modeling terms.
- Author
- autentisitet ↗
- Repository
- python-engineering-skills ↗
- Licence
- MIT
- Last repository change
- 12.11.2026
Assessment and security
- Files in this package
- 8
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Designs Python type annotations, domain objects, validation boundaries, dataclass/Pydantic models, invariants, interfaces, fixed choices, and object-copy semantics. Use when choosing ABC for owned nominal implementations versus Protocol for third-party structural compatibility, or when changing model behavior and boundary contracts. Never activate for dependency/version updates, translation, documentation-only edits, counting references, isolated syntax, or incidental modeling terms.
Original author description
Designs Python type annotations, domain objects, validation boundaries, dataclass/Pydantic models, invariants, interfaces, fixed choices, and object-copy semantics. Use when choosing ABC for owned nominal implementations versus Protocol for third-party structural compatibility, or when changing model behavior and boundary contracts. Never activate for dependency/version updates, translation, documentation-only edits, counting references, isolated syntax, or incidental modeling terms.
How it works
- Activation
- Start From the Data Lifecycle
- Separate Boundary Models From Domain Objects
- Distinguish Construction Rules From Lifetime Invariants
- Choose Interfaces and Fixed Choices Deliberately
- Implementation and Verification
- Required Output
SKILL.md preview
--- name: python-domain-modeling description: Designs Python type annotations, domain objects, validation boundaries, dataclass/Pydantic models, invariants, interfaces, fixed choices, and object-copy semantics. Use when choosing ABC for owned nominal implementations versus Protocol for third-party structural compatibility, or when changing model behavior and boundary contracts. Never activate for dependency/version updates, translation, documentation-only edits, counting references, isolated syntax, or incidental modeling terms. metadata: short-description: Choose Python models and interfaces while protecting boundaries and invariants --- # Python Domain Modeling ## Activation - **Keyword trigger:** the request substantively involves `typing.Any`, Protocol, ABC, Pydantic v2, `BaseModel`, `BaseSettings`, dataclass, Enum/Literal, domain models, invariants, `copy.copy`, `copy.deepcopy`, or alias preservation. - **Intent trigger:** the user asks to design or review Python type interfaces, including ABC versus Protocol ownership, configuration models, input models, domain objects, or fixed choices. - **Disclosure:** once when starting applicable work, briefly state: `Using $python-domain-modeling because this task involves ...`. - **Exit:** stop applying this skill when the task no longer concerns Python model or interface decisions. - **Do not trigger:** a term that appears only in a filename, dependency list, log, or unrelated context is insufficient. --- ## Start From the Data Lifecycle Before choosing dataclass or Pydantic, trace one real use case: 1. Where does data enter from HTTP, configuration, messages, files, or third-party SDKs? 2. Which layer converts an untrusted representation into accepted program values? 3. Which rules are input-format constraints, and which are domain invariants that must hold throughout object lifetime? 4. Who mutates, serializes, persists, or exports the object? 5. Should an error be rejected at the boundary, converted into a domain error, or handled by the caller? Read [references/decision-table.md](references/decision-table.md) for adjacent choices. Read [references/typing-interfaces.md](references/typing-interfaces.md), [references/pydantic-v2.md](references/pydantic-v2.md), [references/dataclass-guide.md](references/dataclass-guide.md), or [references/copy-semantics.md](references/copy-semantics.md) only when that area is relevant. Read [references/scenarios.md](references/scenarios.md) when multiple choices remain plausible. --- ## Separate Boundary Models From Domain Objects - Parse external requests, configuration, and messages at boundaries. Pydantic may own parsing, coercion, field errors, and protocol compatibility; `pydantic-settings` may own configuration sources and precedence. - Internal entities and value objects should express behavior and invariants. Do not introduce runtime validation merely to obtain type hints. - When boundary and domain semantics differ, use an explicit converter or named factory. Do not hide differences in field names, units, defaults, or nullability behind unexplained dictionary unpacking. - Reuse one model only when the external contract and internal concept truly share semantics, validation rules, serialization behavior, and change cadence. --- ## Distinguish Construction Rules From Lifetime Invariants - Use generated dataclass initialization when fields can be assigned directly. - Put construction-only cross-field validation, normalization, and derived-field calculation in `__post_init__`. - Do not rely only on `__post_init__` for rules that must survive later state changes. Use named behavior methods, immutable objects, or a setter only when public assignment is appropriate. - Use a read-only property for a value computed on access. Do not move construction logic into a property merely to keep `__init__` visually short. - A property does not reduce per-instance memory. Evaluate `slots=True` when compact layout matters, and verify with measurement. - Dataclass fields and same-named properties can conflict with generated initialization. Prefer `InitVar`, private storage, a named factory, or a regular class when input conversion is required. --- ## Choose Interfaces and Fixed Choices Deliberately - Avoid `Any` when the value has a knowable shape. Prefer a concrete type, generic parameter, union, Protocol, TypedDict, or validated boundary model. Use `Any` deliberately at truly dynamic/untyped boundaries and narrow it promptly. - Choose ABC or Protocol only after deciding whether nominal inheritance, shared implementation, runtime registration, or structural compatibility is required. - Do not create an interface merely because two classes currently share method names. Identify the stable capability required by a caller. - Choose Enum or Literal based on scope, reuse, serialization, and whether members require behavior. - After introducing Enum, verify JSON, database, CLI, and log values so an internal member name does not accidentally become an external contract. --- ## Implementation and Verification 1. Write down the trust boundary and object responsibility before implementation. 2. Keep parsing, domain construction, and serialization conversion in identifiable locations. 3. Test at least one valid construction, one invalid state, and one mutation path for each lifetime invariant. 4. When replacing an existing model, check call signatures, exception types, serialization, equality, hashing, copying, and defaults. 5. Use the smallest combination of modeling tools that expresses the actual constraints. When copying an object graph is part of a model change, define which outer/nested objects and aliases must be shared or reconstructed. Do not treat `deepcopy()` as "every object becomes new" or pickle as a generic deep-copy substitute. --- ## Required Output Report only the items relevant to the requested change; do not impose a full review on a small task. State: 1. where data crosses the trust boundary; 2. which rules are input constraints versus domain invariants; 3. which invariants are construction-only versus lifetime-long; 4. why the selected tool is preferable to adjacent choices; 5. where boundary, domain, and persistence conversions occur; and 6. which invalid states, mutations, and serialization contracts are tested.
Files in this package (8)
- SKILL.md 6 KB
- agents/openai.yaml 1 KB
- references/copy-semantics.md 2 KB
- references/dataclass-guide.md 2 KB
- references/decision-table.md 5 KB
- references/pydantic-v2.md 4 KB
- references/scenarios.md 2 KB
- references/typing-interfaces.md 2 KB
Versions
The database has no other skills named python-domain-modeling.
Database snapshot: 13.11.2026 · package version b81d3a48b257 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90python-dataclasses
Choose between dataclass, NamedTuple, and pydantic, and configure frozen, slots, and validation correctly. Use when modeling structured data in Python or reviewing class boilerplate. - 90geode-code-conventions
Apply GEODE's measured architecture, module and symbol naming, Python type/class, persisted schema, test, site, and versioning conventions. Use when adding or moving modules, choosing dataclass/Pydantic/Protocol/ABC forms, naming classes or files, designing stored data,… - 100domain-driven-design
DDD tactical patterns for complex business modeling including entities, value objects, aggregates, domain services, repositories, specifications, and bounded contexts. Python dataclass implementations with TypeScript alternatives. Use when building rich domain models, enforcing… - 100writing-data-models
Governs implementation and review of Python data modeling with Pydantic v2, dataclasses, SQLModel, SQLAlchemy 2.0 bridging, serialization, and immutability and performance constraints. Use when working with Pydantic BaseModel, dataclass, SQLModel (table=True/False), domain… - 100python
Guides Python development with modern idioms, tooling, and project structure. ALWAYS trigger on "python project", "pyproject.toml", "ruff", "mypy", "pytest", "poetry", "python setup", "type hints", "pydantic", "dataclass", "async python", "asyncio", "python anti-pattern",… - 100pydantic
Pydantic is a Python data validation and serialization library, based on type hints. Use this skill whenever you need to do relatively complex data modeling using Pydantic, e.g. when adding constraints, defining a model hierarchy with subclasses, etc.