JSON Field

The JSON field stores JSON values directly. In the admin panel, editors work in a code editor with syntax highlighting. Use a Code field instead when the database value must always be a string.

import type { CollectionConfig } from 'frogbot'

export const Settings: CollectionConfig = {
  slug: 'settings',
  fields: [
    {
      name: 'theme',
      type: 'json',
      required: true,
    },
  ],
}

Config options

Option	Type	Default	Description
`name`	`string`	Required	Property name used in stored records and APIs. See field names.
`type`	`'json'`	Required	Selects the JSON field.
`jsonSchema`	`{ uri: string; fileMatch: string[]; schema: JSONSchema4 }`	—	JSON Schema used for editor suggestions and validation. See JSON Schema validation.
`label`	`string \| Record<string, string> \| (({ i18n, t }) => string) \| false`	Generated from `name`	Label shown in the admin panel. Use an object keyed by language code for translations, or `false` to hide the label.
`required`	`boolean`	`false`	Rejects an empty value in the default validation.
`unique`	`boolean`	`false`	Creates a unique database index for the field path. See indexes.
`index`	`boolean`	`false`	Creates a database index for faster queries. `unique` already creates one.
`localized`	`boolean`	`false`	Stores one value per configured locale. Ignored without localization or inside a localized parent.
`defaultValue`	`unknown` or `({ locale, req, user }) => value`	—	Value used when the field has no value. See default values.
`validate`	`Validate`	Built-in validator	Replaces the built-in validator. See validation. The built-in validator rejects invalid JSON and values that fail `jsonSchema`.
`hooks`	`{ beforeValidate, beforeChange, afterChange, afterRead, beforeDuplicate }`	—	Arrays of `FieldHook` functions for each phase. See field hooks.
`access`	`{ create, read, update }`	Allowed	`FieldAccess` functions for each operation. See field access control.
`hidden`	`boolean`	`false`	Removes the field from API responses and the admin panel while keeping stored data.
`saveToJWT`	`boolean \| string`	`false`	In an auth-enabled collection, copies the value into the user’s token. A string sets the token key. See token data.
`virtual`	`boolean \| string`	`false`	`true` skips database storage; a string reads a value through a relationship path. Virtual fields are read-only in the admin panel unless `admin.readOnly` is `false`. See virtual fields.
`disableDuplicate`	`boolean`	`false`	Leaves the value out when a document is duplicated, so the copy uses `defaultValue`.
`admin`	`object`	—	Admin-panel options. See Admin options.
`custom`	`Record<string, any>`	—	Server-only metadata for your own code and plugins. Use `admin.custom` for data the browser also needs.
`jsonSchema`	`Array<({ jsonSchema }) => JSONSchema4>`	—	Functions that modify the JSON Schema used by type generation.

Admin options

JSON fields support the standard field admin options, plus these options:

Option	Type	Default	Description
`editorOptions`	`EditorProps['options']`	—	Monaco editor options, such as `minimap` or `tabSize`.
`maxHeight`	`number`	—	Maximum editor height in pixels. The editor grows with its content up to this height.

For example, admin.editorOptions accepts Monaco editor options:

const preferencesField = {
  name: 'preferences',
  type: 'json',
  admin: {
    editorOptions: {
      minimap: { enabled: false },
      tabSize: 2,
    },
  },
} as const

JSON Schema validation

Provide a local schema to add completion hints and reject invalid values when a record is saved:

import type { CollectionConfig } from 'frogbot'

export const Customers: CollectionConfig = {
  slug: 'customers',
  fields: [
    {
      name: 'preferences',
      type: 'json',
      jsonSchema: {
        uri: 'app://schemas/preferences.json',
        fileMatch: ['app://schemas/preferences.json'],
        schema: {
          type: 'object',
          additionalProperties: false,
          properties: {
            colorScheme: {
              enum: ['light', 'dark', 'system'],
            },
          },
        },
      },
    },
  ],
}

A schema can also be loaded from a public URL by providing uri and fileMatch without an inline schema. Prefer an inline or imported schema when availability must not depend on a remote server.

Custom components

Override the field or its label through admin.components. Custom components can wrap FrogBot’s default JSON editor.

Field

Server component

import { JSONField } from '@frogbotai/ui/admin'
import type { JSONFieldServerProps } from 'frogbot'

export const CustomJSONFieldServer = ({
  clientField,
  path,
  permissions,
  schemaPath,
}: JSONFieldServerProps) => (
  <JSONField
    field={clientField}
    path={path}
    permissions={permissions}
    schemaPath={schemaPath}
  />
)

Client component

'use client'

import { JSONField } from '@frogbotai/ui/admin'
import type { JSONFieldClientProps } from 'frogbot'

export const CustomJSONFieldClient = (props: JSONFieldClientProps) => (
  <JSONField {...props} />
)

Label

Server component

import { FieldLabel } from '@frogbotai/ui/admin'
import type { JSONFieldLabelServerProps } from 'frogbot'

export const CustomJSONLabelServer = ({
  clientField,
  path,
}: JSONFieldLabelServerProps) => (
  <FieldLabel
    label={clientField.label || clientField.name}
    path={path}
    required={clientField.required}
  />
)

Client component

'use client'

import { FieldLabel } from '@frogbotai/ui/admin'
import type { JSONFieldLabelClientProps } from 'frogbot'

export const CustomJSONLabelClient = ({ field, path }: JSONFieldLabelClientProps) => (
  <FieldLabel label={field.label || field.name} path={path} required={field.required} />
)

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Config options

Admin options

JSON Schema validation

Custom components

Field

Server component

Client component

Label

Server component

Client component

​Config options

​Admin options

​JSON Schema validation

​Custom components

​Field

​Server component

​Client component

​Label

​Server component

​Client component

Config options

Admin options

JSON Schema validation

Custom components

Field

Server component

Client component

Label

Server component

Client component