Overview

Summary generated from the README

Provides a defineEntity and field facade that produces Payload field configs and matching Zod schemas from a single definition. Normalization such as trimming also runs on writes through the admin and Local API. It requires Payload 3.85 or newer, Zod 4 and Node 20.9 or newer, and is ESM-only.

Features

defineEntity with typed field helpers such as text, slug and number
Generates Payload field configs from one definition
Derives Zod schemas with pick and optional options
Native escape hatch for custom Payload fields with a Zod schema
Static and dynamic default values validated at definition time

Use cases

Share validation rules between Payload collections and external API or form code
Keep field normalization consistent across admin and Local API writes

Installation

npm i @nexload-sdk/payload-schema

Health Score

59/100Good

Composite score based on GitHub activity, stars, npm downloads, publish recency, dependency count, and package size.

Badge for your README

Markdown

[![Payload Directory](https://payloaddirectory.dev/badge/1086380959-payload-schema.svg)](https://payloaddirectory.dev/plugins/1086380959-payload-schema)

HTML

<a href="https://payloaddirectory.dev/plugins/1086380959-payload-schema"><img src="https://payloaddirectory.dev/badge/1086380959-payload-schema.svg" alt="Payload Directory"></a>

README

@nexload-sdk/payload-schema

Define intrinsic field validation and normalization once, then reuse it as ordinary Payload fields and ordinary Zod schemas.

Documentation · API reference

Install

pnpm add @nexload-sdk/payload-schema payload zod

Requires Node >=20.9.0, Payload >=3.85.0 <4, and Zod >=4 <5. The package is ESM-only and server/config safe.

Quick start

import { defineEntity, field } from "@nexload-sdk/payload-schema";

export const productEntity = defineEntity({
  name: "Product",
  fields: {
    title: field.text({ required: true, trim: true }),
    slug: field.slug({ required: true }),
    inventory: field.number({ integer: true, safe: true, defaultValue: 0 }),
  },
});

export const Products = {
  slug: "products",
  fields: productEntity.payload.all(),
};

Each facade call returns fresh Payload config containers. Canonical normalization also runs for writes through Payload Admin and the Local API.

Derive schemas

export const createProductSchema = productEntity.schema(({ pick }) =>
  pick(["title", "slug", "inventory"], {
    optional: ["inventory"],
  }),
);

entity.schema can return any Zod schema, not only objects or picks:

export const titleLengthSchema = productEntity.schema(({ fields }) =>
  fields.title.transform((title) => title.length),
);

Native escape hatch

import { z } from "zod";

const location = field.native({
  payload: { type: "point" },
  schema: z.tuple([z.number(), z.number()]),
});

A native data field without a schema still compiles for Payload but is unavailable to canonical schema derivation. Layout fields remain directly in collection configuration.

Defaults

defaultValue accepts a static value, validates it during defineEntity, and passes the canonical result to Payload.
dynamicDefaultValue accepts a native Payload function and is forwarded opaquely.
neither option adds Zod .default() behavior;
using both is invalid;
payload.defaultValue is reserved.

Non-goals

The package does not create collections, infer CRUD schemas, model populated relationship documents, generate persistence types, own access control or hooks, provide a rich-text editor, or implement business workflows.

Payload-generated types remain authoritative for stored documents. See the canonical documentation for architecture, fields, integration, errors, migration, and compatibility.

payload schema