You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Declare source-of-truth and derivation intent for spaces and their representations #146
There is no way to say which representation of some structured content is canonical, and which ones are derived from it. Config registers each space independently, and render/sync commands are run ad hoc.
Example
A Wardley map could exist as:
a directory of markdown files, one per component, with frontmatter for evolution, visibility and needs links;
an OnlineWardleyMaps (OWM) text file;
a visual canvas or board in a tool like Obsidian Canvas or Miro.
If the markdown directory is the source of truth, the OWM file and the canvas should be generated from it and treated as read-only, or at least checked for drift. There may also be several maps over one body of content. Nothing in config or the CLI records that intent today.
Questions
How to express it: a space-level setting (for example derivedFrom / renders with target formats and paths), a relationship between spaces, or a separate project-level "pipeline" concept?
What tooling follows from it:
a sctx render/sync that regenerates all derived outputs;
drift detection when a derived file is edited by hand;
hooks that warn on edits to derived files.
How one space maps to several derived artefacts (many maps or views over one space), and several spaces feed one artefact.
How this relates to bidirectional sync with external systems of record, where the canonical side may differ per field.
Related: #6 (systems of work), #8 (cross-space references), #88 (frameworks as plugins), #138 (serialisable graph)
Note: one schema, several representations already works
A plugin can parse a non-markdown representation against the same schema the markdown reader uses. The Wardley mapping plugin (in an extensions repo) is an example:
Its parser handles a .owm file path.
For a directory path it returns null, so the markdown reader takes over with the same schema.
Round-trip check with a sample map: .owm space → sctx render … markdown.directory → markdown space → sctx render … owm.
Both spaces validate with the same 15 nodes and 0 errors.
The regenerated OWM is semantically equivalent. The differences are formatting, explicit pipeline bounds and normalised element syntax, plus one dropped comment line.
What's missing is the link between the two: today they are two unrelated spaces, and the render step is a manual command.
Possible direction: render targets in space config
A space keeps its path (what is parsed and validated) and gains render targets, so source-of-truth intent sits where the space is defined. For example:
Context note (2026-10-29). Separate from what this issue asks.
The working assumption for core, the Obsidian plugin and map views is that each space has one canonical source, and that today the source is the space's markdown. An editing surface (a map view, an editor) writes back to the markdown, and anything else is derived from it. That is a scoping assumption for those three, not an answer to this issue.
This issue stays open for the wider question: declaring which representation is canonical and which are derived (OWM text, canvases, boards), and what happens when a non-markdown source arrives. Candidate mechanisms, none chosen:
everything goes via markdown, with two-way sync for other representations;
the source system parses straight into nodes, with no markdown;
updates go to the source system and are re-parsed.
Decide when the first non-markdown source arrives.
Activity
mindsocket commentedon Oct 7, 2026
Note: one schema, several representations already works
A plugin can parse a non-markdown representation against the same schema the markdown reader uses. The Wardley mapping plugin (in an extensions repo) is an example:
.owmfile path.null, so the markdown reader takes over with the same schema.Round-trip check with a sample map:
.owmspace →sctx render … markdown.directory→ markdown space →sctx render … owm.What's missing is the link between the two: today they are two unrelated spaces, and the render step is a manual command.
Possible direction: render targets in space config
A space keeps its
path(what is parsed and validated) and gains render targets, so source-of-truth intent sits where the space is defined. For example:That gives:
sctx render <space>(orsync) that regenerates every declared target;Two-way sync, where either side can be edited, would build on this rather than replace it.
mindsocket commentedon Oct 29, 2026
Context note (2026-10-29). Separate from what this issue asks.
The working assumption for core, the Obsidian plugin and map views is that each space has one canonical source, and that today the source is the space's markdown. An editing surface (a map view, an editor) writes back to the markdown, and anything else is derived from it. That is a scoping assumption for those three, not an answer to this issue.
This issue stays open for the wider question: declaring which representation is canonical and which are derived (OWM text, canvases, boards), and what happens when a non-markdown source arrives. Candidate mechanisms, none chosen:
Decide when the first non-markdown source arrives.