From 6c368979d214e7f3305d7df54117c62a62468ec8 Mon Sep 17 00:00:00 2001 From: Jerome Etienne Date: Wed, 1 Jul 2026 05:46:49 +0200 Subject: [PATCH] =?UTF-8?q?okf:=20recommend=20relative=20cross-links=20ove?= =?UTF-8?q?r=20absolute=20(=C2=A75.1/=C2=A75.2)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SPEC §5.1 recommended /-prefixed absolute (bundle-relative) links, but these only resolve in an OKF-aware consumer. A raw renderer resolves a leading / against its own root (host origin in a browser, repo root on GitHub), which is not the bundle root once the bundle is nested as a subdirectory within a larger repository (allowed by §3), so the links mislink or 404. The reference implementation had already voted against the spec: the agent prompt forbids leading /, and every cross-link in the shipped bundles is relative. This aligns the spec with that reality. - Swap §5.1/§5.2 so relative links are §5.1 and marked recommended. - Reframe absolute links as §5.2, documenting that they require an OKF-aware resolver and the browser/GitHub/nested-subdir failure mode. - Update the §4.3/§4.4 examples to use the recommended relative form. --- okf/SPEC.md | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/okf/SPEC.md b/okf/SPEC.md index 55d0a46..5840914 100644 --- a/okf/SPEC.md +++ b/okf/SPEC.md @@ -193,13 +193,13 @@ timestamp: 2026-05-28T14:30:00Z | Column | Type | Description | |---------------|-----------|------------------------------------------| | `order_id` | STRING | Globally unique order identifier. | -| `customer_id` | STRING | Foreign key into [customers](/tables/customers.md). | +| `customer_id` | STRING | Foreign key into [customers](./customers.md). | | `total_usd` | NUMERIC | Order total in US dollars. | | `placed_at` | TIMESTAMP | When the customer submitted the order. | # Joins -Joined with [customers](/tables/customers.md) on `customer_id`. +Joined with [customers](./customers.md) on `customer_id`. # Citations @@ -220,7 +220,7 @@ timestamp: 2026-04-12T09:00:00Z # Trigger A freshness alert fires when `orders` lags more than 30 minutes behind -its expected SLA. See the [orders table](/tables/orders.md). +its expected SLA. See the [orders table](../tables/orders.md). # Steps @@ -235,25 +235,37 @@ its expected SLA. See the [orders table](/tables/orders.md). Concepts MAY link to other concepts using standard markdown links. Two forms are supported: -### 5.1 Absolute (bundle-relative) links +### 5.1 Relative links (recommended) -Begin with `/`, interpreted relative to the bundle root. +Standard markdown relative paths. ```markdown -See the [customers table](/tables/customers.md) for the join key. +See the [neighboring concept](./other.md). ``` -This is the **recommended** form because it is stable when documents are -moved within their subdirectory. +This is the **recommended** form because it resolves correctly in any +standard markdown renderer — `cat`, a browser, GitHub, an editor preview +— without OKF-aware tooling, which keeps the bundle portable and +browsable raw. Its only drawback is that a link breaks if either +document is moved relative to the other. -### 5.2 Relative links +### 5.2 Absolute (bundle-relative) links -Standard markdown relative paths. +Begin with `/`, interpreted relative to the bundle root. ```markdown -See the [neighboring concept](./other.md). +See the [customers table](/tables/customers.md) for the join key. ``` +This form is stable when a document is moved within the bundle, but it +**requires an OKF-aware resolver**: a non-OKF renderer resolves a +leading `/` against its own root (the host origin in a browser, the +repository root on GitHub), which is not the bundle root once the bundle +is nested as a subdirectory within a larger repository (§3). In that +case the link mislinks or 404s. Use this form only when the bundle is +served at a root that an OKF-aware consumer maps to the bundle root; +prefer §5.1 for bundles meant to be browsed raw. + ### 5.3 Link semantics A link from concept A to concept B asserts a *relationship*. The