Skip to content

fix: align REQUIRED_FRONTMATTER_KEYS with OKF spec §4.1#64

Open
tcconnally wants to merge 2 commits into
GoogleCloudPlatform:mainfrom
Perseus-Computing-LLC:fix/okf-required-fields-spec-compliance
Open

fix: align REQUIRED_FRONTMATTER_KEYS with OKF spec §4.1#64
tcconnally wants to merge 2 commits into
GoogleCloudPlatform:mainfrom
Perseus-Computing-LLC:fix/okf-required-fields-spec-compliance

Conversation

@tcconnally

Copy link
Copy Markdown

Problem

REQUIRED_FRONTMATTER_KEYS in document.py was set to ("type", "title", "description", "timestamp"), treating four fields as required. However, OKF v0.1 §4.1 states that only type is REQUIRED. title, description, and timestamp are "Recommended" — not required.

This means the reference implementation was rejecting valid OKF bundles that conform to the spec. For example, a concept document with only type and tags (both spec-valid) would fail validate().

Fix

  • Changed REQUIRED_FRONTMATTER_KEYS to ("type",) — only type is required per spec.
  • Updated test_validate_rejects_missing_required_keystest_validate_rejects_missing_type to test that only missing type triggers validation failure.
  • Added test_validate_accepts_minimal_frontmatter to verify that {"type": "X"} passes validation (spec-minimal bundle).

Verification

All 6 document tests pass:

tests/test_document.py::test_roundtrip_preserves_frontmatter_and_body PASSED
tests/test_document.py::test_parse_no_frontmatter_treats_all_as_body PASSED
tests/test_document.py::test_unterminated_frontmatter_raises PASSED
tests/test_document.py::test_validate_rejects_missing_type PASSED
tests/test_document.py::test_validate_accepts_minimal_frontmatter PASSED
tests/test_document.py::test_validate_accepts_full_frontmatter PASSED

Impact

This is a conformance fix. Without it, any downstream producer that emits spec-minimal bundles (type-only frontmatter) would get false validation failures from the reference validator. This is especially important for programmatic producers that may not have human-readable title/description fields available at generation time.

@google-cla

google-cla Bot commented Jun 15, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

Per OKF v0.1 §4.1, only 'type' is a required frontmatter field.
'title', 'description', and 'timestamp' are 'Recommended', not
required. The reference implementation was incorrectly rejecting
valid OKF bundles that included only the required 'type' field.

This also adds a test for minimal frontmatter (type-only) to
prevent regression.
@tcconnally tcconnally force-pushed the fix/okf-required-fields-spec-compliance branch from 6b3101b to 1fe1f61 Compare June 15, 2026 17:32
@tcconnally

Copy link
Copy Markdown
Author

Friendly ping — CLA signed and checks passing. Happy to iterate on any feedback.

passionworkeer pushed a commit to passionworkeer/knowledge-catalog that referenced this pull request Jun 25, 2026
OKF v0.1 §4.1 explicitly states that only `type` is REQUIRED; `title`,
`description`, and `timestamp` are listed as Recommended. The reference
implementation treated all four as REQUIRED, so any spec-minimal bundle
whose concepts only declared `type` would be incorrectly rejected by
OKFDocument.validate().

This hurts programmatic producers in particular — they often have no
human-readable title/description available at generation time.

This PR is a rebase of upstream GoogleCloudPlatform#64 onto the post-GoogleCloudPlatform#129 `enrichment_agent`
→ `reference_agent` rename: change one constant, update the corresponding
test, and add a minimal-frontmatter acceptance test.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant