Pre-release — content may change.

GuidesCustom Fields

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:

PartWhat it does
JSON SchemaDescribes the structure, types, and validation rules for the data you want to capture.
UI SchemaDescribes how the fields are displayed in the form — titles, labels, field order, and translations.
JSON Schema ResourceDetermines when and where a section is shown in Wicket, and can apply context-specific UI behaviour.
Data FieldA 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:

  1. A Data Field is created when a user clicks Save in a section of Additional Info.
  2. 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, store Test Enum Value as test-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

Useful references

On this page