JSON field

Store any serialized JSON value with size validation

The json field stores any valid JSON value including objects, arrays, strings, numbers, booleans, and null. It validates JSON syntax and enforces size constraints.

Configuration options

maxSize · int64 · default: "1048576"

Maximum size of the JSON value in bytes (up to 2^53-1). Defaults to 1MB if not set or zero.

required · bool · default: "false"

When true, requires the field value to be non-empty JSON (not null, empty string, empty array, or empty object).

Validation rules

The json field validates:

• JSON syntax: Value must be valid JSON
• Size: JSON string size must not exceed maxSize bytes
• Required: If enabled, value cannot be null, "", [], or {}

Value normalization

When submitting plain string values (e.g., from multipart/form-data), the following normalization rules apply:

• "true" → true
• "false" → false
• "null" → null
• Numeric strings → JSON numbers
• Valid JSON strings starting with [, {, or " → parsed as JSON
• Other strings → double-quoted JSON strings
• Empty string → ""

This normalization allows the field to work seamlessly with both JSON and multipart/form-data request formats.

Go examples

Basic usage

import "github.com/pocketbase/pocketbase/core"

field := &core.JSONField{
    Name:     "metadata",
    Required: false,
}

collection.Fields.Add(field)

// Set JSON value
record.Set("metadata", map[string]any{
    "color": "blue",
    "size":  "large",
    "tags":  []string{"featured", "new"},
})

With size limit

field := &core.JSONField{
    Name:     "config",
    Required: true,
    MaxSize:  512 * 1024, // 512KB
}

collection.Fields.Add(field)

record.Set("config", map[string]any{
    "theme": "dark",
    "notifications": map[string]bool{
        "email": true,
        "push":  false,
    },
})

Array values

field := &core.JSONField{
    Name:     "items",
    Required: false,
}

collection.Fields.Add(field)

// Store array
record.Set("items", []map[string]any{
    {"id": 1, "name": "Item 1"},
    {"id": 2, "name": "Item 2"},
})

Complex nested data

field := &core.JSONField{
    Name:     "settings",
    Required: true,
    MaxSize:  2 << 20, // 2MB
}

collection.Fields.Add(field)

record.Set("settings", map[string]any{
    "user": map[string]any{
        "preferences": map[string]any{
            "theme":    "dark",
            "language": "en",
        },
        "privacy": map[string]bool{
            "showEmail":   false,
            "showProfile": true,
        },
    },
    "notifications": []string{"email", "push"},
})

Database column type

JSON DEFAULT NULL

Working with JSON values

Setting values

import "github.com/pocketbase/pocketbase/tools/types"

// From map
record.Set("data", map[string]any{
    "key": "value",
})

// From slice
record.Set("data", []string{"a", "b", "c"})

// From JSON string
jsonStr := `{"name":"John","age":30}`
record.Set("data", jsonStr)

// From types.JSONRaw
raw := types.JSONRaw(`{"key":"value"}`)
record.Set("data", raw)

Common use cases

User preferences

field := &core.JSONField{
    Name:    "preferences",
    MaxSize: 10 * 1024, // 10KB
}

record.Set("preferences", map[string]any{
    "theme":        "dark",
    "language":     "en",
    "notifications": true,
})

Querying JSON fields

You can query JSON fields using JSONPath-like syntax:

Simple queries

// Find records where JSON field contains a specific value
records, err := app.FindRecordsByFilter(
    "items",
    "metadata.category = 'tech'",
    "-created",
    10,
    0,
)

Best practices

• Set appropriate maxSize to prevent database bloat and performance issues
• Use structured field types (text, number, etc.) when possible for better queryability
• JSON fields are great for flexible, schemaless data that varies by record
• Consider indexing frequently queried JSON properties
• Validate JSON structure in your application layer for complex schemas
• Be mindful that JSON fields consume more storage than primitive types

Empty vs null

When required: true, these values are considered empty and will fail validation:

• null
• ""
• []
• {}

Zero value

The zero value for json fields is a zero types.JSONRaw.