Field Types
Every field type and pattern used to build Additional Info schemas
When adding a property to a schema you choose the type of data it holds. Each property is defined in the Schema (structure and validation) and, optionally, labelled and customized in the UI Schema (display).
This page covers the field types and patterns commonly used in Wicket. For copy-paste recipes, see Examples.
Throughout these examples the UI Schema uses ui:i18n to provide English (en) and French (fr) labels. Wicket renders forms with react-jsonschema-form, so the UI Schema follows its conventions.
String
The most commonly used type. It holds any text-based data.
"name": {
"type": "string"
}"name": {
"ui:i18n": {
"label": {
"en": "Name",
"fr": "Nom"
}
}
}Add a textarea widget for multi-line input:
"name": {
"ui:widget": "textarea",
"ui:i18n": {
"label": { "en": "Name", "fr": "Nom" }
}
}String formats
Strings can carry a format for richer validation:
| Use case | format |
|---|---|
| Date | date |
email | |
| URL | hostname |
"date": {
"type": "string",
"format": "date"
}"email": {
"type": "string",
"format": "email"
}"url": {
"type": "string",
"format": "hostname"
}Regex strings
Add pattern to validate a string against a regular expression — useful for phone numbers, for example:
"phoneNumber": {
"type": "string",
"pattern": "^\\s*(?:\\+?(\\d{1,3}))?[-. (]*(\\d{3})[-. )]*(\\d{3})[-. ]*(\\d{4})(?: *x(\\d+))?\\s*$"
}Integer
Holds whole numbers. Does not accept decimals.
"integer": {
"type": "integer"
}Number
Holds numbers, including decimals.
"number": {
"type": "number"
}Boolean
Holds a true/false value. The default widget is a single checkbox.
"boolean": {
"type": "boolean"
}Use a Yes/No radio group instead:
"boolean": {
"ui:widget": "radio",
"ui:i18n": {
"label": { "en": "Yes or No?", "fr": "Oui ou non?" }
}
}Enum
Enums limit a string, integer, or number to a fixed set of accepted values. They render as a drop-down.
When defining enums, keep these conventions in mind:
- Parameterize values with dashes — store
Test Enum Valueastest-enum-value. - Order matters — values display in the order defined (usually ordered by their English translation).
- Provide translations for the values in the UI Schema via
enumNames.
"enum": {
"type": "string",
"enum": ["first", "second", "third"]
}"enum": {
"ui:i18n": {
"label": { "en": "Enum", "fr": "Enum" },
"enumNames": {
"en": ["First", "Second", "Third"],
"fr": ["Premier", "Deuxième", "Troisième"]
}
}
}Avoid special characters such as /, ', (), or & in enum values — use snake_case. Removing an enum option after data exists will invalidate any records using that value.
Arrays
Arrays serve two main purposes in Wicket.
Checkbox lists
Store a list of strings rendered as checkboxes:
"array": {
"type": "array",
"uniqueItems": true,
"items": {
"type": "string",
"enum": ["first", "second", "third"]
}
}"array": {
"ui:widget": "checkboxes",
"ui:i18n": {
"label": { "en": "Array", "fr": "Array" },
"enumNames": {
"en": ["First", "Second", "Third"],
"fr": ["Premier", "Deuxième", "Troisième"]
}
}
}Repeaters
Repeat a group of fields by defining an array of object properties. These are often called "repeaters."
"array": {
"type": "array",
"items": {
"type": "object",
"properties": {
"firstField": { "type": "string" },
"secondField": { "type": "string" }
}
}
}"array": {
"ui:i18n": {
"description": {
"en": "Please enter your information below.",
"fr": "SVP entrer votre information ci-dessous."
}
},
"items": {
"firstField": {
"ui:i18n": { "description": { "en": "First", "fr": "Premier" } }
},
"secondField": {
"ui:i18n": { "description": { "en": "Second", "fr": "Deuxième" } }
}
}
}When mixing a repeater with other fields, make the repeater last in the UI order so users can fill out the single fields without scrolling past repeater entries first.
Conditional fields
Using more advanced JSON Schema features, you can show a field only when another field has a specific value. This works with boolean or string fields, and is most commonly used with booleans.
The example below shows a conditional text field only when optIn is true:
{
"type": "object",
"oneOf": [
{
"properties": {
"optIn": { "type": "boolean", "enum": [true] },
"conditional": { "type": "string" }
},
"required": ["optIn", "conditional"],
"additionalProperties": false
},
{
"properties": {
"optIn": { "type": "boolean", "enum": [false] }
},
"required": ["optIn"],
"additionalProperties": false
}
]
}{
"ui:field": "ObjectOneOfEnumField",
"ui:options": {
"enumField": "optIn",
"enumFieldOptions": [true, false],
"enumFieldType": "boolean"
},
"ui:i18n": {
"enumFieldOptionsNames": {
"en": ["Yes", "No"],
"fr": ["Oui", "Non"]
}
},
"optIn": {
"ui:widget": "radio",
"ui:options": { "inline": true },
"ui:i18n": {
"label": {
"en": "Should we show the conditional field?",
"fr": "Est-ce qu'on devrait voir le champ optionnel?"
}
}
},
"oneOf": [
{ "ui:order": ["conditional"] },
{}
],
"conditional": {
"ui:i18n": {
"label": { "en": "Conditional Field", "fr": "Champ optionnel" }
}
}
}The oneOf array in the UI Schema must have the same number of objects as the oneOf array in the Schema.
References to Wicket resources
You can populate enum lists from live Wicket data using a $ref that starts with wicket://schemas/. This is resolved by Wicket's dereferencer at request time.
Organizations
The enum value is the organization's UUID and the label is its legal name. You can pass Ransack filters to limit which organizations are returned — the example below returns organizations with an Education type and the mep tag:
"organization": {
"type": "string",
"$ref": "wicket://schemas/organizations?type_eq=education&tags=mep"
}Referencing organizations is only supported for organizations — not for people.
Resource types
The enum value is the resource type's slug and the label is its name. Here phone_types is the slug of the Wicket entity type that holds the desired resource types:
"resourceType": {
"type": "string",
"$ref": "wicket://schemas/resource_types/phone_types"
}Default values
You can set a default value in the schema:
"default": {
"type": "string",
"default": "Default Value"
}A default value only applies when a Data Field is saved (i.e. when the user clicks Save in the form). There is currently no way to apply a default when a Person or Organization is first created.
Required fields
Mark fields as required using the required keyword in the root of an object, with an array of field names:
{
"type": "object",
"properties": {
"requiredField": { "type": "string" },
"nonRequiredField": { "type": "string" }
},
"required": ["requiredField"]
}If your schema contains nested objects, you can define required properties for each nested object.
Ordering fields
Add a ui:order key in the UI Schema with the field names in the order you want them to appear:
{
"type": "object",
"properties": {
"secondField": { "type": "string" },
"firstField": { "type": "string" }
}
}{
"ui:order": ["firstField", "secondField"],
"ui:i18n": {
"title": {
"en": "Additional Info Section",
"fr": "Section d'information supplémentaire"
}
}
}If your schema contains nested objects, you can define the order of properties for each nested object.