@10up/relay-schemas

Shared JSON Schemas for content stored in Relay. This package is the single source of truth for the frontmatter shapes and path-allowlist policy validated by the Relay Cloud MCP server and the Relay client utilities.

Zero runtime dependencies. Pure ESM.

Install

npm install @10up/relay-schemas

What's in the box

| Export | Description | | ------------------------------------- | -------------------------------------------------------------------------------- | | notebookSchema | JSON Schema for notebook frontmatter (agenda, status report, retro, etc.) | | prdSchema | JSON Schema for PRD frontmatter (status, domain, epic, version) | | pathAllowlistSchema | JSON Schema describing the shape of a path-allowlist policy | | defaultPathPolicy | Sensible default policy values (allow/deny globs, size limits, secret patterns) | | resolveSchemaForPath(path, policy?) | Returns the schema id (prd.json / notebook.json) for a given path, or null | | isAllowedPath(path, policy?) | Returns true if path is allowed and not denied | | matchGlob(pattern, value) | Minimal glob matcher supporting ?, *, ** |

You can also import individual schema documents:

import notebookSchema from "@10up/relay-schemas/schemas/notebook.json" with { type: "json" }

Quick example

import { notebookSchema, defaultPathPolicy, isAllowedPath } from "@10up/relay-schemas"

// Path policy
isAllowedPath("notebooks/agendas/2026-05-05.md") // → true
isAllowedPath("scripts/ci.sh") // → false (not in allow)
isAllowedPath("anything/.env") // → false (deny wins)

// Validate frontmatter against the notebook schema with your validator of choice.
// AJV example:
import Ajv from "ajv"
import addFormats from "ajv-formats"

const ajv = addFormats(new Ajv({ strict: false }))
const validate = ajv.compile(notebookSchema)

const ok = validate({
  title: "Standup 2026-05-05",
  kind: "agenda",
  created: "2026-05-05T09:30:00Z",
})
console.log(ok, validate.errors)

The schemas use the JSON Schema draft 2020-12 vocabulary. Any compliant validator works (AJV, hyperjump, jsonschema, etc.). This package does not bundle a validator.

Default path policy

defaultPathPolicy ships:

• allow: requirements/**/*.md, requirements/**/*.prd.md, notebooks/**/*.md, research/**/*.md
• deny: **/.git/**, **/node_modules/**, **/.env*, **/secrets/**, **/*.key, **/*.pem
• schema mapping: **/*.prd.md → prd.json, notebooks/**/*.md → notebook.json
• limits: maxFileBytes 200 KB, maxBatchBytes 1 MB, maxBatchFiles 20
• secretPatterns: AWS access keys, Google API keys, OpenAI keys, GitHub tokens, Slack tokens, PEM-format private keys

You can pass your own policy as the second argument to resolveSchemaForPath / isAllowedPath — it must conform to pathAllowlistSchema.

Versioning

Pre-1.0. Expect breaking changes between minor versions until 1.0.0. Schemas evolve as Relay's content model evolves; consumers should pin a known-good version.

License

MIT © 10up Inc.