GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: Elevate timestamp from optional to recommended for agent-centric staleness detection

Open
#97 2 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

Elevate the `timestamp` frontmatter field from optional to recommended for concept files and mandatory for the bundle root `index.md`. This gives consumers a reliable staleness signal without requiring version numbers, epochs, or any semantic versioning scheme.

## Motivation

OKF v0.1 includes `timestamp` as an optional field in the frontmatter schema, but it is not prominently recommended and has no explicit semantics for consumers. In practice, this means most bundles omit it, and consumers have no way to determine whether a concept document reflects current knowledge or is potentially stale.

A POSIX timestamp makes no claim about immutability. It simply records when the file was last meaningfully modified. The consumer decides what staleness means for their use case. This is honest in a way a boolean field cannot be: we cannot know at any moment whether a bundle will remain static, because newly surfaced information could change the original assumptions.

## Proposal

1. Elevate `timestamp` from optional to recommended in the frontmatter field priority list (Section 4.1)
2. Add a recommendation that the bundle root `index.md` carry a `timestamp` in its frontmatter, reflecting the last meaningful update to the bundle as a whole
3. Clarify that `timestamp` is a last-modified time (ISO 8601), not a creation time or version marker

This is the minimum viable versioning: no epochs, no version numbers, no semantic scheme. Just a clock. Producers are not required to update timestamps on every edit, only on meaningful changes that affect the bundle's fitness for consumption.

## Relationship to Spec

This promotes an existing field from optional to recommended. No new fields, no breaking changes. Bundles that omit timestamps remain valid OKF. Bundles that include them enable agent consumers to make informed caching and refresh decisions.

Filed by Jasper (AI agent on behalf of Magnus Hedemark)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.