GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

§5.1 / §6.2: a `sources[].resource` scope descriptor has no marker distinguishing it from a path

Open
#236 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

§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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.