Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ Space names (e.g. `personal`, `politics`) are resolved via a config file - `$SCT

A Claude Code plugin lives at `plugin/`. It includes skills, commands and hooks used when working with collections of Obsidian markdown content (aka a space) in a vault.

The plugin version in `plugin/.claude-plugin/plugin.json` is managed by git hooks (`lefthook.yml`, `scripts/sync-plugin-version.ts`); never edit it by hand:
- **pre-commit:** bumps the patch version for any commit touching `plugin/`, so the plugin version runs ahead of `package.json` between releases by design. It also syncs major.minor up when `package.json` moves ahead (i.e. a release).
- **pre-push:** fails if a commit since the last tag changed `plugin/` without bumping the version.

## Definition of done

There are several places that need reviewing and updating with any new feature or change added:
Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ See `config.example.json` for the full structure. The config maps space names to

Schemas define the structure and rules for the entities in a space, allowing customisation and extension to different models.

Several schemas (`strict_ost`, `knowledge_wiki` and `general`) are included. The general (strategy) schema combines a basic vision/mission/goals hierarchy with a hierarchy loosely based on Opportunity Solution Trees. It is intentionally flexible to support rapid initial adoption. The strict OST schema has a narrower scope, and reflects Teresa Torres' specific recommendations for Opportunity Solution Trees more closely. The knowledge wiki schema defines a flatter set of types used for knowledge bases.
Several schemas (`strict_ost`, `knowledge_wiki`, `general` and `okf`) are included. The general (strategy) schema combines a basic vision/mission/goals hierarchy with a hierarchy loosely based on Opportunity Solution Trees. It is intentionally flexible to support rapid initial adoption. The strict OST schema has a narrower scope, and reflects Teresa Torres' specific recommendations for Opportunity Solution Trees more closely. The knowledge wiki schema defines a flatter set of types used for knowledge bases. The `okf` schema validates [Open Knowledge Format](https://github.com/GoogleCloudPlatform/open-knowledge-format) bundles: any concept `type`, with provenance, trust, lifecycle and Attested Computation fields checked when present.

structured-context schemas use a metaschema based on JSON Schema 2020-12 that adds a top-level `$metadata` block:

Expand Down Expand Up @@ -217,7 +217,7 @@ A space can have several hierarchies by importing schemas that each declare one.
- The main hierarchy drives `space_on_a_page` parsing, hierarchy embedding, `template-sync`, and the default `show`/`diagram`/`render` output. Use `--hierarchy <name>` to render another one.

**Customizing Schemas:**
- **Partial schemas**: Files starting with an underscore (like `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`) are loaded and used to resolve references (using `$ref`).
- **Partial schemas**: Files starting with an underscore (like `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`, `_okf.json`) are loaded and used to resolve references (using `$ref`).
- **Partials as entity libraries**: Partials can define reusable entity types in `$defs` that composing schemas reference via `$ref`. Bundled partials like `_strategy_general` and `_knowledge_wiki` provide common entity sets for strategy and wiki content.
- **Partials can carry metadata**: Unlike plain JSON Schema, partials may include `$metadata` (hierarchy, aliases, relationships, rules). A schema gets that metadata only by listing the partial in `$metadata.imports`.
- **No-metadata partials**: If a partial has no `$metadata`, prefer `$schema: "https://json-schema.org/draft/2020-12/schema"` so it validates standalone as plain JSON Schema.
Expand Down Expand Up @@ -298,6 +298,8 @@ The WHERE predicate is a [JSONata](https://docs.jsonata.org/overview) expression
- `_selfRef` — whether the edge is a same-type (self-referential) link
- **`descendants[]`** — same structure, for descendant nodes

Dates and datetimes are the strings written in frontmatter, so compare them with `$toMillis()` rather than as strings (offsets and precision vary), e.g. `WHERE $toMillis(updated) > $toMillis('2026-03-31T00:00:00Z')`. See [Rules: dates and times](docs/rules.md#dates-and-times).

**SELECT spec** expands the result set by walking the graph from matched nodes. The spec is a comma-separated list of directives:

| Directive | Meaning |
Expand Down
13 changes: 13 additions & 0 deletions docs/rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,3 +145,16 @@ $count(current.sources) >= 1
$count(nodes[resolvedType='outcome' and status='active']) <= 1
current.status != 'active' or $exists(parent) = false or parent.status = 'active'
```

### Dates and times

Dates and datetimes reach rules as ISO 8601 strings. Convert with `$toMillis()` to compare them, including date against datetime, and use `$millis()` for the current time:

```jsonata
$not($exists(current.due)) or $toMillis(current.due) > $millis()
$toMillis(current.stale_after) > $toMillis(current.generated.at)
```

A datetime without an offset (`2026-07-01T00:00:00`) is read in the machine's local time zone, so require an offset with `format: "date-time"` when results must not depend on where validation runs. `$toMillis()` also needs seconds: it cannot parse a minute-precision datetime such as `2026-07-01T09:15`, which `format: "date-or-date-time"` accepts. A value `$toMillis()` cannot parse makes the rule fail.

The same applies to [filter expressions](../README.md#filter-expressions): compare dates with `$toMillis()`, not as strings.
15 changes: 9 additions & 6 deletions docs/schemas.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,9 @@ This schema reuses shared structural defs from partials via `$ref` and imports i

| Format | Validates | Example |
|--------|-----------|---------|
| `date` | ISO 8601 date (`YYYY-MM-DD`) | `"2026-03-31"` |
| `date` | ISO 8601 calendar date (`YYYY-MM-DD`) | `"2026-03-31"` |
| `date-time` | ISO 8601 datetime with seconds and a UTC offset (`Z` or `±HH:MM`) | `"2026-03-31T09:15:00+10:00"` |
| `date-or-date-time` | A date, or a datetime where seconds and offset are optional (as Obsidian's datetime property writes) | `"2026-03-31"`, `"2026-03-31T09:15"`, `"2026-03-31T09:15:00Z"` |
| `path` | Non-empty filesystem path — absolute, relative, or a plain name | `"notes"`, `"./subdir/file.md"`, `"/abs/path"` |
| `wikilink` | Obsidian wikilink syntax (`[[...]]`) | `"[[Parent Node]]"` |

Expand All @@ -75,15 +77,16 @@ Using `format` directly is more concise when the full definition isn't needed:
{ "type": "string", "format": "wikilink" }
```

### Date coercion
### Dates and datetimes

YAML parsers (gray-matter, js-yaml) coerce unquoted ISO dates to JavaScript `Date` objects:
The markdown plugin reads frontmatter and embedded YAML blocks without YAML's timestamp type, so unquoted dates and datetimes stay as the strings written, at any depth (including inside lists):

```yaml
published_date: 2026-03-31 # parsed as a Date object by gray-matter
published_date: 2026-03-31 # "2026-03-31"
updated: 2026-06-20T22:53:05+10:00 # "2026-06-20T22:53:05+10:00", offset kept
```

The markdown plugin automatically coerces `Date` objects to `YYYY-MM-DD` strings before validation, so unquoted dates in frontmatter and embedded YAML blocks work correctly with `format: "date"` fields.
Validate them with `format: "date"` or `format: "date-time"` when a field needs one precision, or `format: "date-or-date-time"` to accept either, and compare them in rules with JSONata's `$toMillis()` (see [Rules](rules.md#dates-and-times)).

## Metadata dialect

Expand Down Expand Up @@ -373,7 +376,7 @@ Every schema `$id` uses the `sctx://` scheme. The shape of the `$id` says where
- `$id` values follow the [namespace rules](#schema-id-namespaces) and must not collide across bundled, plugin and local schemas.
- `$ref` resolution is transitive across files.
- Partials with no `$metadata` should prefer `$schema: "https://json-schema.org/draft/2020-12/schema"` so they validate standalone as plain JSON Schema fragments.
- **Bundled partials as entity libraries**: `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`, and `_ost_strict.json` provide reusable entity definitions and metadata. Composing schemas can reference their entity types via `$ref` rather than redefining them.
- **Bundled partials as entity libraries**: `_sctx_base.json`, `_strategy_general.json`, `_knowledge_wiki.json`, `_okf.json`, and `_ost_strict.json` provide reusable entity definitions and metadata. Composing schemas can reference their entity types via `$ref` rather than redefining them.
- **Partials can carry metadata**: Partials may include `$metadata` (hierarchy, aliases, relationships, rules). A schema gets it only by listing the partial in `$metadata.imports`; `$ref` alone brings none.

## Plugin-contributed schemas
Expand Down
2 changes: 1 addition & 1 deletion plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "structured-context",
"version": "0.12.0",
"version": "0.12.4",
"description": "Structured content authoring for Obsidian — automatic validation hooks, slash commands, and agent skills to keep markdown files compliant with your schema.",
"homepage": "https://github.com/mindsocket/structured-context",
"repository": "https://github.com/mindsocket/structured-context",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -126,10 +126,12 @@ Use `sctx schemas show _sctx_base.json` to inspect built-in defs.
| `summary` | Short summary string | Any schema that needs a summary property |
| `status` | OST lifecycle status enum | OST-domain schemas only |

Custom string formats: `date` (`YYYY-MM-DD`), `date-time` (ISO 8601 with seconds and offset), `date-or-date-time` (date, or datetime with optional seconds/offset; prefer it unless one precision is required), `path`, `wikilink`. Frontmatter dates and datetimes arrive as the strings written.

Convention:
- define reusable concepts in `$defs`
- reference via `$ref` from `oneOf` entries
- **always check existing schemas** (`strategy_general.json`, `strict_ost.json`, `knowledge_wiki.json`) before authoring — use them as consistency references for property names, patterns, and structure
- **always check existing schemas** (`strategy_general.json`, `strict_ost.json`, `knowledge_wiki.json`, `okf.json`) before authoring — use them as consistency references for property names, patterns, and structure

## `oneOf` authoring pattern

Expand Down
4 changes: 2 additions & 2 deletions schemas/_knowledge_wiki.json
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@
},
"published_date": {
"type": "string",
"format": "date",
"format": "date-or-date-time",
"description": "Original publication date"
},
"source_type": {
Expand Down Expand Up @@ -213,7 +213,7 @@
"type": { "const": "note" },
"date": {
"type": "string",
"format": "date",
"format": "date-or-date-time",
"description": "Date this entry was created or relates to"
}
},
Expand Down
176 changes: 176 additions & 0 deletions schemas/_okf.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
{
"$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/latest/_structured_context_schema_meta.json",
"$id": "sctx://core/_okf",
// Open Knowledge Format v0.2 frontmatter families: core, provenance, trust, lifecycle, attested computation.
// OKF §4.1: consumers MUST NOT reject unknown fields, so every object here allows additional properties.
// Concept types are not registered centrally (§4.1), so there is deliberately no oneOf over `type` consts:
// type checking would reject every type not listed. `Attested Computation` is handled with if/then instead.
// index.md and log.md are reserved bundle files without a `type`; they are reported as excluded during parsing.
"$metadata": {
"rules": [
{
"id": "okf-description",
"category": "best-practice",
"severity": "warning",
"description": "Concepts should have a one-line description (used by index generators and search snippets)",
"check": "$exists(current.description) and $length(current.description) > 0"
},
{
"id": "okf-stale-after-generated",
"category": "coherence",
"severity": "error",
"description": "stale_after must be later than generated.at",
"check": "$not($exists(current.stale_after)) or $not($exists(current.generated.at)) or $toMillis(current.stale_after) > $toMillis(current.generated.at)"
},
{
"id": "okf-usage-count-window",
"category": "coherence",
"severity": "warning",
"description": "A source's usage_count is only meaningful within a usage_window (on the source or shared at the top level)",
"check": "$not($exists(current.sources)) or $count(current.sources[$exists(usage_count) and $not($exists(usage_window)) and $not($exists($$.current.usage_window))]) = 0"
},
{
// Body content is plain text (headings are not kept), so a `# Computation` section can't be told apart
// from other body text: any body counts.
"id": "okf-computation-present",
"category": "validation",
"severity": "error",
"type": "Attested Computation",
"description": "An Attested Computation needs its computation: a `computation` path or a body `# Computation` section",
"check": "$exists(current.computation) or $exists(current.content)"
}
]
},
"$defs": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 datetime with an explicit UTC offset, e.g. 2026-06-30T14:00:00Z (§5)"
},
"actor": {
"type": "string",
"minLength": 1,
"description": "<producer>/<version> for agents, human:<id> for people, process:<id> for automated processes (§7)"
},
"usageWindow": {
"type": "object",
"properties": {
"from": { "$ref": "#/$defs/timestamp" },
"to": { "$ref": "#/$defs/timestamp" }
},
"required": ["from", "to"]
},
"source": {
"type": "object",
"properties": {
"resource": {
"type": "string",
"minLength": 1,
"description": "Followable artifact (URL or path) or a scope descriptor"
},
"id": { "type": "string", "description": "Stable key for footnote attribution" },
"title": { "type": "string" },
"author": { "$ref": "#/$defs/actor" },
"usage_count": { "type": "integer", "minimum": 0 },
"last_modified": { "$ref": "#/$defs/timestamp" },
"usage_window": { "$ref": "#/$defs/usageWindow" }
},
"required": ["resource"]
},
"generated": {
"type": "object",
"properties": {
"by": { "$ref": "#/$defs/actor" },
"at": { "$ref": "#/$defs/timestamp" }
},
"required": ["by"]
},
"verification": {
"type": "object",
"properties": {
"by": { "$ref": "#/$defs/actor" },
"at": { "$ref": "#/$defs/timestamp" }
},
"required": ["by", "at"]
},
"okfProps": {
"type": "object",
"properties": {
"type": {
"type": "string",
"minLength": 1,
"description": "Kind of concept; unregistered and open-ended (§4.1)"
},
"title": { "type": "string" },
"description": { "type": "string" },
"resource": { "type": "string", "minLength": 1, "description": "URI or path of the underlying asset" },
"tags": { "type": "array", "items": { "type": "string" } },
"sources": { "type": "array", "items": { "$ref": "#/$defs/source" } },
"usage_window": { "$ref": "#/$defs/usageWindow" },
"generated": { "$ref": "#/$defs/generated" },
"verified": {
"description": "One verification event, or a list of them (§5.2: a bare mapping is a one-element list)",
"anyOf": [
{ "$ref": "#/$defs/verification" },
{ "type": "array", "items": { "$ref": "#/$defs/verification" } }
]
},
"status": { "type": "string", "enum": ["draft", "stable", "deprecated"], "default": "stable" },
"stale_after": { "$ref": "#/$defs/timestamp" }
},
"required": ["type"]
},
"concept": {
"type": "object",
"allOf": [
{ "$ref": "#/$defs/okfProps" },
{
"if": { "properties": { "type": { "const": "Attested Computation" } }, "required": ["type"] },
"then": { "$ref": "#/$defs/attestedComputation" }
}
],
"additionalProperties": true
},
"attestedComputation": {
"type": "object",
"properties": {
"runtime": {
"type": "string",
"minLength": 1,
"description": "How to run the computation; defines what `parameters` mean (§10.2)"
},
"parameters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1 },
"type": { "type": "string", "minLength": 1 },
"required": { "type": "boolean" }
},
"required": ["name", "type"]
}
},
"computation": {
"type": "string",
"minLength": 1,
"description": "Path to a file holding the computation, instead of the body fence"
},
"executor": {
"type": "object",
"properties": {
"resource": { "type": "string", "minLength": 1 },
"receipt": { "type": "array", "items": { "type": "string" }, "description": "Fields a run must return" }
},
"required": ["resource"]
},
"attester": {
"type": "object",
"properties": { "resource": { "type": "string", "minLength": 1 } },
"required": ["resource"]
}
},
"required": ["runtime"]
}
}
}
8 changes: 8 additions & 0 deletions schemas/okf.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/latest/_structured_context_schema_meta.json",
"$id": "sctx://core/okf",
"title": "Open Knowledge Format",
"description": "Validates the frontmatter of Open Knowledge Format (OKF v0.2) concept documents in a bundle. Any `type` is accepted and unknown fields are tolerated; `Attested Computation` concepts additionally carry the computation contract.\n\nSpecification: https://github.com/GoogleCloudPlatform/open-knowledge-format",
"$metadata": { "imports": ["sctx://core/_okf"] },
"allOf": [{ "$ref": "sctx://core/_okf" }, { "$ref": "sctx://core/_okf#/$defs/concept" }]
}
7 changes: 3 additions & 4 deletions src/plugins/markdown/parse-embedded.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
import { load as yamlLoad } from 'js-yaml';
import type { Code, Heading, List, ListItem, Paragraph, Root, Table, TableRow } from 'mdast';
import { toString as mdastToString } from 'mdast-util-to-string';
import remarkGfm from 'remark-gfm';
Expand All @@ -13,7 +12,7 @@ import type {
SharedEmbeddingFields,
} from '../../api';
import { extractLinksFromAstNode } from './extract-content-links';
import { applyFieldMap, coerceDates } from './util';
import { applyFieldMap, parseYaml } from './util';

/** Type values that identify a space_on_a_page container (not themselves space nodes). */
export const ON_A_PAGE_TYPES = ['ost_on_a_page', 'space_on_a_page'];
Expand Down Expand Up @@ -884,9 +883,9 @@ export function extractEmbeddedNodes(body: string, options: ExtractEmbeddedOptio
activeNode.contentLinks.push(...extractLinksFromAstNode(child));
} else if (child.type === 'code' && (child as Code).lang?.trim() === 'yaml') {
const code = child as Code;
const parsed = yamlLoad(code.value);
const parsed = parseYaml(code.value);
if (parsed && !Array.isArray(parsed) && typeof parsed === 'object') {
Object.assign(activeNode.schemaData, coerceDates(applyFieldMap(parsed as Record<string, unknown>, fieldMap)));
Object.assign(activeNode.schemaData, applyFieldMap(parsed as Record<string, unknown>, fieldMap));
} else if (Array.isArray(parsed)) {
throw new Error(`YAML block must be an object at "${activeNode.label}".`);
} else {
Expand Down
Loading
Loading