Validate and generate UCP (Universal Commerce Protocol) Business Profiles
npm install @ucptools/validator
Validate and generate UCP (Universal Commerce Protocol) Business Profiles for AI-powered shopping agents like ChatGPT, Google AI Mode, and Copilot checkout.
> Try it online: ucptools.dev - Free AI Commerce Readiness Checker
---
The Universal Commerce Protocol is an open standard enabling AI agents to discover, browse, and complete purchases on any UCP-enabled merchant. Google announced UCP on January 11, 2026, with support from Shopify, Target, Walmart, and 20+ ecosystem partners.
This library helps you:
- Validate your UCP profile for compliance
- Generate properly formatted UCP profiles
- Verify schemas and capability declarations
---
``bash`
npm install @ucptools/validator
---
`typescript
import { validateProfile, validateQuick, validateRemote } from '@ucptools/validator';
// Validate a local profile object
const report = await validateProfile(myProfile);
console.log(report.ok ? 'Valid!' : 'Issues found:', report.issues);
// Quick validation (no network calls)
const quickReport = validateQuick(myProfile);
// Validate a remote profile by domain
const remoteReport = await validateRemote('example.com');
`
`typescript
import { buildProfile, generateMinimalProfile } from '@ucptools/validator';
// Generate a minimal profile (checkout only)
const minimal = generateMinimalProfile({
endpoint: 'https://api.yourstore.com/ucp/v1',
});
// Generate a full profile
const result = await buildProfile({
merchant: {
merchantId: 'store-123',
primaryDomain: 'yourstore.com',
},
transport: {
rest: { endpoint: 'https://api.yourstore.com/ucp/v1' },
},
capabilities: {
checkout: true,
order: true,
fulfillment: false,
discount: false,
product: false,
inventory: false,
},
});
console.log(result.profileJson);
`
`typescript
import { generateSigningKeyPair } from '@ucptools/validator';
// Generate Ed25519 key pair for Order capability
const { publicKey, privateKey, kid } = await generateSigningKeyPair('Ed25519');
`
---
must use ucp.dev URLs)
- Extension chain validation (no orphaned extends)
- Endpoint rules (HTTPS, no trailing slash)
- Signing keys requirement for Order capability$3
- Fetch and verify remote schemas
- Self-describing schema validation
- Schema/capability version matching---
Validation Report
`typescript
interface ValidationReport {
ok: boolean; // true if no errors
profile_url?: string; // URL of validated profile
ucp_version?: string; // UCP version from profile
issues: ValidationIssue[]; // Array of issues found
validated_at: string; // ISO timestamp
validation_mode: ValidationMode;
}interface ValidationIssue {
severity: 'error' | 'warn' | 'info';
code: string; // e.g., 'UCP_NS_ORIGIN_MISMATCH'
path: string; // JSON path, e.g., '$.ucp.capabilities[0]'
message: string;
hint?: string; // Suggestion to fix
}
`---
Error Codes
| Code | Severity | Description |
|------|----------|-------------|
|
| error | Missing ucp object at root |
| UCP_MISSING_VERSION | error | Missing version field |
| UCP_INVALID_VERSION_FORMAT | error | Version not in YYYY-MM-DD format |
| UCP_NS_ORIGIN_MISMATCH | error | Schema URL doesn't match namespace origin |
| UCP_ORPHANED_EXTENSION | error | Extends references non-existent capability |
| UCP_ENDPOINT_NOT_HTTPS | error | Endpoint must use HTTPS |
| UCP_ENDPOINT_TRAILING_SLASH | warn | Remove trailing slash from endpoint |
| UCP_MISSING_SIGNING_KEYS | error | Order capability requires signing_keys |
| UCP_SCHEMA_FETCH_FAILED | warn | Could not fetch remote schema |---
CLI Usage
`bash
Validate a local file
npx @ucptools/validator validate -f ucp.jsonValidate a remote profile
npx @ucptools/validator validate -r yourstore.comGenerate a minimal profile
npx @ucptools/validator generate-minimal -e https://api.example.com/ucp/v1 -o ucp.json
``---
Don't want to install anything? Use our free online tool:
ucptools.dev - AI Commerce Readiness Checker
- Validates UCP profiles + Schema.org requirements
- Generates UCP profiles with a simple form
- Creates Schema.org snippets (MerchantReturnPolicy, shippingDetails)
- Provides A-F grading and actionable recommendations
---
- UCP Specification
- UCP GitHub Repository
- Google UCP Business Profile Guide
- UCP JavaScript SDK
---
Contributions are welcome! Please read our Contributing Guide for details.
---
MIT - See LICENSE for details.
---
Built with love for the AI Commerce ecosystem
ucptools.dev