Minimal modeling guidance
Model only what the user's current workflow needs. Each type, field and constraint must support a concrete user action, query or invariant; omit speculative abstractions. Reuse native Seed structure and schema bindings rather than duplicating facts they already express. Navigation/index documents can remain ordinary documents: grouping children alone does not justify a collection schema or collectionType. Add an explicit discriminator only when a real consumer needs a distinction the existing schema binding cannot express; name that consumer and the behavior it enables.
This guidance governs future modeling and simplification review; it does not migrate existing records or change published schema contracts. Audit consumers before removing existing fields or bindings. The relationships below describe the current model, not a requirement to reproduce every layer.
A Journey Map describes a coherent user journey. A Product Portfolio Map connects journeys. Actors pursue Goals through User Activities (broad stages) and User Tasks (actions within stages). These four objects are embedded with stable opaque IDs; ordering is separate. A reference pairs owning map URL with local ID; IDs are not Seed block fragments.
User Stories describe observable product behavior supporting user tasks. Release Slices select a coherent end-to-end set of stories to test an outcome. A story has at most one committed release allocation; alternatives are proposals. Delivery Work Items realize or validate stories; technical tasks are one subtype alongside design, research, engineering, architecture, data, quality, security, documentation and operations.
Registries compute views of embedded objects, not canonical copies. Migration evidence retains exact source document, version, block context, extraction rationale and review decision. Referential integrity and allocation uniqueness require application validation beyond structural schemas.
Status: the HM schema family under Schemas is published. The earlier experimental journey-map shape survives only as a pinned schema CID on the embedded model test. Native rendered editing has not been verified.
Relationships and ownership
Owner | Relation | Target | Invariant |
|---|---|---|---|
Portfolio |
| Journey document URL | Unique URLs; list order is portfolio navigation order. |
Journey |
| Embedded object keyed by opaque stable local ID | Never recycle keys; rename labels freely; |
Goal / Activity / User Task |
| Local IDs in same journey map | Referenced objects must exist; retire instead of deleting referenced identities. |
Story |
| Journey and embedded task | Both map URLs match; the local task exists. Actor/goal refs use the same pair shape. |
Story |
| Optional single release URL | Scalar: zero or one committed release. |
Release |
| Selected story URLs | Release membership is a selection/proposal; allocation authority is the story's committed scalar, cross-checked both ways on commitment. |
Delivery work |
| User Story URLs | Work may support multiple stories; zero permitted for portfolio-level work. |
Registry |
| Journey Maps collection | Computed view returns |
Migration entry |
| Exact historical version/block and proposed/approved target | Only publish canonical targets after review; originals remain unchanged. |
Identity, lifecycle and provenance
Local IDs match ^[A-Za-z0-9][A-Za-z0-9._~-]*$; keys are identity, independent of labels, order or document block fragments. For promotion, retain the embedded key and set promotedTo to a standalone document URL; the registry must resolve legacy {map,localId} through this alias without silently rewriting inbound references. No standalone embedded-object subtype is modeled currently; create one only after reviewing consumers.
Status sets are type-specific and closed in current schemas. archived retains the historical record; embedded objects use active/retired. State transitions, permitted reviewers and writer access are governance/application rules, not schema language features. References use hm-url strings; existence, nominal target type, same-map pairing, uniqueness, referential integrity, ordered-ID coverage, positive provenance review, and release reciprocity require transactional application checks. An HM typed-document write is advisory; the app must block on failed checks and re-read after save.
Provenance entries contain sourceDocument, exact sourceVersion, optional exact sourceBlockId (without #), optional localContext, nonempty extractionRationale, and reviewStatus. At least one of sourceBlockId or localContext is mandatory for a migrated target; migrated records also require migrationEntry and review-approved provenance, while genuinely new records may omit these fields. A source block link is formed with the read-back block ID and pinned source version, never with an invented heading slug. Migration entries additionally capture candidateType, confidence, duplicateCandidates, classificationRationale, reviewDecision, reviewer/rationale, and candidate versus published target separately. A candidate or manifest entry is not approval.
Schema evolution
Type documents under Schemas evolve in place: a change to a type is a new schemaDefinition on the same document, so the document's version history is the schema's history and its hm:// URL stays the identity that records bind to. Do not publish sibling documents with version suffixes. Records that follow the URL see the current definition; pin ?v=<version> or the schema CID where an audit needs an exact contract. Breaking changes (renames, new required fields, key-format or subtype changes) still need a reviewed, provenance-preserving conversion of existing records.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime