GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
§5.1 / §6.2: a `sources[].resource` scope descriptor has no marker distinguishing it from a path
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
§5.1 says a `sources[].resource` is *either* a followable path (an absolute URL, a bundle-relative path, or a `references/…` path) *or* "a population or scope descriptor it cannot [follow]," e.g. `all queries in BigQuery project X`. §6.2 restates it: "A `sources[].resource` may instead be a scope descriptor (§5.1), in which case it is not a path."
But neither section gives a consumer any syntactic way to tell the two apart. A tool that resolves `sources` — building a provenance graph, or flagging a `resource` that points nowhere — has to decide "path or scope descriptor?" with nothing to key on but the string's shape.
```yaml
sources:
- resource: /references/ga4-schema.md # a path — resolve it
- resource: all queries in BigQuery project X # a scope — leave it
- resource: references/attesters/revenue.py # a path
```
## The problem
Absent a marker, a consumer must guess. The obvious heuristic — "does it contain a space?" — is fragile both ways: a scope descriptor can be a single token, and a real path can contain a space (cf. #200 on percent-encoded spaces). Guessing wrong means either flagging a scope descriptor as a broken path, or silently skipping a genuinely dangling one.
## The question
Should a scope descriptor carry an explicit marker, so tooling isn't inferring intent from punctuation? For example a distinct key (`scope:` alongside `resource:`), or a structured form (`resource: { scope: "all queries in project X" }`). Either lets a consumer resolve paths and leave scopes alone deterministically.
## Context
Same family as #234 and #235: the spec draws a distinction a consumer is expected to act on without giving it the means to. Surfaced building a structural validator — resolving path-valued fields and reporting the ones that dangle (§6.2), where a scope descriptor must not be mistaken for a broken path.
Contributor guide
Research direction
Read the distinctions in §5.1 and §6.2 alongside the examples of path and scope descriptor values. Review the structural validator context and related issues #234 and #235; done means the specification defines an unambiguous representation that lets consumers resolve paths without treating scope descriptors as dangling paths.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100