How to Validate Your UCP Profile: A Step-by-Step Guide

TL;DR

A valid UCP profile is essential for AI shopping agents to interact with your store. This guide walks you through validating your /.well-known/ucp file, understanding validation errors, and fixing common issues.

Quick validation: Go to ucptools.dev and enter your domain.

---

Why Validate Your UCP Profile?

AI shopping is growing fast. ChatGPT, Google AI Mode, and Microsoft Copilot can now complete purchases on behalf of users. But these agents need valid UCP profiles to interact with your store.

An invalid UCP profile means:

• AI agents skip your store entirely
• Checkout flows fail mid-transaction
• Lost sales from AI-assisted shopping
• Poor AI readiness scores

A valid UCP profile means:

• Full AI agent compatibility
• Successful checkouts
• Higher visibility in AI recommendations
• Future-proofed commerce

---

The Four Levels of UCP Validation

UCP validation happens at four levels. Each catches different types of issues:

1. Structural Validation

Checks the basic JSON structure:

• Valid JSON syntax
• Required fields present (ucp, version, services, capabilities, signing_keys, payment handlers)
• Correct data types for each field
• JWK signing key structure (kty, kid required)
• Payment handler configuration

2. Rules Validation

Checks UCP specification compliance:

• HTTPS endpoints (not HTTP)
• No trailing slashes in URLs
• Namespace/origin binding (dev.ucp.* schemas must be from ucp.dev)
• Extension chains (parent capabilities must exist)

3. Network Validation

Checks accessibility and schemas:

• Can fetch remote schemas
• Self-describing profile verification
• Endpoint reachability

4. SDK Validation

Tests against the official SDK:

• Full @ucp-js/sdk compliance
• Complete specification adherence

---

Step-by-Step Validation Guide

Step 1: Open the Validator

Go to ucptools.dev and find the validator section.

Step 2: Enter Your Domain

Type your store's domain (e.g., mystore.com or mystore.myshopify.com).

Don't include:

• https:// prefix
• /.well-known/ucp path
• Trailing slashes

Just the domain: mystore.com

Step 3: Run Validation

Click "Check" to start validation. The tool will:

1. Fetch your /.well-known/ucp file
2. Parse the JSON
3. Run all validation checks
4. Generate a report

Step 4: Review Results

You'll see:

AI Readiness Score: 0-100 score based on:

• UCP compliance (40 points)
• Schema.org markup (30 points)
• Performance (30 points)

Validation Issues: Any errors or warnings with:

• Severity (error, warning, info)
• Error code
• JSON path to the issue
• Specific fix hint

Step 5: Fix Issues

For each issue, follow the provided hint. Re-run validation after fixes.

---

Common Validation Errors and Fixes

UCP_MISSING_ROOT

Error: Missing or invalid root object / No ucp object found.

Fix: Add the required ucp wrapper with version, services, and capabilities:

{
  "ucp": {
    "version": "2026-01-11",
    "services": { ... },
    "capabilities": [ ... ]
  }
}

UCP_MISSING_VERSION

Error: Missing version field.

Fix: Add version in YYYY-MM-DD format:

{
  "ucp": {
    "version": "2026-01-11",
    ...
  }
}

UCP_INVALID_VERSION_FORMAT

Error: Version must be YYYY-MM-DD format.

Fix: Use date format like 2026-01-11, not 1.0 or v1.

UCP_ENDPOINT_NOT_HTTPS

Error: Endpoint uses HTTP instead of HTTPS.

Fix: Change all endpoints to HTTPS:

// Wrong
"endpoint": "http://mystore.com/api/ucp"

// Correct
"endpoint": "https://mystore.com/api/ucp"

UCP_ENDPOINT_TRAILING_SLASH

Error: Endpoint URL has trailing slash.

Fix: Remove trailing slashes:

// Wrong
"endpoint": "https://mystore.com/api/ucp/"

// Correct
"endpoint": "https://mystore.com/api/ucp"

UCP_MISSING_SIGNING_KEYS

Error: No signing keys found.

Fix: Add Ed25519 or ES256 signing keys:

{
  "signing_keys": [
    {
      "kid": "key-1",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "base64-encoded-public-key",
      "use": "sig",
      "alg": "EdDSA"
    }
  ]
}

Use the UCPtools generator to create signing keys automatically.

UCP_MISSING_PAYMENT_HANDLERS

Error: Missing required "payment" object or handlers.

Fix: Add payment object with handlers array (required by UCP spec 2026-01-11):

{
  "payment": {
    "handlers": [
      {
        "id": "google_pay",
        "name": "Google Pay",
        "version": "2026-01-11",
        "spec": "https://ucp.dev/handlers/google-pay/"
      }
    ]
  }
}

UCP_NS_ORIGIN_MISMATCH

Error: Schema URL doesn't match namespace authority.

Fix: Ensure schema URLs match your domain or use official UCP schemas:

// Wrong - schema from different domain than namespace
{
  "name": "com.mystore.custom",
  "schema": "https://otherdomain.com/schemas/custom.json"
}

// Correct - use matching domain
{
  "name": "com.mystore.custom",
  "schema": "https://mystore.com/schemas/custom.json"
}

// Or use official UCP schemas
{
  "name": "dev.ucp.shopping.checkout",
  "schema": "https://ucp.dev/schemas/shopping/checkout.json"
}

UCP_ORPHANED_EXTENSION

Error: Extension has no parent capability.

Fix: Either add the parent capability or remove the extension:

{
  "capabilities": [
    // Parent capability
    {
      "name": "dev.ucp.shopping.checkout",
      "version": "2026-01-11"
    },
    // Extension that extends checkout
    {
      "name": "dev.ucp.shopping.fulfillment",
      "version": "2026-01-11",
      "extends": "dev.ucp.shopping.checkout"
    }
  ]
}

---

Understanding Severity Levels

Error (Red)

Must be fixed. Profile won't work correctly with AI agents.

Examples:

• Missing required fields
• Invalid JSON syntax
• HTTP endpoints

Warning (Yellow)

Should be fixed. May cause issues with some agents.

Examples:

• Missing optional but recommended fields
• Deprecated features

Info (Blue)

Good to know. Won't break anything but could be improved.

Examples:

• Suggestions for optimization
• New features available

---

Beyond Basic Validation

After fixing validation errors, consider these advanced checks:

AI Agent Simulation

Test how AI agents actually interact with your store:

• Discovery flow
• Capability inspection
• Checkout simulation

Use the Simulator tab at ucptools.dev.

Security Scan

Check for security issues:

• SSL configuration
• CORS settings
• API security

Use the Security tab at ucptools.dev.

Competitive Benchmarking

See how your AI readiness compares to competitors:

• Industry percentile
• Score breakdown
• Improvement suggestions

---

Validation Checklist

Before launching with UCP, validate that:

• [ ] Profile accessible at /.well-known/ucp
• [ ] Valid JSON syntax
• [ ] ucp object present at root level
• [ ] Version in YYYY-MM-DD format (e.g., "2026-01-11")
• [ ] Services defined with version, spec, and transport bindings
• [ ] Capabilities defined with name, version, spec, and schema
• [ ] All endpoints use HTTPS (not HTTP)
• [ ] No trailing slashes in URLs
• [ ] Signing keys present and valid (JWK format with kty, kid)
• [ ] Payment handlers configured
• [ ] Extensions have parent capabilities
• [ ] dev.ucp.* schemas from ucp.dev domain
• [ ] No validation errors

---

When to Re-Validate

Run validation again when you:

1. Change platform settings - Updates to checkout, APIs, etc.
2. Deploy new features - New capabilities or extensions
3. Update API endpoints - URL changes
4. Renew certificates - SSL/TLS updates
5. Monthly maintenance - Regular health checks

---

Get Help

If you're stuck on a validation error:

1. Check the UCP Learn page for concepts
2. Review platform guides for your specific platform
3. Use the UCP Generator to create a valid profile from scratch

---

Conclusion

Validating your UCP profile is essential for AI commerce success. A few minutes of validation now prevents lost sales later.

Ready to validate? Head to ucptools.dev/validator and check your profile in seconds.

---

UCPtools is an independent community tool for validating and generating UCP profiles. UCP is an open standard developed by Google and Shopify.