Overview
Capture tenant-specific data that doesn't fit Wicket's standard fields
Custom Fields — referred to as Additional Info in the Wicket admin — let you capture client-specific information that cannot be stored in Wicket's standard fields. Additional Info is stored against a person or an organization record.
For example, a person's name and email are stored in Wicket's standard fields. But there is no standard field for a person's education history — that's where Custom Fields come in.
Each section of Additional Info is defined using JSON Schema, which describes the structure of the data, validates it, and drives the form used to enter it.
What makes up a section
A section of Additional Info is made up of four parts:
| Part | What it does |
|---|---|
| JSON Schema | Describes the structure, types, and validation rules for the data you want to capture. |
| UI Schema | Describes how the fields are displayed in the form — titles, labels, field order, and translations. |
| JSON Schema Resource | Determines when and where a section is shown in Wicket, and can apply context-specific UI behaviour. |
| Data Field | A Wicket record that stores the data a user enters, linked to the person or organization it belongs to. |
JSON Schema
A JSON object that follows the JSON Schema spec. It is responsible for:
- Describing the structure of the data you want to capture
- Describing the type of data you want to capture
- Defining rules and validations
- Validating data against those rules
UI Schema
A JSON object that describes how to display the fields from your JSON Schema in a form. In Wicket this typically defines:
- The title for the section
- The label for each field
- The order in which fields appear
- The labels shown in drop-downs
Wicket uses react-jsonschema-form to render these forms, so the UI Schema follows its conventions.
Data Field
A Wicket record that stores the data a user enters in a section, linked to the person or organization it belongs to. Two things are important to keep in mind:
- A Data Field is created when a user clicks Save in a section of Additional Info.
- Data Field and JSON Schema records change independently from one another — changing a schema can invalidate data already saved against it. See Avoiding errors below.
JSON Schema Resource
A Wicket record that determines when and where an entire section is shown in the Wicket UI (a person profile, an organization profile, the onboarding flow, a website widget, etc.). It can also apply context-specific UI behaviour through UI Schema Overrides.
Who can access schemas
Editing Additional Info schemas is restricted to logged-in users with administrative rights.
How the pieces fit together
Avoiding errors
Because the schema and the data saved against it change independently, a schema change can invalidate data that already exists.
Enum naming: When building enums inside the
Schema, avoid special characters such as/,',(), or&. Use snake_case (a-or_in place of spaces and special characters). For example, storeTest Enum Valueastest-enum-value.
Removing enum options: If you remove an option from an enum and Data Fields already exist with that value, those records can no longer be saved — the value is now invalid and the user has no way to clear it from the UI.
See Changing existing sections for safe ways to evolve a schema.
Next steps
Creating a Section
Step-by-step walkthrough in the Wicket admin
Field Types
Strings, dates, enums, repeaters, conditionals, and more
Resources & Overrides
Control where sections appear and override the UI per context
Updating Data via the API
Read and write Additional Info data (data_fields) safely
Examples
A cookbook of common field patterns
Useful references
- Understanding JSON Schema
- Getting started step-by-step (JSON Schema)
- react-jsonschema-form — UI Schema reference
- JSON:API naming recommendations — field and object names use
camelCase; enum slugs usesnake_case