# Mandatory Frontmatter Keys Required for OKFDocument Validation: A Complete Guide

> Learn the four mandatory frontmatter keys required for OKFDocument validation: type, title, description, and timestamp. Ensure compliance and avoid errors in your GoogleCloudPlatform knowledge catalog.

- Repository: [Google Cloud Platform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
- Tags: how-to-guide
- Published: 2026-07-16

---

**`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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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.

```python
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:

```python

# 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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/tests/test_document.py) and bundle integration tests in [`okf/tests/test_index.py`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`.