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
22 changes: 19 additions & 3 deletions docs/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Each `.md` file with a `type` frontmatter field is a **typed page** — it repre

- **Heading with `[type:: x]`** or **anchor-implied type** (e.g. `## My Goal ^goal1`) → becomes a child node.
- **Relationship headings** (e.g. `### Assumptions`) → when matched to a relationship definition in the schema, signals that following content (list items or table rows) should be typed as that relationship's child type, without requiring explicit inline annotations.
- **Untyped headings** → update the depth stack for parent resolution but do not become nodes.
- **Untyped headings** → update the depth stack for parent resolution but do not become nodes. They stay in the content of the node whose section contains them; see [Node content](#node-content).
- **Typed bullet items** (`- [type:: solution] Title`) → become child nodes at any nesting depth.
- **Table rows** under a relationship heading → become child nodes of the relationship type.
- **YAML blocks** and **unbracketed `key:: value` paragraph fields** → merged into the current node's `schemaData`.
Expand Down Expand Up @@ -87,7 +87,7 @@ Key properties:

#### Preamble

**Preamble** is content in a `space on a page` document that appears before the first heading. It is parsed but discarded — not associated with any node.
**Preamble** is content in a `space on a page` document that appears before the first heading. It is parsed but discarded — not associated with any node, and not part of any node's `content`.

---

Expand All @@ -99,6 +99,8 @@ Node types are defined by the schema in use and may vary across schemas. Example

Each node retains its physical `source` location (`file`, and `line` / `column` where available) so that validation diagnostics, edge errors, and downstream tooling pinpoint the exact location in the vault.

A node's `content` is the markdown source of its body; see [Node content](#node-content).

> `space_on_a_page` and `dashboard` are not `space node` types — they are `tooling types`.

### Embedded node
Expand All @@ -107,6 +109,20 @@ An **embedded node** is a `space node` defined *within* a containing document ra

A `typed page` may contain embedded nodes in its body. Those nodes become full members of the parsed node set, with `parent references` wired to their containing page or enclosing heading.

### Node content

A node's `content` is the markdown of its body, copied unchanged from the file: blank lines, list looseness, line endings and code fences all stay as written. The content of a list item node is dedented by the item's content indent, so it reads as markdown on its own. Leading blank lines and trailing whitespace are trimmed.

A node owns the source from its heading or list item up to the next heading that ends its section, with these parts removed:

- Its own heading line or list marker text.
- The sections of nested embedded nodes.
- Field syntax that supplies data: frontmatter and other YAML blocks, and lines that hold only `key:: value` or `[key:: value]` fields. A field written inside a sentence stays in the prose, and its value is still read as a field.

An untyped heading belongs to the content of the node whose section contains it. An untyped heading at the same level as an embedded node's heading, or at a higher level (fewer `#`), ends that node's section, so the heading and what follows it go to the enclosing node, or to the page. An untyped heading at a deeper level stays inside the section. Inline fields below an untyped heading are assigned the same way.

In a `space_on_a_page` file, content before the first heading (the preamble) is not assigned to any node.

### Type alias

A **type alias** is an alternative name accepted in the `type` field for a given `space node` type. Aliases allow teams to use their own vocabulary while still receiving schema validation. For example, a schema might accept `outcome` as an alias for `goal`.
Expand All @@ -117,7 +133,7 @@ A `space node`'s resolved type (`resolvedType`) is its canonical type after alia

## Typed page

A **typed page** is a markdown file whose frontmatter declares a `space node` type (e.g. `type: goal`). The file itself represents one node, and its body may additionally contain `embedded nodes`. Body content appearing before any embedded headings (or the entire body when no embedded headings are present) is preserved as the page node's `content`.
A **typed page** is a markdown file whose frontmatter declares a `space node` type (e.g. `type: goal`). The file itself represents one node, and its body may additionally contain `embedded nodes`. The page node's `content` is the body markdown outside any embedded node (the entire body when there are none).

Typed pages are distinct from `space on a page` files: a typed page *is* a `space node`; a `space_on_a_page` file is merely a container.

Expand Down
4 changes: 3 additions & 1 deletion docs/schemas.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ Main types:

### `okf.json`

[Open Knowledge Format](https://github.com/GoogleCloudPlatform/open-knowledge-format) (OKF v0.2) bundles, validated as plain markdown spaces. Any concept `type` is accepted and unknown fields are tolerated; provenance (`sources`), trust (`generated`, `verified`), lifecycle (`status`, `stale_after`) and the Attested Computation contract are checked when present. Reserved `index.md` and `log.md` are reported as excluded during parsing.
[Open Knowledge Format](https://github.com/GoogleCloudPlatform/open-knowledge-format) (OKF v0.2) bundles, validated as plain markdown spaces. Any concept `type` is accepted and unknown fields are tolerated; provenance (`sources`), trust (`generated`, `verified`), lifecycle (`status`, `stale_after`) and the Attested Computation contract are checked when present. An Attested Computation needs its computation: a `computation` field, or a `# Computation` section in the body (found by matching that line in the body text, so a `# Computation` line inside a code fence also counts). Reserved `index.md` and `log.md` are reported as excluded during parsing.

## Custom format annotations

Expand Down Expand Up @@ -284,6 +284,8 @@ With this config, an application page may include `### capability` with wikilink
- [[Zephyr]] ← populates application.tools (fieldOn: parent)
```

A node's body becomes its `content`; see [Node content](concepts.md#node-content).

## Composition and merge semantics

`$ref` and `$defs` are for **validation only**: a `$ref` to another schema (or to one of its `$defs`) reuses its JSON Schema definitions but brings none of its `$metadata`.
Expand Down
6 changes: 2 additions & 4 deletions schemas/_okf.json
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,11 @@
"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",
"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)"
"description": "An Attested Computation needs its computation: a `computation` path or a body `# Computation` section. Known limitation: the section is found by matching a `# Computation` line in the body text, so such a line inside a code fence also counts",
"check": "$exists(current.computation) or $contains(current.content, /^# Computation[ \\t]*$/m)"
}
]
},
Expand Down
2 changes: 1 addition & 1 deletion schemas/_sctx_base.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
},
"content": {
"type": "string",
"description": "Body content"
"description": "Markdown source of the node's body, excluding its own heading or list marker and any nested embedded nodes"
},
"summary": {
"type": "string",
Expand Down
Loading
Loading