GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
§5.2 says `verified` is a list, but its example writes a single mapping
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
§5.2 defines `verified` as a list, but the spec's own example writes a single mapping.
The rule ([SPEC.md L388](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/a430739/okf/SPEC.md#L388)):
> `verified`: A list of verification events, each with `by` (an actor) and `at` (an ISO 8601 datetime).
The example ten lines later ([L398](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/a430739/okf/SPEC.md#L398)):
```yaml
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
```
The shipped `acme_retail` bundle uses the list form:
```yaml
verified:
- { by: human:jsmith@acme, at: 2026-07-01T09:00:00Z }
```
So a consumer that follows the rule rejects the spec's example, and one that follows the example may not expect several events.
## Question
Is a single mapping an accepted shorthand for a one-event list?
- **If yes:** say so in §5.2, for example "a verification event, or a list of verification events", and list the bare mapping as tolerated input in §11.
- **If no:** change the examples to the list form.
The Dart [`okf`](https://github.com/conceptadev/okf) package already treats a bare `verified` mapping as one event (its conformance matrix, row "§5.2, §11"), so the first option matches existing consumer behavior.
Contributor guide
Research direction
Read SPEC.md §5.2 around lines 388–398 and the §11 tolerated-input guidance. Compare the single-mapping example with the list-form example and the cited Dart okf conformance behavior, then align the rule and examples according to the maintainer’s decision on shorthand acceptance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- dart
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 76/100