GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Date-valued frontmatter is unquoted in the spec's examples, so its parsed type is left to the YAML parser

Open Beginner friendly
#240 1 comment 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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.