payload schema export

@yairl/payload-schema-export

A Payload 3 plugin that describes your site as JSON: collections, globals, fields, relations, select options, labels, locales, and every REST route, built-in and custom. Clients, code generators and schema-driven tools in any language read that one file instead of your Payload config.

• GET /api/_schema serves it, behind your own access rule.
• An API schema page in the admin summarises it and downloads schema.json.
• schema.schema.json in this package is the format as a JSON Schema, for validating the file or generating a reader for it.

// payload.config.ts
import { schemaExport } from '@yairl/payload-schema-export'

export default buildConfig({
  // ...
  plugins: [
    schemaExport({
      // Default: any signed-in user. The schema is a map of your data model.
      access: ({ req }) => Boolean(req.user?.roles?.includes('admin')),
    }),
  ],
})

pnpm add @yairl/payload-schema-export
pnpm payload generate:importmap   # so the admin page and sidebar link are found

Options

Option	Default
path	'/_schema'	Under your API route: GET /api/_schema
access	any signed-in user	({ req }) => boolean, used by the endpoint and the admin page
adminView	{ path: '/schema', showInSidebar: true }	The admin page; false for the endpoint alone
enabled	true	Turn the plugin off without removing it

What's in the file

{
  "schemaVersion": 1,
  "adminUserCollection": "users",
  "idType": "text",                       // or "number" (Postgres, SQLite)
  "localization": { "defaultLocale": "he", "locales": [{ "code": "he", "rtl": true }, …] },
  "api": {
    "basePath": "/api",
    "authorizationScheme": "JWT",         // Authorization: JWT <token>
    "cookieName": "payload-token",
    "routes": [{ "method": "get", "path": "/api/public-catalog" }, …],
    "graphQL": false
  },
  "collections": [{
    "slug": "posts",
    "drafts": true,
    "routes": [
      { "method": "get", "path": "/api/posts", "operation": "find" },
      { "method": "post", "path": "/api/posts/:id/publish" }   // custom: no operation
    ],
    "fields": [
      { "name": "title", "type": "text", "required": true, "localized": true },
      { "name": "author", "type": "relationship", "relationTo": "users" },
      …
    ]
  }],
  "globals": […]
}

SPEC.md describes every key. In short:

• It describes the sanitized config, so fields Payload adds (auth, upload, timestamps, _status for drafts) are there, because the API returns them.

• Nothing executable crosses. Function defaults and admin conditions become flags (hasDynamicDefault, admin.conditional); clients leave those to the server.

• Routes are the site's real route table, read from the config. Built-in ones carry Payload's operation name (find, login, getFile…). Custom ones carry their endpoint's custom object when it's plain JSON, which is the place to describe a custom route's request and response:

  endpoints: [{
    path: '/public-catalog',
    method: 'get',
    handler,
    custom: { description: 'Active exercises, no auth', response: { docs: 'Exercise[]' } },
  }]
  

Versioning

Adding keys doesn't change schemaVersion, so readers must ignore keys they don't know. The version goes up only for a change an existing reader would have to handle: a key removed, renamed, or changing type.

Clients

• Dart / Flutter: payload_flutter: generated models (payload_dart_gen), a REST client, and a schema-driven editor app.

Built one for another language? Open an issue and it goes on this list.

Development

pnpm install
pnpm test          # builds real sanitized configs and checks the output
pnpm build         # dist/ and schema.schema.json
pnpm fixture       # test/fixtures/schema.json, a sample for client tests
pnpm publish       # runs typecheck, tests and build first

License

MIT