Schemas & Validation - PRPM Documentation

Overview

PRPM uses JSON Schema to validate every package before publishing and during format conversion. This ensures package integrity, catches errors early, and provides helpful feedback when creating packages.

What Are Schemas?

JSON Schemas are specifications that define:

Required fields - What must be present (e.g., name, description)
Optional fields - What can be included (e.g., tools, model)
Field types - String, number, boolean, array, object
Field constraints - Min/max values, patterns, enums
Examples - Sample valid packages

When Validation Happens

1. During Publishing

When you run prpm publish, the CLI:

Detects your package format and subtype
Loads the appropriate JSON Schema
Validates all frontmatter fields
Checks required fields are present
Verifies field types and constraints
Reports any errors before publishing

prpm publish

# ❌ Validation error: Missing required field 'description'
# ❌ Field 'temperature' must be between 0.0 and 1.0

2. During Format Conversion

When converting packages with prpm convert:

Validates source format before conversion
Converts to target format
Validates output against target schema
Reports any data loss or incompatibilities

prpm convert agent.md --from claude --to opencode

# ✅ Source validation passed
# ⚠️  Warning: 'permissionMode' field not supported in OpenCode
# ✅ Output validation passed

3. During Package Installation

When installing packages, PRPM:

Validates package structure from registry
Ensures format compatibility with your IDE
Checks for required dependencies

Supported Formats & Schemas

Base Format Schemas

Every supported AI IDE has a base schema:

Format	Schema	Description
Claude Code	`claude.schema.json`	Base schema for Claude packages
Cursor	`cursor.schema.json`	MDC format with YAML frontmatter
Continue	`continue.schema.json`	Rules with glob/regex matching
Windsurf	`windsurf.schema.json`	Plain markdown (12k char limit)
GitHub Copilot	`copilot.schema.json`	Path-specific instructions
Kiro	`kiro-steering.schema.json`	Steering files with frontmatter
Factory Droid	`droid.schema.json`	Base schema for Droid packages
OpenCode	`opencode.schema.json`	Agent configuration with tools
Gemini CLI	`gemini.schema.json`	Google Gemini format
Ruler	`ruler.schema.json`	Centralized rule management
agents.md	`agents-md.schema.json`	OpenAI single-file format

Subtype Schemas

Formats with multiple package types have specialized schemas:

Claude Code

claude-agent.schema.json - AI agents with tools and permissions
claude-skill.schema.json - Specialized skills (name + description only)
claude-slash-command.schema.json - Custom slash commands
claude-hook.schema.json - Event-driven hooks

Factory Droid

droid-skill.schema.json - Reusable workflows
droid-slash-command.schema.json - Commands with argument hints
droid-hook.schema.json - Event automations (JSON format)

OpenCode

opencode-slash-command.schema.json - Template-based commands with placeholders

Kiro

kiro-agent.schema.json - Custom AI agents (JSON)
kiro-hooks.schema.json - Event hooks (JSON)

Cursor

cursor-command.schema.json - Cursor slash commands

Accessing Schemas

Public Registry API

All schemas are publicly accessible via the PRPM registry: List all schemas:

curl https://registry.prpm.dev/api/v1/schemas

Get a base format schema:

curl https://registry.prpm.dev/api/v1/schemas/cursor.json

Get a subtype schema:

curl https://registry.prpm.dev/api/v1/schemas/claude/agent.json

Response:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://registry.prpm.dev/api/v1/schemas/claude/agent.json",
  "title": "Claude Code Agent Format",
  "description": "JSON Schema for Claude Code Agents",
  ...
}

Other Access Methods

1. View in Repository

https://github.com/pr-pm/prpm/tree/main/packages/converters/schemas

2. Local Development

# Source schemas
packages/converters/schemas/*.schema.json

# Bundled with CLI
node_modules/prpm/dist/schemas/*.schema.json

3. Direct URLs Schemas are available at: Base format schemas:

https://registry.prpm.dev/api/v1/schemas/{format}.json

Subtype schemas:

https://registry.prpm.dev/api/v1/schemas/{format}/{subtype}.json

Examples:

https://registry.prpm.dev/api/v1/schemas/cursor.json (base format)
https://registry.prpm.dev/api/v1/schemas/claude/agent.json (subtype)
https://registry.prpm.dev/api/v1/schemas/droid/slash-command.json (multi-word subtype)
https://registry.prpm.dev/api/v1/schemas/opencode/slash-command.json (subtype)

3. Programmatic Access

import { validateMarkdown, validateFormat } from '@pr-pm/converters';

// Validate markdown with frontmatter
const result = validateMarkdown('claude', markdownContent, 'agent');

if (!result.valid) {
  console.error('Validation errors:', result.errors);
  result.errors.forEach(error => {
    console.log(`${error.path}: ${error.message}`);
  });
}

// Validate structured data
const packageData = {
  frontmatter: {
    name: 'my-agent',
    description: 'AI agent that reviews code',
    mode: 'subagent',
    tools: 'Read, Grep, Bash'
  },
  content: '# Code Reviewer\n\nYou are an expert code reviewer.'
};

const result2 = validateFormat('opencode', packageData, 'agent');

Common Validation Errors

Missing Required Fields

---
# ❌ Missing 'description' field
name: my-agent
---

Fix:

---
name: my-agent
description: Brief explanation of what this agent does  # ✅ Added
---

Invalid Field Types

---
description: Test agent
temperature: "0.5"  # ❌ String instead of number
---

Fix:

---
description: Test agent
temperature: 0.5  # ✅ Number type
---

Invalid Enum Values

---
description: Test agent
mode: "standalone"  # ❌ Invalid mode
---

Fix:

---
description: Test agent
mode: "subagent"  # ✅ Valid: "primary", "subagent", or "all"
---

Out of Range Values

---
description: Test agent
temperature: 1.5  # ❌ Must be 0.0-1.0
---

Fix:

---
description: Test agent
temperature: 0.7  # ✅ Within valid range
---

Validation in CI/CD

GitHub Actions Example

name: Validate PRPM Package

on:
  pull_request:
    paths:
      - '.claude/**'
      - '.cursor/**'
      - 'prpm.json'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install PRPM
        run: npm install -g prpm

      - name: Validate Package
        run: prpm publish --dry-run

      - name: Report Validation Results
        if: failure()
        run: echo "❌ Package validation failed. Check the logs above for details."

Schema Development

Creating Custom Schemas

If you’re adding support for a new AI IDE:

Study the format - Understand frontmatter fields, file structure, and constraints
Create base schema - Define required and optional fields
Add subtype schemas - If format has multiple types (agent, skill, command)
Update validation - Map schema in validation.ts
Test thoroughly - Create fixtures and run validation tests

See the adding-new-ai-format skill for complete instructions.

Best Practices

Validate Before Publishing

Run prpm publish --dry-run to catch errors before publishing

Use Strict Mode

Enable strict validation in your IDE to catch issues during development

Follow Schema Examples

Reference example packages in each schema for correct structure

Check Conversion Warnings

Review warnings when converting between formats for potential data loss

Format Specifications

Detailed specs for each AI IDE format

Publishing Guide

Step-by-step publishing workflow

Format Conversion

Convert packages between different AI IDEs

Package Structure

Understanding PRPM package anatomy

Get Started

Core Concepts

Guides

Publishing

Advanced

​Overview

​What Are Schemas?

​When Validation Happens

​1. During Publishing

​2. During Format Conversion

​3. During Package Installation

​Supported Formats & Schemas

​Base Format Schemas

​Subtype Schemas

​Claude Code

​Factory Droid

​OpenCode

​Kiro

​Cursor

​Accessing Schemas

​Public Registry API

​Other Access Methods

​Common Validation Errors

​Missing Required Fields

​Invalid Field Types

​Invalid Enum Values

​Out of Range Values

​Validation in CI/CD

​GitHub Actions Example

​Schema Development

​Creating Custom Schemas

​Best Practices

Validate Before Publishing

Use Strict Mode

Follow Schema Examples

Check Conversion Warnings

​Further Reading

Format Specifications

Publishing Guide

Format Conversion

Package Structure

Overview

What Are Schemas?

When Validation Happens

1. During Publishing

2. During Format Conversion

3. During Package Installation

Supported Formats & Schemas

Base Format Schemas

Subtype Schemas

Claude Code

Factory Droid

OpenCode

Kiro

Cursor

Accessing Schemas

Public Registry API

Other Access Methods

Common Validation Errors

Missing Required Fields

Invalid Field Types

Invalid Enum Values

Out of Range Values

Validation in CI/CD

GitHub Actions Example

Schema Development

Creating Custom Schemas

Best Practices

Further Reading