OPF registry guide

What is a registry?

A registry is a JSON file describing a collection of OPF design choices, including layouts, color schemes, font schemes, themes, and blocks, that third parties can publish for agents and tools to reuse.

Schema

The v1 registry contract keeps the top-level file small: identify the registry, then list named items with their OPF document or fragment.

{
  "$schema": "https://pptx.dev/schema/registry/v1",
  "name": "string",
  "version": "1.0.0",
  "homepage": "https://...",
  "items": [
    {
      "id": "string",
      "kind": "layout|color-scheme|font-scheme|theme|block",
      "name": "string",
      "description": "string",
      "opf": { },
      "requires": ["other-id"]
    }
  ]
}

Required fields are $schema, name, version, and a non-empty items array. Each item requires id, kind, name, and opf. Optional fields are homepage, description, and requires.

Example

Start from the public fixtures:

{
  "$schema": "https://pptx.dev/schema/registry/v1",
  "name": "example-minimal",
  "version": "1.0.0",
  "items": [
    {
      "id": "hero-split",
      "kind": "layout",
      "name": "Hero Split",
      "opf": {
        "$schema": "https://pptx.dev/schema/opf/v1",
        "version": "1.0",
        "meta": { "title": "Hero Split Example" },
        "design": {},
        "slides": [{ "id": "s1", "layout": "hero-split", "elements": [] }]
      }
    }
  ]
}

Validating your registry

Send the public registry URL to /api/v1/validate:

curl -X POST https://pptx.dev/api/v1/validate \
  -H "Authorization: Bearer $PPTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"registryUrl":"https://yourdomain.com/registry.json"}'

The response includes top-level valid, errors, and warnings, plus one result per registry item. A top-level valid: false means the registry file could not be used as a valid registry; a per-item valid: false means that item failed its own OPF validation.

Publishing

Host the JSON anywhere HTTPS is available, such as GitHub Pages, Vercel, S3, or Cloudflare R2. The file must be publicly fetchable, no larger than 1 MiB, and should be served with an application/json Content-Type.