# Experimental Domain Modeling Grammar **Status: Lab · optional working hypothesis · expected to change.** Use it when a flat brief is no longer enough, and report which distinctions help or create unnecessary modeling overhead. Use this draft when a Domain Context Brief needs more structure than a flat list of concepts, but a team does not need a full software architecture or ontology method. The grammar is experimental. It provides shared language for grouping domain knowledge, scoping context for AI skills and agents, and translating one domain model into different product representations. Test whether these distinctions improve real work before making them recommended defaults. > The framework should be authoritative about how domain knowledge is represented and validated. Domain experts and authoritative sources remain responsible for what is true in a particular domain. ## Why Group Concepts A flat object list can reveal useful nouns, but it does not explain: - which parts of the domain solve different problems - where the same term carries different meanings - which concepts matter for a particular workflow or agent - which concepts users should see and which should remain backstage - where rules, language, and sources of truth stop being consistent The goal is not to force every concept into one hierarchy. Model the domain as a graph, then use several grouping lenses to make different boundaries visible. ## Draft Grouping Primitives ### Domain The broad real-world or proposed product territory being modeled. A domain establishes the outer boundary of the inquiry. It names the world that matters and what is intentionally excluded. ```text Domain: Residential renovation permitting Includes: permit research, applications, inspections, and approvals Excludes: performing construction work or issuing municipal approvals ``` ### Domain Area A coherent area of responsibility, capability, work, or expertise within the domain. Domain areas divide the problem space. They help a team see the major capabilities in the domain, identify expertise and ownership, and decide which areas are central, supporting, or external to the product. `Domain area` is the default lightweight term in this framework. A DDD practitioner may recognize a similar concern in the idea of a subdomain. ```text Domain areas: - project planning - permit application - document preparation - inspections - contractor credentials - municipal review ``` A concept may participate in more than one domain area. ### Meaning Context A boundary within which terms, definitions, rules, states, relationships, and sources of truth remain internally consistent. Meaning contexts divide semantic models. Create or name a separate context when: - the same term has different definitions - concepts follow different rules or lifecycles - different authorities determine what is true - information must be translated between groups - two models can change independently `Meaning context` is the default product-facing term in this framework. It borrows the semantic boundary concern of a DDD bounded context without requiring teams to define software architecture. ```text Meaning context: Municipal inspection "Passed" means the assigned municipal inspector recorded that the inspected work satisfied the applicable inspection requirements. This is different from: - a contractor marking work ready for inspection - a homeowner considering the work complete ``` > Canonical does not mean universally identical. It means authoritative within a declared context. ### Domain Concept Something meaningful that people, organizations, systems, or agents need to reason about. Concepts are the meaningful elements that participate in relationships, rules, events, actions, states, and sources of truth. OOUX objects are often the subset of domain concepts that users need to recognize, navigate to, inspect, or act upon. Use lightweight concept kinds when they improve clarity: | Concept kind | Purpose | Examples | | --- | --- | --- | | Actor or role | Participates, decides, owns, approves, or is affected | Homeowner, contractor, inspector | | Durable object | Retains identity and changes over time | Project, permit application, inspection | | Record or evidence | Documents, supports, or traces a claim or action | Application form, inspection report | | Classification or value | Describes, categorizes, or measures another concept | Permit type, jurisdiction code | | Event | Records something meaningful that happened | Application submitted, inspection passed | | Decision | Records a judgment or determination | Permit approved, correction required | | Rule or policy | Constrains what must, may, or cannot happen | Inspection required before occupancy | | Source or authority | Settles a particular type of fact or decision | Municipal permitting system | These kinds are descriptive lenses, not mandatory technical implementation types. Some things can be both a named concept and part of the domain mechanics. For example, `Inspection Passed` can be modeled as an event concept that records an occurrence, while event mechanics explain what caused it and what changes after it. ### Domain Slice A purpose-specific selection of concepts, relationships, rules, states, events, sources, and authority boundaries drawn from the larger domain model. Domain slices scope context for a product feature, design project, agent skill, workflow prompt, evaluation, or stakeholder review. They should include enough context to preserve meaning without loading the entire domain. ```text Domain slice: Prepare for inspection Purpose: Help a homeowner and contractor determine whether a scheduled inspection is ready to proceed. Includes: - Project - Inspection - Requirement - Contractor - Document - Scheduled Date - Correction Notice - municipal inspection rules and records Excludes: - permit fee payment - unrelated contractor credential renewal ``` ### Representation A purpose- and audience-specific translation of the domain model. Representations include interfaces, navigation, workflows, schemas, APIs, prompts, agent instructions, reports, and review artifacts. A representation may simplify or rename concepts, but it should preserve the important meaning, rules, and authority boundaries of its source context. ```text Canonical concept: Correction Notice Homeowner representation: Issues to resolve Inspector representation: Correction notice Agent instruction: Do not mark resolved without evidence accepted by the authority ``` ## How The Groupings Relate ```text Domain contains overlapping domain areas. Meaning contexts declare where language, rules, and authority remain consistent. Domain concepts participate in areas and contexts and connect through domain mechanics. Domain slices select the relevant context for a bounded purpose. Representations translate that context for a particular audience or system. ``` A concept should not be forced into only one branch: ```yaml concept: Inspection kind: durable object domain_areas: - inspections - municipal review meaning_context: municipal inspection source_of_truth: municipal inspection record ux_visibility: directly visible included_in_slices: - schedule inspection - prepare for inspection - resolve correction notice ``` Do not treat domain areas and meaning contexts as interchangeable or assume they map one-to-one. A domain area asks which work, capability, or expertise is involved. A meaning context asks where definitions, rules, and authority remain consistent. ## Domain Mechanics The grouping primitives organize the model. Domain mechanics explain what happens inside and across those groups. | Mechanic | Working definition | | --- | --- | | Relationship | A named, directional connection between concepts that carries domain meaning | | State | A condition of a concept that changes what can happen next | | Action | Something an actor intends or attempts to do | | Event | Something meaningful that happened | | Rule | A constraint governing what must, may, or cannot happen | | Source of truth | The authority used to verify a particular type of fact | | Authority boundary | Who or what may suggest, decide, approve, or execute an action | Keep actions, events, and state changes distinct: ```text Action: Inspector approves inspection Event: Inspection approved State change: Inspection moves from Scheduled to Passed Rule: Only the assigned inspector may approve the inspection Source of truth: Municipal inspection record ``` ## Draft Mapping Prompt Use this prompt after initial discovery or while improving an existing Domain Context Brief. ```text Help me create an experimental domain structure map for: [Describe the product, service, workflow, or domain] Use these grouping primitives: - Domain: the broad world being modeled and its outer boundary - Domain areas: coherent areas of responsibility, capability, work, or expertise - Meaning contexts: boundaries where terms, rules, states, relationships, and sources of truth remain internally consistent - Domain concepts: meaningful things people, systems, or agents reason about - Domain slices: purpose-specific selections of context for a feature, workflow, decision, skill, agent, or review - Representations: audience- or system-specific translations of the model Do not force the domain into one rigid hierarchy. A concept may participate in multiple areas or slices. For each important concept, identify when useful: - concept kind - definition and nearby concepts it should not be confused with - domain areas it participates in - meaning context where its definition is authoritative - important relationships, states, actions, events, and rules - source of truth and authority boundaries - whether users need to see it directly Flag: - overloaded terms that change meaning across contexts - concepts that are being incorrectly collapsed together - uncertain boundaries or classifications - assumptions that require domain-expert or source verification - translations required between contexts End with: 1. a concise domain structure map 2. one recommended domain slice for the immediate task 3. questions that must be answered before treating the model as authoritative Do not invent domain truth. Clearly separate evidence, inference, and open questions. ``` ## Testing Questions Use the draft in real work and evaluate: - Do domain areas reveal meaningful capability or ownership boundaries? - Do meaning contexts prevent overloaded terms and rules from being collapsed? - Do concept kinds improve clarity without becoming technical taxonomy work? - Do domain slices give AI tools enough relevant context while excluding distractions? - Do representations preserve important meaning while fitting their audiences? - Can product, design, engineering, and domain experts correct the map easily? - Does the grammar improve downstream specs, UX, schemas, agent instructions, and evaluations? ## Current Boundary This draft is not: - a universal ontology - a complete replacement for OOUX, DDD, UML, knowledge graphs, or software architecture methods - a requirement to classify every concept - a claim that an AI-generated model is authoritative Use only the distinctions that improve shared understanding, product decisions, translation, or agent behavior. Promote them into the core framework only after repeated testing shows that they earn their weight.