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

journeyMaps[]

Journey document URL

Unique URLs; list order is portfolio navigation order.

Journey

actors, goals, activities, userTasks

Embedded object keyed by opaque stable local ID

Never recycle keys; rename labels freely; *Order[] has exactly the same unique IDs as the corresponding map.

Goal / Activity / User Task

actorIds[], goalIds[], activityId

Local IDs in same journey map

Referenced objects must exist; retire instead of deleting referenced identities.

Story

map and userTask: {map,localId}

Journey and embedded task

Both map URLs match; the local task exists. Actor/goal refs use the same pair shape.

Story

committedRelease

Optional single release URL

Scalar: zero or one committed release. proposedReleases[] contains non-committed alternatives; no overlap and no duplicate values.

Release

storyRefs[]

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

storyRefs[]

User Story URLs

Work may support multiple stories; zero permitted for portfolio-level work. technical-task extends delivery-work and pins workType.

Registry

sourceCollection

Journey Maps collection

Computed view returns {map,localId}; never copy embedded canonical object data into registry records.

Migration entry

sources[], proposedRecord, canonicalRecord, embeddedTarget

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

Connections0
Linked document · Outgoing linkLinked documentStory Maps OntologyStory Maps Ontology
Citations 0Children & links 1

Loading child documents…

Connections show where other documents or comments link to this document.

Related documents

Loading connections…