How to Validate an OKF Bundle

What Is OKF Conformance?

OKF conformance means a bundle follows the formal OKF specification — a structured set of rules covering directory layout, file naming, YAML frontmatter schema, cross-linking conventions, and version compatibility. A conformant bundle is guaranteed to work with any OKF-compatible tool.

What Conformance Checks

• Directory structure: Must have index.md, SPEC.md, and a concepts/ directory
• Frontmatter schema: index.md must include name, description, okf_version
• Cross-links: Concept files must link to each other using OKF-style references
• Version compatibility: Bundle's okf_version must match a supported spec version
• No orphaned files: All markdown files should be referenced from the bundle index

Step 1: Check Conformance on BundleDex

The quickest way to check a bundle's conformance status is on BundleDex. Every bundle page shows a conformance badge:

curl https://bundledex.net/api/bundles.json | \
  jq '.bundles[] | select(.okf_conformant == true) | .name'

Step 2: Use the OKF Conformance Tool

For thorough validation, use the OKF Conformance tool — the official validator for OKF bundles. It runs a comprehensive test suite against any bundle directory.

Installation

# Clone the conformance tool
git clone https://github.com/YOUR_ORG/okf-conformance
cd okf-conformance

# Run against a bundle
python validate.py /path/to/your-bundle/

What It Validates

• Structural checks: Required files exist, no unknown top-level files
• Frontmatter validation: All required YAML fields present and correctly typed
• Cross-link integrity: Every concept link points to an existing file
• OKF version check: Bundle declares a valid okf_version
• Content quality: Descriptions are non-empty, titles are meaningful

Other validation tools include okf-lint for frontmatter linting, OKF Go Parser for programmatic Go-based validation, and okf-schema for Python/JSON Schema validation.

Step 3: Manual Validation Checklist

If you prefer to check manually, here's a quick checklist:

Step 4: Automate Validation in CI

The best practice is to validate your OKF bundle on every commit. Here's a GitHub Actions workflow:

# .github/workflows/okf-validate.yml
name: Validate OKF Bundle
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check directory structure
        run: |
          test -f index.md || (echo "Missing index.md" && exit 1)
          test -f SPEC.md || (echo "Missing SPEC.md" && exit 1)
          test -d concepts || (echo "Missing concepts/" && exit 1)
      - name: Validate frontmatter
        uses: okf-lint/action@v1
        with:
          path: .

You can also use Surface for documentation quality checks in CI, which catches issues like documentation drift and missing cross-references.

Real Examples from the Index

Here are examples of conformant and non-conformant bundles from the BundleDex index:

✅ Conformant Bundles

These bundles pass all conformance checks. Their structure is verified to match the OKF specification, and they're guaranteed to work with any OKF-compatible agent or tool.

⚠️ Non-Conformant Bundles (for comparison)

Non-conformant status doesn't mean a bundle is bad — many excellent OKF bundles are in this category. It simply means they haven't been validated. As the ecosystem matures, we expect more bundles to achieve conformance.

Frequently Asked Questions