126 lines
4.2 KiB
Markdown
126 lines
4.2 KiB
Markdown
---
|
|
title: "JSON Field"
|
|
aliases: [payload-json-field, json-field-payload]
|
|
tags: [payloadcms, fields, json, validation, monaco]
|
|
sources: [raw/fields__json.md]
|
|
created: 2026-05-15
|
|
updated: 2026-05-15
|
|
---
|
|
|
|
The JSON Field stores raw JSON (object/array/primitive) directly in the database — unlike the [[wiki/payloadcms/fields-code|Code Field]] which stores a plain string. The Admin Panel shows a Monaco editor with full JSON syntax highlighting.
|
|
|
|
## Config
|
|
|
|
```ts
|
|
import type { Field } from 'payload'
|
|
|
|
export const MyJSONField: Field = {
|
|
name: 'customerJSON',
|
|
type: 'json',
|
|
required: true,
|
|
}
|
|
```
|
|
|
|
## Config Options
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `name` * | DB property name |
|
|
| `jsonSchema` | JSON Schema for validation + editor typeahead |
|
|
| `label` | Admin Panel label (string or i18n object) |
|
|
| `unique` | DB-level unique index |
|
|
| `index` | DB index for faster queries |
|
|
| `validate` | Custom validation function (client + server) |
|
|
| `saveToJWT` | Include in JWT if field is top-level in auth collection |
|
|
| `hooks` | Field lifecycle hooks |
|
|
| `access` | Field-level access control |
|
|
| `hidden` | Hide from all APIs + Admin (still saved to DB) |
|
|
| `defaultValue` | Default value |
|
|
| `localized` | Enable per-locale content |
|
|
| `required` | Make field mandatory |
|
|
| `virtual` | Disable DB column (`true`) or link to a relationship (`string path`) |
|
|
| `typescriptSchema` | Override generated TS type with JSON schema |
|
|
| `admin.editorOptions` | Pass options to Monaco editor |
|
|
|
|
## JSON Schema Validation
|
|
|
|
Attach a `jsonSchema` to enable:
|
|
- **Editor typeahead** — Monaco auto-completes properties and enums in the Admin Panel
|
|
- **Save-time validation** — invalid documents cannot be saved
|
|
|
|
### Local Schema
|
|
|
|
```ts
|
|
{
|
|
name: 'customerJSON',
|
|
type: 'json',
|
|
jsonSchema: {
|
|
uri: 'a://b/foo.json', // required (any unique URI)
|
|
fileMatch: ['a://b/foo.json'], // required (must match uri)
|
|
schema: {
|
|
type: 'object',
|
|
properties: {
|
|
foo: { enum: ['bar', 'foobar'] },
|
|
},
|
|
},
|
|
},
|
|
}
|
|
// {"foo": "bar"} ✓ {"foo": "other"} ✗
|
|
```
|
|
|
|
### Remote Schema
|
|
|
|
```ts
|
|
{
|
|
name: 'customerJSON',
|
|
type: 'json',
|
|
jsonSchema: {
|
|
uri: 'https://example.com/customer.schema.json',
|
|
fileMatch: ['https://example.com/customer.schema.json'],
|
|
// schema omitted — Payload fetches it from the URL
|
|
},
|
|
}
|
|
```
|
|
|
|
> **Gotcha:** If the remote URL is not publicly accessible, Payload will fail to fetch the schema. Embed the schema inline or import it from a local file.
|
|
|
|
## JSON vs Code Field
|
|
|
|
| | JSON Field | [[wiki/payloadcms/fields-code|Code Field]] |
|
|
|--|------------|------------|
|
|
| DB storage | Native JSON / JSONB | Plain string |
|
|
| Editor | Monaco (JSON mode) | Monaco (any language) |
|
|
| Validation | JSON Schema supported | Custom `validate` only |
|
|
| Use case | Structured data, API configs, metadata | Source code snippets, templates |
|
|
|
|
## Custom Components
|
|
|
|
Both Server and Client component patterns are supported. Import `JSONField` from `@payloadcms/ui`:
|
|
|
|
```tsx
|
|
// Server
|
|
import { JSONField } from '@payloadcms/ui'
|
|
import type { JSONFieldServerComponent } from 'payload'
|
|
|
|
export const CustomJSONFieldServer: JSONFieldServerComponent = ({
|
|
clientField, path, schemaPath, permissions,
|
|
}) => <JSONField field={clientField} path={path} schemaPath={schemaPath} permissions={permissions} />
|
|
|
|
// Client
|
|
'use client'
|
|
import type { JSONFieldClientComponent } from 'payload'
|
|
export const CustomJSONFieldClient: JSONFieldClientComponent = (props) => <JSONField {...props} />
|
|
```
|
|
|
|
## Key Takeaways
|
|
|
|
- `type: 'json'` stores actual JSON in the DB (not a stringified value) — use this when you need to query or index the JSON contents later
|
|
- `jsonSchema` unlocks both Monaco typeahead in the Admin Panel and automatic save-time validation — add it for any structured config or metadata field
|
|
- For remote schemas: if the URL is not public, embed the schema inline to avoid fetch failures
|
|
- `admin.editorOptions` accepts the full Monaco `EditorOptions` object for advanced editor configuration
|
|
- Use [[wiki/payloadcms/fields-code|Code Field]] instead when storing source code, templates, or any non-JSON string that just needs syntax highlighting
|
|
|
|
## Sources
|
|
|
|
- [Payload CMS — JSON Field docs](https://payloadcms.com/docs/fields/json)
|
|
- Raw file: `raw/fields__json.md`
|