Pre-release — content may change.

GuidesCustom Fields

Resources & Overrides

Control where sections appear and adjust their UI per context

A JSON Schema Resource attaches a section of Additional Info to an entity and controls where it appears. UI Schema Overrides layer context-specific display changes on top of a section's UI Schema — without changing the underlying schema or the data it stores.

Resources

A resource binds a schema to a place in Wicket. Its key fields are:

FieldPurpose
EntityThe record the section attaches to — Person, Organization, Order, a Connection type, Group, or Group Member.
ContextWhere the section is viewed. Leave blank for the entity's profile, SubmissionPreview for the onboarding flow, or Widget to embed in a website.
WeightSort order relative to other sections — 0 first, then 1, etc.
UI Schema OverridesContext-specific display changes (see below).
ScopesFurther narrows when a section shows — e.g. by order type or membership.

The entity and context of a resource cannot be changed after it is created. Add a new resource if you need a different combination.

A single schema can have multiple resources — for example, one for the admin profile and one for a website Widget — each with its own overrides. This is the recommended way to show the same data differently in different places.

UI Schema Overrides

UI Schema Overrides change how a field appears in a specific resource — for example to hide a field from the onboarding flow (SubmissionPreview) or from a website (Widget), or to make a field read-only on the website while keeping it editable in the admin.

Overrides use react-jsonschema-form (uiSchema) syntax, which differs slightly from JSON Schema. For example, a field made read-only in the Schema with "readOnly": true is instead expressed as "ui:readonly": true in a UI Schema Override.

Planning tip: On widgets you cannot re-order fields, and hidden fields are hidden for all web users regardless of role. As a rule of thumb, keep admin-only fields in their own schema rather than mixing them with fields that will be web-visible — this minimizes reworks. Fields you hide should not be marked required in the schema.

Hide a field

To hide a field in a given context, add a resource for that context (e.g. Widget) and set the field's widget to hidden:

{
  "fieldToHide": {
    "ui:widget": "hidden"
  }
}

Change a label per context

Display a different label in one context (e.g. the Widget) than in the admin:

{
  "fieldOne": {
    "ui:i18n": {
      "label": { "en": "Field 1 (Override Name)" }
    }
  }
}

The same works for nested fields — for example inside a conditional oneOf or a repeater's items:

{
  "licenserepeat": {
    "items": {
      "statelicense": {
        "ui:i18n": {
          "label": { "en": "In which state are you licensed?" }
        }
      }
    }
  }
}

Read-only field, section, or schema

Make a single field read-only:

{
  "fieldname": {
    "ui:readonly": true
  }
}

Make an entire schema read-only:

{
  "ui:readonly": true
}

Disable specific enum values

Disable selected enum options in a context, on a per-enum basis (arevet is the field, novalue an option to disable — list more than one if needed):

{
  "arevet": {
    "ui:enumDisabled": ["novalue"]
  }
}

Lock down a repeater

Hide a field inside a repeater and remove the add/remove/move buttons — useful for making a repeater read-only on a Widget:

{
  "credentials_repeat": {
    "ui:options": {
      "addable": false,
      "removable": false,
      "orderable": false
    },
    "items": {
      "documented_proof": {
        "ui:widget": "hidden"
      }
    }
  }
}

Required-field behaviour cannot be changed at the UI level — you cannot make a field required in the Widget but optional in the admin. Required fields must be set at the schema level instead.

Sections and websites (Widgets)

Wicket widgets can web-expose fields from person and organization profiles, as well as Additional Info schemas. The Additional Info widget can specify which sections (accordions) to output when multiple schemas exist.

On widgets you cannot move fields, and any field you hide is hidden for all web users regardless of role or context — the ordering follows what is shown in the Wicket admin. Build schemas with this in mind, keeping admin-only fields separate from web-visible ones.

Changing existing sections

Because a schema and its saved data change independently, a schema change can invalidate existing data. Common change requests — adding a field, updating an enum list, re-ordering, making a field required, or removing a field — should be handled with care.

Confirm no data will be invalidated

Before making a change, query the client's existing production data to confirm nothing will be invalidated. If nothing is affected, implement the change directly.

Make backwards-compatible changes

Shape the change so existing data remains valid. For example, to "remove" a property without invalidating records that still contain it, drop the property from properties but set additionalProperties to true:

{
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "property1": { "type": "string" }
  }
}

Data that still contains property2 will continue to validate.

Migrate the data

When a breaking change is unavoidable, update the schema and write a script to migrate existing data into the new format — usually with the client defining a mapping between old and new values.

On this page