Skip to content

Multiple hierarchies via schema composition #121

Closed

Description

@mindsocket

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 hierarchy syntax 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_ost via _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_page parsing, the default show/diagram/render and 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

Activity

  1. mindsocket commented on Sep 26, 2026

    @mindsocket
    OwnerAuthor

    Design addition, to be included in #122 before merge: explicit imports. This separates validation reuse from model composition.

    • $ref / $defs become validation-only. A $ref no longer brings in the referenced schema's metadata. Today, any external $ref, even one pointing at a single $defs entry, pulls in the whole referenced schema's metadata (collectExternalRefIdsInOrder in src/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 $ref a definition without importing it.
    • One merge rule for every metadata key. Imported metadata merges in import order, and the schema's own metadata comes last. A duplicate is an error unless marked 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.
    • Hierarchies: imports contribute hierarchies. The main-hierarchy rule is unchanged.
    • Remove rule $ref imports in $metadata.rules. A rules-only schema imported whole does the same job.
    • Bundled schemas: strategy_general, strict_ost and knowledge_wiki currently rely on implicit metadata, so each gains an imports line.
  2. added a commit that references this issue on Sep 27, 2026
    a531625
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions