GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

§6.2 allows a relative path in frontmatter but does not say what it is relative to

Open Beginner friendly
#245 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.