Quickstart

This path is for the developer who has never installed an OCG package and wants to see a readiness report quickly.

The package names below are the intended public npm surfaces. The live site and /demo runtime already run the release-candidate code; npm publishing happens after the final repo cleanup pass.

Prerequisites once packages are public: Node 24 or newer and pnpm 10.x, npm 10.x, or yarn 4.x.

Install after public package publish

pnpm add @realworldcommerce/ocg-schema @realworldcommerce/known-business-validator

record.json

{
  "schemaVersion": "3.0.0-draft",
  "recordId": "kb_acme-llc_acme-flagship_a1b2c3d4",
  "recordType": "known_business",
  "lifecycleStatus": "draft",
  "identity": { "displayName": "Acme LLC" },
  "locations": [{ "id": "loc-1", "type": "service_area" }],
  "categories": [{ "id": "cat-1", "taxonomy": "custom", "code": "general", "label": "General" }],
  "services": [{ "id": "svc-1", "name": "Consulting" }],
  "proof": [],
  "metadata": {
    "createdAt": "2026-05-25T00:00:00.000Z",
    "updatedAt": "2026-05-25T00:00:00.000Z",
    "source": "manual"
  }
}

validate.mjs

import { parseKnownBusinessRecord } from '@realworldcommerce/ocg-schema/zod';
import { normalizeKnownBusinessRecord } from '@realworldcommerce/ocg-schema/normalize';
import { validateKnownBusinessRecord } from '@realworldcommerce/known-business-validator/validation';
import { formatReport } from '@realworldcommerce/known-business-validator/formatters';
import { readFile } from 'node:fs/promises';

const raw = await readFile('./record.json', 'utf8');
const parsed = parseKnownBusinessRecord(JSON.parse(raw));
if (!parsed.ok) process.exit(1);

const normalized = normalizeKnownBusinessRecord(parsed.value);
if (!normalized.ok) process.exit(1);

const report = validateKnownBusinessRecord(normalized.value);
console.log(formatReport(report, 'text'));

Run node validate.mjs. The output reports overall score, per-signal scores, lifecycle status, computed status, effective status, and sorted issues.

In-browser validator

This widget imports the OSS @realworldcommerce/ocg-schema and @realworldcommerce/known-business-validator code directly from the release repo. Paste a record or load a fixture; parsing, normalization, scoring, formatting, and content hashing all run in your browser.

{
  "schemaVersion": "3.0.0-draft",
  "recordId": "kb_desert-summit-roofing_roofing-flagship_deadbeef",
  "recordType": "known_business",
  "lifecycleStatus": "published",
  "identity": {
    "displayName": "Desert Summit Roofing",
    "legalName": "Desert Summit Roofing, LLC",
    "description": "Fictional demo roofing company used to exercise the Open Commerce Graph schema and validator.",
    "url": "https://desert-summit-roofing.example.com",
    "domain": "desert-summit-roofing.example.com",
    "email": "hello@desert-summit-roofing.example.com",
    "phone": "+16025550110",
    "contacts": [
      {
        "id": "contact_support",
        "type": "support_url",
        "value": "https://desert-summit-roofing.example.com/support",
        "preferred": true
      },
      {
        "id": "contact_social",
        "type": "social",
        "value": "https://example.com/social/desert-summit-roofing"
      }
    ],
    "businessIdentifier": {
      "type": "state_filing",
      "value": "AZ-DEMO-0001",
      "issuedBy": "AZ Corporation Commission",
      "visibility": "public"
    }
  },
  "locations": [
    {
      "id": "loc_flagship",
      "type": "physical",
      "name": "Desert Summit yard",
      "address": {
        "streetAddress": "100 Example Mesa Way",
        "addressLocality": "Phoenix",
        "addressRegion": "AZ",
        "postalCode": "85001",
        "addressCountry": "US"
      },
      "geo": {
        "latitude": 33.4484,
        "longitude": -112.074
      },
      "areaServed": [
        "Phoenix, AZ",
        "Tempe, AZ",
        "Mesa, AZ"
      ],
      "openingHours": [
        {
          "dayOfWeek": [
            "Monday",
            "Tuesday",
            "Wednesday",
            "Thursday",
            "Friday"
          ],
          "opens": "07:00",
          "closes": "17:00"
        }
      ],
      "primary": true
    }
  ],
  "categories": [
    {
      "id": "cat_roofing",
      "taxonomy": "schema_org",
      "code": "HomeAndConstructionBusiness",
      "label": "Roofing contractor",
      "primary": true
    },
    {
      "id": "cat_naics_roofing",
      "taxonomy": "naics",
      "code": "238160",
      "label": "Roofing contractors"
    }
  ],
  "services": [
    {
      "id": "svc_roof_repair",
      "name": "Residential roof repair",
      "description": "Patch and re-flash damaged roof sections on single-family homes.",
      "priceModel": {
        "type": "starting_at",
        "currency": "USD",
        "amount": "450.00"
      },
      "locationIds": [
        "loc_flagship"
      ],
      "actionMapping": {
        "kind": "book",
        "actionId": "act_book_repair"
      }
    },
    {
      "id": "svc_roof_inspection",
      "name": "Roof inspection",
      "description": "Annual inspection with a written report.",
      "priceModel": {
        "type": "fixed",
        "currency": "USD",
        "amount": "199.00"
      },
      "locationIds": [
        "loc_flagship"
      ]
    }
  ],
  "proof": [
    {
      "id": "proof_domain",
      "type": "domain_control",
      "status": "verified",
      "authority": {
        "type": "self",
        "name": "DNS TXT record",
        "url": "https://desert-summit-roofing.example.com/.well-known/ocg.txt"
      },
      "evidence": {
        "url": "https://desert-summit-roofing.example.com/.well-known/ocg.txt",
        "description": "DNS TXT record asserts ocg-verification token."
      },
      "issuedAt": "2026-04-15T00:00:00.000Z"
    },
    {
      "id": "proof_license",
      "type": "license",
      "status": "verified",
      "authority": {
        "type": "government",
        "name": "Arizona Registrar of Contractors",
        "url": "https://example.com/azroc/lookup"
      },
      "evidence": {
        "url": "https://example.com/azroc/lookup/AZ-DEMO-0001",
        "description": "Active Arizona roofing contractor license (fictional demo record)."
      },
      "issuedAt": "2025-01-10T00:00:00.000Z",
      "expiresAt": "2027-01-10T00:00:00.000Z"
    }
  ],
  "metadata": {
    "createdAt": "2026-04-15T00:00:00.000Z",
    "updatedAt": "2026-05-21T15:00:00.000Z",
    "publishedAt": "2026-04-20T00:00:00.000Z",
    "source": "fictional-demo",
    "ownerController": "demo-fixtures@example.com",
    "canonicalUrl": "https://desert-summit-roofing.example.com/known-business"
  },
  "solana": {
    "network": "devnet",
    "merchantWallet": "DemoMerchant1Roofing111111111111111111111111",
    "paymentEndpoints": [
      {
        "id": "endpoint_pay",
        "url": "https://desert-summit-roofing.example.com/solana-pay",
        "label": "Pay deposit"
      }
    ],
    "memoPrefix": "OCG"
  },
  "actions": [
    {
      "id": "act_book_repair",
      "kind": "book",
      "url": "https://desert-summit-roofing.example.com/book/repair",
      "label": "Book repair",
      "description": "Schedule a fictional demo roof repair appointment."
    }
  ]
}

Waiting for input

Parse: not_run
Normalize: not_run