Two questions about validate: broken links as ERROR, and footnotes inside code spans
Tested with v0.4.0 (linux_amd64, checksum verified) against a private OKF v0.2 bundle of ~130 concepts, then reduced to the minimal repro below. Both questions may well be deliberate — I'd rather ask than assume.
Thanks for the tool, incidentally: it found real problems in a bundle that passed fourteen of our own house checks, and the spec-section citation in every message made each one straightforward to act on.
Repro
mkdir -p repro/notes
cat > repro/index.md <<'EOF'
---
okf_version: "0.2"
---
# Repro
* [A note](notes/a.md) - demonstrates two validate behaviours.
EOF
cat > repro/notes/a.md <<'EOF'
---
type: Note
title: A note
description: Minimal reproduction.
tags: [repro]
---
This links to [something not yet written](/notes/b.md).
The intake protocol says to attribute claims with `[^id]` footnotes.
EOF
okf validate repro --format json
Result:
valid=False errors=1 warnings=1
[WARN] okf/sources/footnote-undefined
body: footnote [^id] is referenced but never defined - renders as a dangling marker (OKF §5.1)
[ERROR] okf/links/broken
broken link: [something not yet written] -> /notes/b.md (concept notes/b not found)
1. Should a broken link make a bundle non-conformant?
The spec seems to say the opposite, in two places.
§6.1:
Consumers MUST tolerate broken links: a link whose target does not exist in the bundle is not malformed; it may simply represent not-yet-written knowledge.
§11, which lists conformance as exactly three conditions — none about links — and then:
consumers MUST NOT reject a bundle because of […] broken cross-links
validate currently reports a broken link as ERROR, sets valid: false, and exits 1. In our bundle, a single broken link was the only thing standing between valid: false and valid: true, errors: 0 — the other 13 findings are warnings and don't affect the verdict.
The case that raised it for us is one the spec's own wording seems to anticipate: a concept links to a binary in the bundle — a frozen PNG that exists on disk but isn't a .md concept. So the link resolves for a human and for git, but not under the concept model.
Two things make me think this may be a misplacement rather than a stance:
- The tool already has a separate
lint command for advisory findings, which suggests validate is meant to be the conformance gate and lint the quality one.
- §11's three conditions are a tight, checkable set, and links aren't in it.
But there's a reasonable counter-argument, which is why this is a question: §6.1 and §11 constrain consumers, and a validator arguably isn't a consumer — a linter can legitimately be stricter than the thing it protects. If that's the intent, it would help to say so, because valid: false reads as a conformance verdict rather than as advice, and downstream tooling gating on it will reject bundles the spec says are fine.
Would you consider either moving links/broken to WARN, or moving it to lint?
2. Footnote references inside code spans
In the repro, `[^id]` is inside backticks — prose about footnotes, in documentation that explains the convention. validate reads it as a footnote reference and reports it undefined.
The finding's own rationale is the argument against it: "renders as a dangling marker". Inside a code span it doesn't — it renders as literal text.
We hit this twice, in both files that document our own intake protocol, which is probably the common case: the documents most likely to write [^id] as an example are the ones explaining what sources[].id is for.
Would skipping footnote scanning inside code spans (and fenced blocks) be reasonable?
Not a request, just context
Neither of these blocks us — we're planning to consume --format json and apply severities on our side, so the exit code isn't load-bearing for us. I'm raising them because the first affects anyone gating CI on validate, and the second affects anyone whose bundle documents OKF itself.
Happy to send a PR for either if you'd like, though I'd rather hear which behaviour you intend first.
Two questions about
validate: broken links as ERROR, and footnotes inside code spansTested with v0.4.0 (
linux_amd64, checksum verified) against a private OKF v0.2 bundle of ~130 concepts, then reduced to the minimal repro below. Both questions may well be deliberate — I'd rather ask than assume.Thanks for the tool, incidentally: it found real problems in a bundle that passed fourteen of our own house checks, and the spec-section citation in every message made each one straightforward to act on.
Repro
Result:
1. Should a broken link make a bundle non-conformant?
The spec seems to say the opposite, in two places.
§6.1:
§11, which lists conformance as exactly three conditions — none about links — and then:
validatecurrently reports a broken link asERROR, setsvalid: false, and exits 1. In our bundle, a single broken link was the only thing standing betweenvalid: falseandvalid: true, errors: 0— the other 13 findings are warnings and don't affect the verdict.The case that raised it for us is one the spec's own wording seems to anticipate: a concept links to a binary in the bundle — a frozen PNG that exists on disk but isn't a
.mdconcept. So the link resolves for a human and forgit, but not under the concept model.Two things make me think this may be a misplacement rather than a stance:
lintcommand for advisory findings, which suggestsvalidateis meant to be the conformance gate andlintthe quality one.But there's a reasonable counter-argument, which is why this is a question: §6.1 and §11 constrain consumers, and a validator arguably isn't a consumer — a linter can legitimately be stricter than the thing it protects. If that's the intent, it would help to say so, because
valid: falsereads as a conformance verdict rather than as advice, and downstream tooling gating on it will reject bundles the spec says are fine.Would you consider either moving
links/brokentoWARN, or moving it tolint?2. Footnote references inside code spans
In the repro,
`[^id]`is inside backticks — prose about footnotes, in documentation that explains the convention.validatereads it as a footnote reference and reports it undefined.The finding's own rationale is the argument against it: "renders as a dangling marker". Inside a code span it doesn't — it renders as literal text.
We hit this twice, in both files that document our own intake protocol, which is probably the common case: the documents most likely to write
[^id]as an example are the ones explaining whatsources[].idis for.Would skipping footnote scanning inside code spans (and fenced blocks) be reasonable?
Not a request, just context
Neither of these blocks us — we're planning to consume
--format jsonand apply severities on our side, so the exit code isn't load-bearing for us. I'm raising them because the first affects anyone gating CI onvalidate, and the second affects anyone whose bundle documents OKF itself.Happy to send a PR for either if you'd like, though I'd rather hear which behaviour you intend first.