Repository navigation
Closed
Description
Summary
Allow a space to have several hierarchies by composing schemas. Each schema still declares at most one hierarchy.
Today, when schemas are composed via $ref, only one hierarchy survives. The last metadata provider wins (src/schema/schema.ts:353-358). As a result, a second domain tree (for example, a skills tree or a platform/tools tree alongside a work hierarchy) either gets flattened into relationships, losing tree rendering, orphan checks and layering, or gets bolted onto the single hierarchy.
Design
- One hierarchy per declared schema. The existing
hierarchysyntax is unchanged. Several hierarchies come only from composition. - Every
$ref'd schema contributes what it declares, including its hierarchy. A hierarchy is kept as a separate named hierarchy, not merged. - Naming: a hierarchy has a declared short name. It defaults to the declaring schema's file stem.
- Main hierarchy:
- If the root declares a hierarchy, that one is the main hierarchy.
- If the root declares none and exactly one hierarchy is contributed, that one is the main hierarchy implicitly. This keeps schemas that get their hierarchy from a partial working, such as
strict_ostvia_ost_strict. - If the root declares none and more than one is contributed, the root must select one with
hierarchy: {"$ref": "..."}. Otherwise it's an error. - A root that both declares a hierarchy and uses
hierarchy: {"$ref"}is an error. space_on_a_pageparsing, the defaultshow/diagram/renderand template embedding use the main hierarchy.
- Each type belongs to at most one hierarchy. A type claimed by two hierarchies is an error.
- Validation: layering, parent-type and skip-level checks run per hierarchy. Relationships connect hierarchies as today.
- Rendering: add a
--hierarchy <name>option to hierarchy-based views. The default is the main hierarchy. - Graph model: hierarchy edges carry the hierarchy name, so consumers can tell hierarchies apart.
- A composed schema remains usable standalone as another space's root.
Also
- Fix the stale note in
docs/schema-dialect-update-proposal.md("error on multiple providers"). - Fix the "layer 2 silently wins" comment in
src/schema/schema.ts, which contradicts the collision error it throws.
Out of scope
- Cross-space references (Cross-space references: linking entities across schemas and spaces #8).
- Gating semantics across hierarchies (Layered rule evaluation: cascade gating and coverage annotation #115).
- Namespacing rule ids across composed schemas.
Metadata
Metadata
Assignees
Labels
No labels
Activity
mindsocket commentedon Sep 26, 2026
Design addition, to be included in #122 before merge: explicit imports. This separates validation reuse from model composition.
$ref/$defsbecome validation-only. A$refno longer brings in the referenced schema's metadata. Today, any external$ref, even one pointing at a single$defsentry, pulls in the whole referenced schema's metadata (collectExternalRefIdsInOrderinsrc/schema/schema.ts).$metadata.imports: ["sctx://..."]becomes the only way hierarchy, relationships, aliases and rules travel. An import brings the whole schema, all or nothing, and imports are transitive: an imported schema's own imports come too. A schema can still$refa definition without importing it.override: true. That covers alias keys, relationships (same parent/type/field), rule ids and hierarchy names. It replaces today's per-key behaviour: aliases shallow-merge, relationships concatenate.$refimports in$metadata.rules. A rules-only schema imported whole does the same job.strategy_general,strict_ostandknowledge_wikicurrently rely on implicit metadata, so each gains animportsline.Multiple hierarchies via schema composition