GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
§6.2 allows a relative path in frontmatter but does not say what it is relative to
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
§6.2 lists the fields that name a path and the three forms each accepts:
> - an absolute URL (for example `https://...`),
> - a bundle-relative path beginning with `/`, or
> - a relative path (for example `../computations/revenue.md`).
The second form is anchored. The third is not, in §6.2 or anywhere else. §6.1 anchors the leading-slash form for markdown body links, and says nothing about the bare form in frontmatter.
## The shipped bundle answers one way in frontmatter and the other way in bodies
`bundles/acme_retail` is the only bundle exercising these fields. It has twelve non-URL path-valued frontmatter fields, none beginning with `/`, so all twelve are the unanchored third form. Resolved file-relative, twelve of twelve point at files that do not exist. Resolved from the bundle root, twelve of twelve resolve.
`computations/revenue-ytd.md`:
```yaml
executor:
resource: skills/run-on-bq.md
attester:
resource: attesters/sql_equality.py
```
There is no `computations/skills/` and no `computations/attesters/`. Both directories sit at the bundle root.
The same file's body links resolve the other way:
```markdown
The sanctioned computation is [`computations/revenue-ytd.md`](../computations/revenue-ytd.md).
```
and `policies/revenue-recognition.md` uses a third style, the leading slash, for its body links. So one bundle contains bare-means-bundle-root in frontmatter and dot-relative-means-file-relative in bodies, and §6.2 calls both "a relative path".
## Why it matters
A consumer that resolves `executor.resource` to decide what code to run has to guess. Guessing file-relative yields twelve dead paths in the bundle written by hand to demonstrate the feature. This is also the field that determines which executor runs an Attested Computation, so a wrong guess is not a broken link, it is the wrong code or none.
## Relation to existing issues
This is deliberately narrow. #157, #85, #48, #201, #120, #115, #112 and #200 discuss cross-link resolution and identifier stability for markdown body links, permalinks included. #234 covers a different §5.1 and §7 mismatch. The point here is only that §6.2's third bullet has no anchor, and that the shipped bundle depends on the unstated reading.
## Suggestion
Add the anchor to §6.2. Given what `acme_retail` already does, "relative to the bundle root unless written with a leading `./` or `../`" would ratify existing practice, but any stated rule beats the current silence. I don't know whether the bare form was intended as bundle-root or simply not thought about.
Contributor guide
Research direction
Start with §6.2 and compare its path rules with the examples in bundles/acme_retail, especially computations/revenue-ytd.md and policies/revenue-recognition.md. Confirm the intended anchor for bare and dot-relative frontmatter paths, then update §6.2 so the rule is explicit and consistent with the shipped bundle.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 70/100