Repository navigation
Multiple hierarchies via schema composition - #122
Merged
Merged
Conversation
Every $ref'd schema now contributes its declared hierarchy as a separate
named hierarchy instead of the last provider winning.
- $metadata.hierarchy gains an optional `name` (default: declaring file stem)
and may be `{ "$ref": "<schema $id>#/$metadata/hierarchy" }` on the root to
select the main hierarchy
- main hierarchy: root-declared, else the single contributed one, else the
root's $ref selection; several contributed with none selected is an error,
as is declaring and selecting at once
- a type in two hierarchies, or two hierarchies with the same name, is an error
- layering, parent-type, skip-level and orphan checks run per hierarchy
- hierarchy edges in resolvedParents carry the hierarchy name
- show/diagram/render take --hierarchy <name> (default: main hierarchy)
- SchemaMetadata gains `hierarchies`; SpaceGraph.levels becomes
SpaceGraph.hierarchy; buildSpaceGraph takes a Hierarchy
Closes #121
Claude-Session: https://claude.ai/code/session_01EJgagmpxDYVYr7fp9C6cZi
- $metadata.imports (schema $ids) is the only way metadata travels; imports
are whole-schema and transitive, merged depth-first in order, own metadata last
- external $ref / $defs no longer make the referenced schema a metadata provider
- one merge rule for rules (id), relationships (parent+type+field), aliases
(name) and hierarchies (name): duplicate is an error unless the later entry
sets override: true (aliases: { "type": ..., "override": true })
- remove $ref rule imports inside $metadata.rules
- bundled strategy_general, strict_ost and knowledge_wiki gain imports
Claude-Session: https://claude.ai/code/session_01EJgagmpxDYVYr7fp9C6cZi
mindsocket
force-pushed
the
feat/121-composed-hierarchies
branch
from
September 27, 2026 02:51
00f90c6 to
0c7deee
Compare
Code reviewNo issues found. Checked for bugs and CLAUDE.md compliance. |
mindsocket
added a commit
that referenced
this pull request
Oct 6, 2026
- Resolve plugin schemas synchronously via convention (<pluginRoot>/schemas/) without executing plugin code - Support plugin-prefixed schema resolution (e.g. sctx-wardley-mapping/wardley_map.json) - Index plugin partials (_*.json) under the sctx://<pluginName>/ URI namespace - Enforce schema URI namespace constraints and collision detection across core, plugin, and local schemas - Integrate plugin schemas into schema composition ($ref and $metadata.imports) Addresses #88 Relates to #7, #17, #91, #97, #122
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #121. This includes the explicit-imports design from the latest comment on #121. Follow-up work (plain
allOf/$refsemantics, search paths, types arriving with imports) is tracked in #123.Summary
A space can now have several hierarchies by composing schemas. Each schema still declares at most one hierarchy, but every imported schema contributes the hierarchy it declares as a separate named hierarchy. Previously the last provider won.
$metadata.hierarchy.nameis optional and defaults to the declaring schema's file stem, so the bundled hierarchies are_ost_strictand_strategy_general. A duplicate name is an error unless the later hierarchy sets"override": true.strict_ost,strategy_general)."hierarchy": { "$ref": "<schema $id>#/$metadata/hierarchy" }. Otherwise loading the schema fails.$refat the same time is an error.allowSkipLevelsis per hierarchy. A hierarchy edge whose parent belongs to a different hierarchy is reported as an invalid parent. Relationships still connect types across hierarchies.resolvedParentscarryhierarchy: <name>. Filterancestors[]/descendants[]entries expose it as_hierarchy. ASpaceGraphis built for one selected hierarchy.show,diagramandrendertake--hierarchy <name>, defaulting to the main hierarchy.space_on_a_pageparsing, hierarchy embedding andtemplate-syncuse the main hierarchy.$ref/$defsare now validation-only: an external$refno longer makes the referenced schema a metadata provider.$metadata.imports: ["<schema $id>", ...]. An import brings the whole schema's metadata and is transitive. Merge order is imports in order (depth-first), then the schema's own metadata last. Each schema is merged at most once, and an unresolvable import is an error.override: true. Identities:idparent+type+field{ "type": "<target>", "override": true }as the alias value.name. Overriding by name is how a schema replaces an imported hierarchy's levels.$refrule imports inside$metadata.rulesare removed. To share rules, import a rules-only schema.strategy_general,strict_ostandknowledge_wikigainimportslines.docs/schema-dialect-update-proposal.mdand the "layer 2 silently wins" comment insrc/schema/schema.ts.Docs (README, concepts, schemas, api), plugin skill references, bundled schema comments and the generated metaschema are updated to match.
Breaking changes
Schema format / composition
$refno longer brings metadata. A schema that relied on$ref/allOfto pick up a partial's hierarchy, aliases, relationships or rules gets none until it lists the partial in$metadata.imports. All bundled root schemas are updated.$metadata.imports: string[]. An$idthat doesn't resolve is an error.$refentries inside$metadata.rules(rule and rule-set imports) are removed, and the metaschema rejects them.{ "type": ..., "override": true }. Alias values may now be that object form.parent+type+fieldis an error unless the later one setsoverride: true(new field on relationships).idis now an error even when the two payloads are identical. Previously identical duplicates were tolerated. The error message changed fromConflicting rule "<id>" ...toDuplicate rule "<id>" found in "<a>" and "<b>". Set "override": true ....namecan be replaced with"override": trueon the hierarchy (new field). This is the supported way to change an imported hierarchy's levels.namewith"override": true.hierarchy: { "$ref" }. Otherwise it fails to load.$metadata.hierarchyis nowoneOfa hierarchy declaration (with a new optionalname) or a{ "$ref" }selection. The generated metaschema has changed accordingly.{ levels, $ref }together is rejected.Hierarchy "<name>" level "<type>" is not a valid type ....CLI output / behaviour
schemas showprints onehierarchy "<name>"[ (main)]: a → bline per hierarchy instead ofhierarchy: a → b.schemas show --mermaid-erdemits edges for every hierarchy.show/diagram/rendershow only the main hierarchy as a tree. Types from other hierarchies are listed under "Other (not in hierarchy)" unless--hierarchyis given. Miro sync uses the main hierarchy.validatereports orphans across all hierarchies. A hierarchy edge pointing to a node of another hierarchy's type is now a hierarchy violation; previously it was skipped.JSON output / API / types
ResolvedParentRefgainshierarchy?: string, set on every hierarchy edge. This is visible indumpoutput and in filter predicates as_hierarchy.SchemaMetadata.hierarchyis nowHierarchy({ name, levels, allowSkipLevels? }), andnameis required. There is a newSchemaMetadata.hierarchies: Hierarchy[](all hierarchies, main included).Hierarchyis exported fromstructured-context/api.SpaceGraph.levelsis removed and replaced bySpaceGraph.hierarchy: Hierarchy | undefined.buildSpaceGraph(nodes, levels)becomesbuildSpaceGraph(nodes, hierarchy). Render plugins that readgraph.levelsmust usegraph.hierarchy?.levels.SpaceGraphhierarchy views (hierarchyRoots,orphans,nonHierarchy,hierarchyChildren,hierarchyTitles) are scoped to the graph's hierarchy.assembleSpaceGraph/loadSpaceGraphacceptoptions.hierarchy. An unknown name throwsUnknown hierarchy: "<name>". Available: ....executeRenderacceptsoptions.hierarchy.RuleReftype is renamedMetadataRef(now used only by hierarchy selection), and theRuleEntrytype is removed.Tests
New tests cover:
hierarchy: { "$ref" }selection, which also compiles$refwithout an import brings no metadataoverride$ref'dallowSkipLevels, and a cross-hierarchy parent--hierarchyrendering throughexecuteRender, including an unknown namebun run typecheck,bun run lintandbun run test(451 pass) all pass.plugin/.claude-plugin/plugin.jsonwas reformatted so thatbiome checkpasses. It already failed onmain, and the pre-commit version sync bumped the plugin to 0.11.1.https://claude.ai/code/session_01EJgagmpxDYVYr7fp9C6cZi