GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

§5.2 says `verified` is a list, but its example writes a single mapping

Open Beginner friendly
#415 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.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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.