Core Schema¶
This chapter is the canonical reference for the ESDM core schema. Every kind the schema defines has a page that lists its fields, their types, whether they are required, and the values they accept.
The machine-readable schema is identified by https://schema.esdm.io/core/v1 (hosting in preparation). The apiVersion field of every core document carries the same identifier without the https:// scheme.
Common Fields¶
Every core document, regardless of kind, carries the same top-level shape.
| Field | Required | Description |
|---|---|---|
apiVersion |
yes | The schema identifier. Must be exactly schema.esdm.io/core/v1 for core documents. |
kind |
yes | The kind of artifact this document describes. One of domain, subdomain, bounded-context, context-mapping, aggregate, dynamic-consistency-boundary, command, event, event-handler, policy, process-manager, read-model, query, value-object, domain-service, actor, external-system. |
name |
yes | The natural identifier of the artifact. Must follow the kebab-case name pattern. |
description |
no | Free-form prose describing the artifact. |
metadata |
no | A container for non-semantic attachments. Holds labels (string-to-string keys for selection and grouping) and annotations (string-to-string keys for tooling and provenance). Nothing else in the schema reads either. |
Scope¶
Most kinds carry a scope field that places the artifact inside the model hierarchy. The shape depends on the kind:
scope.domain– the document scopes to a Domain by name. Used by Subdomain, Bounded Context, Event Handler, Policy, Process Manager, External System.scope.boundedContext– the document scopes to a Bounded Context, identified by its Domain and Bounded Context name. Used by Aggregate, Dynamic Consistency Boundary, Read Model, Query, Value Object, Domain Service, Actor.scope.aggregate– the document scopes to an Aggregate, identified by Domain, Bounded Context, and Aggregate name. Used by Commands and Events that belong to an Aggregate.scope.dynamicConsistencyBoundary– the document scopes to a DCB. Used by Commands that target a DCB.
Domain documents carry no scope (they are top-level). Context Mapping documents carry no scope either; their endpoints can straddle Domains.
File Convention¶
Documents that follow this schema are stored as *.esdm.yaml files. A single file may contain multiple documents separated by --- (standard YAML multi-document syntax). The schema exposes both conventions through x-esdm-file-suffix and x-esdm-document-separator.
Project Layout¶
An ESDM project keeps schemas under a single schemas/ directory at the project root, one subdirectory per schema, and one file per version inside – schemas/core/v1.yaml, schemas/<extension>/v1.yaml. The user's own *.esdm.yaml model files live alongside schemas/. The x-esdm-project-layout field on the schema captures this convention so generators can materialize it without guessing.