@iraaai/pdp-schema

Schema, parser, validator, and template engine for the Product Discovery Protocol (PDP) — the open YAML spec that powers AI demo agents.

PDP is to AI demo agents what openapi.json is to REST APIs: a single declarative file that describes your product's screens, UI elements, demo flows, FAQ knowledge, and agent behaviour. iraa.ai's DemoAgent reads PDPs to give live, conversational product demos. Anyone can author or consume them — the spec and this validator are open-source.

Install

npm install @iraaai/pdp-schema

Usage

Validate a PDP YAML file

import { readFileSync } from 'node:fs';
import { parsePDP, validatePDP, formatValidationResult } from '@iraaai/pdp-schema';

const yaml = readFileSync('./my-product.pdp.yaml', 'utf8');
const pdp = parsePDP(yaml);
const result = validatePDP(pdp);

if (!result.ok) {
  console.error(formatValidationResult(result));
  process.exit(1);
}

The validator runs a strict Zod schema check plus a cross-validator that catches things Zod can't: broken element references, unreachable screens, dead flows, role-access mismatches, unused demo accounts, and more. Severity tiers are error / warning / info.

Use the types

import type { PDP, PDPProduct, PDPFlow, PDPScreen } from '@iraaai/pdp-schema';

Resolve flow steps for a persona

import { resolveFlow } from '@iraaai/pdp-schema';

const resolved = resolveFlow(pdp, 'sign-up-flow', { role: 'admin' });
// resolved.steps -> ordered, persona-specific steps with templates filled in

Why an open spec?

PDP is what makes a SaaS product agent-discoverable: a stable, self-describing artifact any AI agent can read to understand your product. The schema lives at this package; reference docs at https://iraa.ai/docs/pdp; the plain-English explainer at https://iraa.ai/pdp.

See also

• @iraaai/mcp-server — MCP server so any AI agent can drive demos
• @iraaai/cli — iraaai validate <file> lints PDPs from the command line
• @iraaai/sdk — programmatic SDK for running demo sessions
• PDP explainer · Schema reference

MIT — © iraa.ai