GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Date-valued frontmatter is unquoted in the spec's examples, so its parsed type is left to the YAML parser
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
The spec never says whether date-valued frontmatter is a string or a YAML date. Every example leaves the scalar bare:
```yaml
last_modified: 2026-05-30 # §5.1
usage_window: { from: 2026-06-01, to: 2026-06-30 } # §5.1
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z } # §5.2
stale_after: 2026-09-23 # §5.5
```
A YAML 1.1 parser resolves all four to `date` or `datetime` objects rather than strings. §12 quotes its scalar, `okf_version: "0.2"`, and Appendix A's v0.1 example quotes its timestamp, `timestamp: '2026-05-28T22:53:05+00:00'`, so the document is not consistent with itself either.
## The four shipped bundles disagree
Parsing `okf/bundles/` with `yaml.safe_load` returns two different Python types for the same field. `generated.at` comes back as a `datetime` in `acme_retail` and as a `str` in `ga4`, `stackoverflow` and `crypto_bitcoin`. The split is visible in the raw text: the agent-generated bundles quote, for example `bundles/stackoverflow/tables/posts_questions.md`
```yaml
at: '2026-07-10T22:49:19+00:00'
```
while the hand-authored bundle does not, for example `bundles/acme_retail/computations/revenue-ytd.md`
```yaml
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-30T14:00:00Z }
```
All four shipped in the same commit.
## This already cost the reference tooling
PR #227 records the consequence in its own commit message:
> The visualizer crashed on bundles with unquoted YAML date scalars (generated.at, stale_after, source last_modified), which PyYAML parses into date/datetime objects that json.dumps rejects. Coerce them at the serialization boundary with default=str so hand-authored bundles render
`reference_agent/bundle/document.py` carries the same coercion in `is_stale`, branching on `isinstance(raw, date)` before falling back to `date.fromisoformat(str(raw)[:10])`. Both are workarounds for an ambiguity that lives in the format, so every independent consumer has to rediscover and re-implement them.
There is a second-order effect worth noting. `acme_retail/viz.html` serializes `generated.at` as `2026-06-30 14:00:00+00:00`, which is Python's `str(datetime)`, not the `2026-06-30T14:00:00Z` the source file contains. The round trip does not preserve the authored text.
## Suggestion
State the intended type in §5.1, §5.2 and §5.5, and make the examples match. Either direction is implementable:
- Strings, with the examples quoted. Producers keep the exact authored text and consumers parse when they need to.
- YAML dates, stated as such, with consumers expected to handle `date` and `datetime` objects.
Quoting the examples is the smaller change. It also matches what the agent-generated bundles already do, so three of the four would need no edit.
Contributor guide
Research direction
Locate the specification sections §5.1, §5.2, §5.5 and Appendix A, then compare their frontmatter examples with the files under okf/bundles/. Read reference_agent/bundle/document.py and the serialization behavior described in PR #227 to understand the existing workaround. Done means the intended scalar type is stated consistently and the affected examples agree with it.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100