Schemas

Every shape the SDK, mock, and storefronts must agree on lives as a zod schema in `@cimplify/sdk/testing`. Schemas are registered with metadata, paired with typed `assertX` helpers, and exported as JSON Schema for downstream tooling.

The registry

Each schema is registered with cimplifyRegistry alongside an id, description, and per-schema version. Per-schema versioning means consumers pinned to an old SDK can detect drift on just the contracts they care about, with no false positives from unrelated bumps.

import { cimplifyRegistry, CartSchema } from "@cimplify/sdk/testing";

const meta = cimplifyRegistry.get(CartSchema);
// { id: "Cart", description: "Cart shape returned by GET /cart", version: "1.0.0" }

Public schemas

Schema	Validates
`BrandSchema`	Your `lib/brand.ts`: every required field, valid email/phone/locale
`AddItemPayloadSchema`	Body for `POST /cart/items`; catches dropped `variant_id`, naked product IDs
`CartSchema`	Full cart response: `items[]`, `pricing`, `business_id`
`CartItemSchema`	A single line: `display_attributes`, money fields, quantity
`CartPricingSchema`	Subtotal, tax, discount, total
`CheckoutBodySchema`	Outbound checkout body: `cart_id`, `customer`, payment method
`CheckoutResponseSchema`	`bill_token`, `order_id`, optional `client_secret` / `next_action`
`MoneySchema`	Strict 2-decimal money string
`CurrencyCodeSchema`	ISO 4217
`SeedNameSchema`	`default \| empty \| retail \| restaurant \| services \| grocery \| fashion \| reesa-storefront`

assertX helpers

Every schema ships with a typed assertion that throws SchemaViolationError on failure and narrows the value type on success. The helpers wrap zod 4's z.prettifyError for human-readable output.

import { assertCart, assertBrand } from "@cimplify/sdk/testing";

assertCart(value);   // narrows value to Cart on success; throws on failure
assertBrand(value);  // narrows to Brand

SchemaViolationError

Structured error with the full zod issue list and an RFC 7807 toJSON(). Agents and CI can walk issues[] and act on each path directly.

import { assertCart, SchemaViolationError } from "@cimplify/sdk/testing";

try {
  assertCart(response);
} catch (err) {
  if (err instanceof SchemaViolationError) {
    console.error(err.label);   // "cart"
    console.error(err.issues);  // [{ path, message, code? }, …]
    console.error(err.toJSON()); // { type, title, status: 422, detail, errors[] }
  }
}

Sample toJSON() output

{
  "type": "https://cimplify.io/errors/schema-violation",
  "title": "Schema Violation",
  "status": 422,
  "detail": "cart did not match its schema",
  "errors": [
    { "path": ["items", "0", "variant_info", "display_attributes"], "message": "Required" }
  ]
}

JSON Schema export

zod 4 emits JSON Schema natively. Use it for OpenAPI specs, agent prompts, or codegen downstream of the SDK.

import { z } from "zod";
import { CartSchema } from "@cimplify/sdk/testing";

const json = z.toJSONSchema(CartSchema);
// { $id: "Cart", description: "...", type: "object", properties: { ... }, $defs: { ... } }

Custom schemas

Need a contract specific to your storefront (a fashion lookbook, a services policy)? Use registerSchema so it picks up the same registry plumbing.

import { z } from "zod";
import { registerSchema, makeAssertion } from "@cimplify/sdk/testing";

export const LookbookSchema = registerSchema(
  z.object({
    slug: z.string(),
    title: z.string().min(1),
    drops: z.array(z.object({ slug: z.string(), heroImage: z.string().url() })),
  }),
  { id: "Lookbook", description: "Fashion lookbook", version: "1.0.0" },
);

export const assertLookbook = makeAssertion(LookbookSchema, "lookbook");

Contracts SDK / backend pipeline that pins these schemas
Suites Where these assertions actually run