GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

§6.2: what base does a relative path-valued field resolve against?

Open
#408 0 comments 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 three accepted shapes for a path-valued field but never states what
the third one is relative *to*. Two readings are each defensible, they disagree
on a concrete file, and the spec's own examples appear to require different
answers in different places. An explicit sentence in §6.2 would settle it.

Pinned at `62432a095456147ee71e70ac6e4dc0d2dea3ac30`, `okf/SPEC.md`.

### The gap

§6.2 says a path-valued field (`resource`, `sources[].resource`, `computation`,
`executor.resource`, `attester.resource`) accepts:

> - an absolute URL (for example `https://...`),
> - a bundle-relative path beginning with `/`, or
> - a relative path (for example `../computations/revenue.md`).

The third item has no stated base. §6.1 is explicit for *markdown body links*
(a leading `/` is bundle-root, otherwise "a standard markdown relative path"),
but §6.2 enumerates its own forms rather than deferring to §6.1, so it is not
obvious the same rule is intended.

### Why it matters — the two readings disagree on the spec's own example

**Reading A, document-relative** (by analogy with §6.1): a relative path
resolves against the directory of the concept declaring it.

**Reading B, prefix-driven**: `./` and `../` resolve against the concept's
directory; a *bare* path resolves from the bundle root.

Appendix A gives this layout:

```
bundles/finance/
computations/revenue.md type: Attested Computation
references/skills/run-on-bq.md, run-dbt.md
references/attesters/sql-equality.py, dbt-binding.py
```

and that same `computations/revenue.md` declares:

```yaml
executor:
resource: references/skills/run-on-bq.md
attester:
resource: references/attesters/sql-equality.py
```

Under Reading A those resolve to `computations/references/skills/run-on-bq.md`,
which the layout above does not contain. Under Reading B they resolve to the
`references/` directory the layout actually shows. §6.3
(`references/attesters/revenue.py`) and §10.2 use the same bare shape.

But §6.2's own illustration of the relative form, `../computations/revenue.md`,
is document-relative by construction — so a single "always bundle-root" rule
does not work either.

### Questions

1. Is a **bare** relative path in a path-valued field resolved from the bundle
root, or from the declaring concept's directory?
2. If from the bundle root, is the distinction the explicit `./` / `../`
prefix, as Reading B assumes?
3. Is a consumer instead expected to **try both bases**? If so, §6.2 would need
to state the precedence, since the two can both resolve to existing and
different files.
4. Related, and separable: §6.2 says a `sources[].resource` "may instead be a
scope descriptor (§5.1), in which case it is not a path". §5.1's example is
prose (`all queries in BigQuery project X`), but Appendix A also uses
`resource: dashboards/exec-revenue`, which is path-shaped. Is a consumer
expected to distinguish descriptors from paths syntactically, and if so how?

### Context

Asked from [OKF4net](https://github.com/jchable/okf4net), an independent
LGPL-3.0 .NET implementation of OKF v0.2. We initially implemented Reading A,
which made every bare path in `okf/bundles/acme_retail` (`attesters/…`,
`skills/…`, `policies/…`, `tables/…`) report as unresolvable — twelve
diagnostics against a bundle that is laid out exactly as Appendix A is. We have
switched to Reading B and documented it as an interpretation rather than a
conformance requirement, since §11 places path resolution outside the
conformance floor. We would rather follow whatever you intend than entrench a
guess.

Happy to send a PR against `okf/SPEC.md` with the clarifying sentence once you
say which reading is correct.

Contributor guide

Open the contributing guide

Research direction

Read okf/SPEC.md at commit 62432a095456147ee71e70ac6e4dc0d2dea3ac30, focusing on §6.1–§6.3, §10.2, §11, and Appendix A. Resolve the intended base for bare and prefixed relative paths and how scope descriptors are identified, then update §6.2 with the maintainer-approved clarification.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.