Schema Validation

Every Arete stack ships with Zod schemas alongside its TypeScript interfaces. These schemas give you runtime validation at two levels: automatic frame validation on the wire, and per-query validation in your application code.

Generated Schemas

When you run a4 sdk create typescript, the CLI generates a Zod schema for every entity and sub-type. These mirror the TypeScript interfaces exactly:

import {
  PumpfunTokenSchema,
  PumpfunTokenIdSchema,
  PumpfunTokenReservesSchema,
  PumpfunTokenCompletedSchema,
} from "./generated/pumpfun-stack";

Each entity gets schemas for complete frames, sparse patches, and completed-entity assertions:

Schema	Use Case
`PumpfunTokenSchema`	Complete frames and normalized stored entities
`PumpfunTokenPatchSchema`	Sparse patch frames
`PumpfunTokenCompletedSchema`	Application-level completed-entity assertion

The “Completed” variant is useful when a stack distinguishes fully populated application entities from its normal stored shape. It may be identical to the base schema when every section is always present, and it does not remove field nullability unless the generated schema explicitly says so.

Frame Validation

Generated schemas always normalize and validate every incoming WebSocket frame before it reaches the typed store. Invalid frames are dropped with a console warning instead of corrupting local state.

TypeScript (Core SDK)

import { Arete } from "@usearete/sdk";
import { ORE_STREAM_STACK } from "./generated/ore-stack";

const a4 = await Arete.connect(ORE_STREAM_STACK, {
  onFrameValidationError(diagnostic) {
    console.error('Rejected Arete frame', diagnostic);
  },
});

React

import { AreteProvider } from "@usearete/react";
import { ORE_STREAM_STACK } from "./generated/ore-stack";

const publishableKey = import.meta.env.VITE_ARETE_PUBLISHABLE_KEY;
if (!publishableKey) throw new Error("VITE_ARETE_PUBLISHABLE_KEY is required");

function App() {
  return (
    <AreteProvider
      stack={ORE_STREAM_STACK}
      auth={{ publishableKey }}
      onFrameValidationError={(diagnostic) => reportDiagnostic(diagnostic)}
    >
      <Dashboard />
    </AreteProvider>
  );
}

The diagnostic includes the view, entity key, sequence when available, operation, and schema error. The malformed update is never stored.

Query-Level Validation

Pass a schema option to any streaming method to filter entities that don’t match. React hooks can also report caller-supplied schema rejections through a diagnostic callback.

TypeScript (Core SDK)

The .use() method accepts a schema in its options. Entities that fail validation are skipped:

import { Arete } from "@usearete/sdk";
import {
  ORE_STREAM_STACK,
  OreRoundCompletedSchema,
} from "./generated/ore-stack";

const a4 = await Arete.connect(ORE_STREAM_STACK);

// Only emit rounds where every field is present
for await (const round of a4.views.OreRound.latest.use({
  schema: OreRoundCompletedSchema,
})) {
  // round is guaranteed to have all fields populated
  console.log(round.id.roundId, round.state.motherlode);
}

React Hooks

Both .use() and .useOne() accept schema and onSchemaValidationError in their params. Entities that fail validation are filtered out of the results:

import { useArete } from "@usearete/react";
import {
  ORE_STREAM_STACK,
  OreRoundCompletedSchema,
} from "./generated/ore-stack";

function FullyLoadedRounds() {
  const { views } = useArete(ORE_STREAM_STACK);

  // Only returns rounds where all fields are present
  const { data: rounds } = views.OreRound.latest.use({
    schema: OreRoundCompletedSchema,
    onSchemaValidationError(diagnostic) {
      reportDiagnostic(diagnostic);
    },
  });

  return (
    <ul>
      {rounds?.map((round) => (
        <li key={round.id.roundId?.toString() ?? "unknown"}>
          Round #{round.id.roundId?.toString() ?? "unknown"} — {round.state.motherlode?.toString() ?? "unavailable"}
        </li>
      ))}
    </ul>
  );
}

Custom Schemas

You can define your own Zod schemas to validate only the fields you care about. This is useful for building views that require specific data to render:

import { z } from "zod";

// Only accept tokens with complete trading data
const TradableTokenSchema = z.object({
  id: z.object({
    mint: z.string(),
  }),
  reserves: z.object({
    currentPriceSol: z.number(),
    marketCapSol: z.number(),
  }),
  trading: z.object({
    totalVolume: z.number(),
    totalTrades: z.number(),
  }),
});

// Use in React
const { data: tokens } = views.PumpfunToken.list.use({
  schema: TradableTokenSchema,
});

// Or in core SDK
for await (const token of a4.views.PumpfunToken.list.use({
  schema: TradableTokenSchema,
})) {
  console.log(token.id.mint, token.reserves.currentPriceSol);
}

Any entity missing the required fields is excluded.

Caller-Supplied Schema Diagnostics

React’s onSchemaValidationError(diagnostic) is scoped to the caller-supplied view schema. Its diagnostic has this shape:

type SchemaValidationDiagnostic = {
  view: string;
  key?: string;
  entity: unknown;
  error: unknown;
};

This callback is additive. Entities accepted by the schema continue through unchanged, and rejected entities remain excluded exactly as they were without the callback. It is separate from onFrameValidationError, which reports rejection by the generated wire-frame schemas before storage.

The Schema Interface

The SDK defines a minimal Schema<T> interface that is natively compatible with Zod:

interface Schema<T> {
  safeParse: (input: unknown) => SchemaResult<T>;
}

type SchemaResult<T> =
  | { success: true; data: T }
  | { success: false; error: unknown };

Any object with a safeParse method works — Zod schemas satisfy this out of the box, but you can also use custom validators if needed.

Next Steps

TypeScript SDK — Core streaming API reference
React SDK — Hooks and providers for React apps
Resolvers — How Arete enriches entities with external data like token metadata