GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Spec inconsistency: §7's actor convention excludes its own §5.1 example (`author: team:ga4-docs`)

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

§7 defines the actor convention as exactly three forms — `/`, `human:`, `process:` — but §5.1's worked `sources` example uses `author: team:ga4-docs`, which is none of them (no `/`, and the prefix is neither `human` nor `process`). A consumer that validates `author` / `by` strictly against §7's list ends up flagging the spec's own example.

```yaml
# §7 — the three actor forms
by: reference_agent/gemini-2.5-pro
by: human:ahormati
by: process:finance-nightly

# §5.1 — the worked example
author: team:ga4-docs # matches none of the three
```

## The question

Is §7's list meant to be exhaustive, or is the real convention `:` | `/`, with `human:` and `process:` as two sanctioned schemes among others such as `team:`?

- If **exhaustive**, §5.1's `team:ga4-docs` is non-conforming and the example should change.
- If **general**, §7 could name `:` as the form, with `human:` / `process:` as reserved schemes.

Either resolution works; the ambiguity is the problem. The `human:` prefix is clearly load-bearing — §5.3 keys trust tiers off it — so its special status isn't in question, only whether other schemes like `team:` are legal.

## Context

This surfaced while building a [structural validator for OKF bundles](https://github.com/ojhermann-org/okf-tools): we had to decide whether `author: team:ga4-docs` is a defect, and a strict §7 check would have flagged a value taken verbatim from the spec. We currently accept `/` or `:` to sidestep it, but would rather match whatever §7 intends.

Contributor guide

Open the contributing guide

Research direction

Compare the actor forms stated in §7 with the worked `sources` example in §5.1, and review the trust-tier use of `human:` in §5.3. Check the structural validator context linked in the issue, then document one consistent rule and update the conflicting specification example or wording; done means the examples and validation rule agree.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.