GoogleCloudPlatform / GoogleCloudPlatform/open-knowledge-format

`okf_version: "0.2"` now names two documents: #6's explicit-offset requirement is breaking but carries no version bump

Open
#24 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
467
Forks
35
Avg merge
9m
Merged PRs (30d)
1

Description

PR #6 (merged 2026-08-21, `ad30107c`) inserted at `SPEC.md:284`:

> Every timestamp-valued key in OKF is an ISO 8601 datetime with an explicit UTC offset, for example `2026-06-30T14:00:00Z`.

and rewrote three keys that §5 had previously specified as `YYYY-MM-DD`: `stale_after`, `sources[].last_modified`, and `usage_window.{from,to}`. The prose carrying the old form went with it — `stale_after` lost "An absolute date (`YYYY-MM-DD`)" and `last_modified` lost its parenthetical. So `stale_after: 2026-09-23` was normative before that commit and is non-conformant after it.

§12 (`SPEC.md:768-775`) reserves breaking changes for a major bump, minor bumps being backward-compatible additions. `SPEC.md:3` reads **Version 0.2** both before the change and after it.

**Consequence.** Two bundles both declaring `okf_version: "0.2"` can now legitimately disagree about whether `stale_after: 2026-09-23` is conformant, so a conformance claim against "0.2" is not a well-defined statement — a consumer reading that declaration cannot tell which of the two documents the producer built against.

I am not assuming this was an oversight. A pre-1.0 correction to a format still settling is reasonable on its own terms; it is the version string that is now carrying two meanings.

Several ways to resolve it, any of which would do, and the choice is yours:

- A version bump, so the document states which revision it is.
- An errata note in §13, which already sets the precedent of naming v0.1's breaking changes explicitly.
- A commit- or date-qualified spec identifier, so `okf_version` resolves to bytes rather than to a moving reference.
- If compatibility was the intent: a sentence saying consumers SHOULD accept a date-only value for these three keys and read it as midnight UTC. That is one clause, and it makes every bundle written before 21 August conformant again.

**Where we sit**, for disclosure: not blocked, and not raising this because it cost us anything. We pin `ad30107c` in our interoperability fixtures rather than resolving a version string, and we emit none of the three affected keys, so we cannot produce the old form even by accident. I am raising it for implementations that pin by version string instead of by commit, where the two readings differ with nothing to signal it.

Happy to send a PR for the last option if that is the direction you would prefer.

Contributor guide

Open the contributing guide

Research direction

Read SPEC.md:3 and the changes at SPEC.md:284, then compare the versioning rules in §12 with the errata precedent in §13. Confirm with maintainers which resolution to use; done means the version identifier and the rules for the three affected keys no longer allow two interpretations of okf_version 0.2.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.