Object Field

The Object Field component provides a JSON editor for storing and editing structured data objects. It validates JSON syntax and provides a textarea interface for complex data.

Basic Usage

With Schema

Nested Data

Read-Only

{
  "status": 200,
  "data": {
    "id": 123,
    "name": "Test"
  }
}

Field Schema

An object field is authored as ObjectFieldMetadata (@object-ui/types), which is the source of truth for the key set: it extends BaseFieldMetadata with one key, an optional schema describing the JSON the field accepts.

import type { ObjectFieldMetadata } from '@object-ui/types';

const settings: ObjectFieldMetadata = {
  type: 'object',
  name: 'settings',
  label: 'Settings',
  placeholder: '{ }',
  help: 'Stored as JSON.',
  schema: {
    theme: { type: 'string' },
    notifications: { type: 'boolean' },
  },
};

The value being edited, and the className / disabled a host supplies, are not metadata keys — they are runtime widget props. See Field Widget Props.

JSON Validation

The field validates JSON syntax in real-time:

• Valid JSON: Updates the value immediately
• Invalid JSON: Maintains current valid value, doesn't update
• Empty Input: Sets value to null

Data Format

The object field stores data as parsed JSON:

// Input (string)
'{"name": "John", "age": 30}'

// Stored (object)
{ name: "John", age: 30 }

// Display (formatted)
{
  "name": "John",
  "age": 30
}

Common Patterns

Configuration Objects

{
  type: 'object',
  name: 'api_config',
  label: 'API Configuration',
  value: {
    endpoint: 'https://api.example.com',
    timeout: 5000,
    retries: 3,
    headers: {
      'Content-Type': 'application/json'
    }
  }
}

Metadata

{
  type: 'object',
  name: 'custom_metadata',
  label: 'Custom Metadata',
  value: {
    tags: ['important', 'urgent'],
    priority: 'high',
    department: 'engineering'
  }
}

Preferences

{
  type: 'object',
  name: 'user_preferences',
  label: 'Preferences',
  value: {
    theme: 'dark',
    language: 'en',
    notifications: {
      email: true,
      push: false,
      sms: false
    }
  }
}

Cell Renderer

In tables/grids, an object value is rendered by the JSON cell renderer — getCellRenderer('object') resolves to this same component, shared with json, composite and record:

import { JsonCellRenderer } from '@object-ui/fields';

// <JsonCellRenderer value={specs} field={field} /> renders single-line JSON,
// truncated to the column width with the full text in the cell's `title`.
// A null or empty value renders an em-dash instead.

Schema Validation

For typed object fields, you can define a schema in two formats:

Simplified Format (for documentation):

{
  type: 'object',
  name: 'product_specs',
  label: 'Product Specifications',
  schema: {
    weight: 'number',
    dimensions: {
      width: 'number',
      height: 'number',
      depth: 'number'
    },
    materials: 'array'
  }
}

JSON Schema Format (for validation):

{
  type: 'object',
  name: 'product_specs',
  label: 'Product Specifications',
  schema: {
    type: 'object',
    properties: {
      weight: { type: 'number' },
      dimensions: {
        type: 'object',
        properties: {
          width: { type: 'number' },
          height: { type: 'number' },
          depth: { type: 'number' }
        }
      },
      materials: { type: 'array' }
    }
  }
}

Use Cases

• Configuration: Application settings, API configurations
• Metadata: Custom properties, tags, attributes
• API Responses: Storing API response data
• Preferences: User preferences, feature flags
• Structured Data: Any complex structured information
• JSON Storage: Raw JSON data storage

Best Practices

1. Use for Flexible Data: When schema changes frequently
2. Validate on Backend: Always validate structure server-side
3. Consider Alternatives: Use typed fields when structure is fixed
4. Document Schema: Provide clear documentation for expected structure
5. Size Limits: Set reasonable size limits for JSON data

Backend Validation

ObjectUI does not enforce schema. ObjectField checks JSON syntax only — it accepts any value JSON.parse accepts, and simply declines to propagate a draft it cannot parse — so nothing on the client rejects a well-formed object whose shape is wrong. Structural validation belongs on the server.

The schema you author is carried on the field metadata untouched, and in the JSON Schema Format above it is an ordinary JSON Schema document. That is the whole integration point: the server validates the incoming value against the very same object, using whichever JSON Schema validator it already has (Ajv, for instance — ObjectUI ships none and names none).

import type { ObjectFieldMetadata } from '@object-ui/types';

const apiConfig: ObjectFieldMetadata = {
  type: 'object',
  name: 'api_config',
  label: 'API Configuration',
  schema: {
    type: 'object',
    properties: {
      api_key: { type: 'string', minLength: 1 },
      timeout: { type: 'number', minimum: 0 },
      enabled: { type: 'boolean' },
    },
    required: ['api_key'],
  },
};

One caveat when you do: the Simplified Format above is documentation for a reader, not a validator input — only the JSON Schema Format can be handed to a JSON Schema validator as-is.