Mandatory Frontmatter Keys Required for OKFDocument Validation: A Complete Guide

OKFDocument enforces exactly four mandatory frontmatter keys—type, title, description, and timestamp—and raises an OKFDocumentError during validate() if any are missing or falsy.

The OKFDocument class in the GoogleCloudPlatform/knowledge-catalog repository defines the document standard for the Open Knowledge Framework (OKF). Before a document can be processed or rendered, it must pass strict validation ensuring all mandatory frontmatter keys required for OKFDocument validation are present. These requirements are hard-coded in the REQUIRED_FRONTMATTER_KEYS constant and checked by the validate() method.

Where the Mandatory Keys Are Defined

The authoritative list of required entries lives in okf/src/reference_agent/bundle/document.py inside the REQUIRED_FRONTMATTER_KEYS constant. According to the GoogleCloudPlatform/knowledge-catalog source code, this tuple contains the four fields that every OKFDocument frontmatter dictionary must include.

The Four Required Frontmatter Keys

• type — The document’s category or kind, such as "guide" or "reference".
• title — A human-readable title that identifies the document.
• description — A short summary explaining the document’s purpose and content.
• timestamp — An ISO-8601 formatted date-time string indicating when the document was created or last updated.

During the OKFDocument.validate() routine, the implementation iterates over REQUIRED_FRONTMATTER_KEYS (lines 56–61 in okf/src/reference_agent/bundle/document.py) and raises an OKFDocumentError if any key is absent or evaluates to a falsy value.

How OKFDocument Validation Works

The validation logic is straightforward and strict. When validate() is invoked, it inspects the document’s frontmatter mapping for each key in REQUIRED_FRONTMATTER_KEYS. If one or more keys are missing—or present but empty—the method collects the missing names and raises an OKFDocumentError with a clear message listing the absent fields.

This behavior is exercised in okf/tests/test_document.py, which contains unit tests verifying correct parsing, serialization, and validation enforcement. Additional integration context appears in okf/tests/test_index.py, where OKFDocument instances are loaded as part of the bundle index workflow.

Practical OKFDocument Code Examples

The following examples demonstrate a valid document, an invalid document missing the description key, and the resulting error output.

from reference_agent.bundle.document import OKFDocument, OKFDocumentError

# Example of a valid document

doc = OKFDocument(
    frontmatter={
        "type": "guide",
        "title": "How to Use OKFDocument",
        "description": "A quick start guide for the OKFDocument class.",
        "timestamp": "2024-07-16T12:00:00Z",
    },
    body="Content of the guide goes here."
)

# Validate – succeeds because all required keys are present

doc.validate()

Attempting to validate a document with a missing description key produces an explicit failure:

# Example of an invalid document (missing `description`)

invalid_doc = OKFDocument(
    frontmatter={
        "type": "guide",
        "title": "Incomplete Document",
        "timestamp": "2024-07-16T12:00:00Z",
    },
    body="Missing description."
)

try:
    invalid_doc.validate()
except OKFDocumentError as exc:
    print(exc)   # → Missing required frontmatter keys: description

Summary

• type, title, description, and timestamp are the only mandatory frontmatter keys required for OKFDocument validation.
• These keys are defined in the REQUIRED_FRONTMATTER_KEYS constant in okf/src/reference_agent/bundle/document.py.
• The OKFDocument.validate() method iterates over this tuple and raises an OKFDocumentError if any required key is missing or falsy.
• Unit tests in okf/tests/test_document.py and bundle integration tests in okf/tests/test_index.py enforce this behavior across the codebase.

Frequently Asked Questions

What happens if a required frontmatter key is missing in OKFDocument?

If a required key is missing or falsy, OKFDocument.validate() raises an OKFDocumentError that explicitly names the missing fields. This ensures no incomplete document is processed further in the Knowledge Catalog pipeline.

Can I add custom keys to OKFDocument frontmatter beyond the four required ones?

Yes. The validation logic in okf/src/reference_agent/bundle/document.py specifically checks for the presence of the four mandatory keys defined in REQUIRED_FRONTMATTER_KEYS. Additional custom metadata entries do not trigger validation errors, provided the required set is satisfied.

Where are the OKFDocument validation rules tested?

The enforcement of mandatory frontmatter keys is covered in okf/tests/test_document.py, which validates parsing, serialization, and error handling. Usage within a full index loading workflow is demonstrated in okf/tests/test_index.py.

Does the OKFDocument timestamp key require a specific format?

The timestamp key must be present in the frontmatter dictionary as an ISO-8601 formatted date-time string indicating when the document was created or last updated. The OKFDocument.validate() method checks that this key exists and is truthy alongside the other REQUIRED_FRONTMATTER_KEYS.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}