Info: This article is work in progress and subject to change.
Two related but distinct mechanisms control what must be filled in and what counts as a valid value: required rules (driven by Lucene) decide whether a Field must hold a value before publish; regex patterns (driven by regular expressions) decide what users can type and what counts as a valid final value.
This article covers both, the messages that go with them, and the patterns and pitfalls of writing each. Read 02d — How conditions work first if Lucene and regex are unfamiliar.
Required versus Required condition
Like the disable mechanism, “required” has two slots:
| Setting | Behaviour | Use when |
|---|---|---|
| Required | When on, the field must hold a value before publish, regardless of any condition | The field is always mandatory |
| Required condition | A Lucene query against the selected asset’s metadata. When true, the field is required | The field is mandatory only in some states — for example, only when the asset is moving to Final review |
If both are set, Required wins. The condition is consulted only if Required is off.
Always pair the requirement with a Required message — the text the user sees when the field is empty and the requirement fires.
How required is enforced
A required field that is empty does not block the user from typing in other fields, navigating around the panel, or selecting other assets. It blocks at the point of save / publish: the Workflow Assistant raises the Required message and refuses to write the change until the field is filled.
Note: This non-blocking-during-edit behaviour is deliberate — it lets users work in the order that suits them and only enforces requirements at the final step. The trade-off is that the user does not know the field is required until they try to publish. Mitigate by always pairing the requirement with a Notification (display condition: credit:"" or similar) so the user is told what is missing while they work.
Required-message patterns
| Bad | Good |
|---|---|
Required field |
Add a credit before publishing — it appears below the image when this asset is used |
Cannot be empty |
Pick a status before saving — choose Draft, Review, or Final |
Field required |
Set a publish date before moving to Final review |
A useful template is <verb> a <thing> before <action> — <reason>. The user knows what to do, what for, and why.
Patterns and Required conditions
Three patterns recur:
Always required
| Setting | Value |
|---|---|
| Required | On |
| Required message | Title is required — every asset needs a title. |
Required only when moving to Final
| Setting | Value |
|---|---|
| Required condition | status:"Awaiting publish" |
| Required message | A credit is required before publishing. |
Required only for specific kinds
Required conditions can express asset-kind logic if you prefer Lucene over the visibility checklist for a particular case:
| Setting | Value |
|---|---|
| Required condition | assetDomain:image AND status:"Final" |
| Required message | Final images need a credit and a usageRights value. |
Tip: Reach for the visibility checklist for kind-only logic and Lucene for value-driven logic. Mixing the two in a Required condition is sometimes the right call, but only when the rule is genuinely cross-cutting.
Regex: keep pattern versus pattern
Regex sits on Field types that hold typed values — Text, Rich text, Number, Decimal, and a few others. The Configurator gives you two regex slots:
| Slot | Behaviour | Use for |
|---|---|---|
| Keep pattern | Filters what the user can type. Anything that does not match the regex is dropped silently | Constraining the input alphabet — only digits, only letters, only uppercase |
| Pattern | Validates the final value. The Configurator shows a Pattern message if the value does not match | Shape-checking the result — three letters and four digits, exactly 13 digits, a valid ISO date |
The two work together. Use Keep pattern to make the user’s typing safer; use Pattern to validate the shape of the final result.
Note: A common mistake is to use only Pattern, with no Keep pattern. This works but produces a worse experience: the user types freely, then sees a validation error after the fact. With the right Keep pattern, many invalid characters never appear at all, and the user sees the error message only for the harder-to-prevent shape mistakes.
Pattern-message patterns
A pattern with no message frustrates the user. Always pair them.
| Bad | Good |
|---|---|
Invalid |
ISBN must be 13 digits with no spaces or dashes |
Pattern mismatch |
Project code must be three uppercase letters followed by four digits, e.g. PRJ1234 |
Format error |
Phone number must be in international format, starting with + |
The template is the same as for required messages: tell the user what is wrong and what shape the value should take.
Common regex examples
Use these as starting points and adjust for your own field shapes.
Numeric input
| Slot | Regex | Effect |
|---|---|---|
| Keep pattern | [0-9] |
Only digits can be typed |
| Pattern | [0-9]{13} |
The final value must be exactly 13 digits |
| Pattern message | ISBN must be exactly 13 digits. |
Alphanumeric code
| Slot | Regex | Effect |
|---|---|---|
| Keep pattern | [A-Z0-9] |
Only uppercase letters and digits can be typed |
| Pattern | [A-Z]{3}[0-9]{4} |
Three letters followed by four digits |
| Pattern message | Project code must be three uppercase letters followed by four digits, e.g. PRJ1234. |
Restricted text (letters and spaces)
| Slot | Regex | Effect |
|---|---|---|
| Keep pattern | [A-Za-z ] |
Only letters and spaces |
| Pattern | [A-Za-z]{3,50}( [A-Za-z]{3,50})* |
Three to fifty letters per word, single spaces between words |
| Pattern message | Use only letters and single spaces. Each word must be three to fifty letters. |
Decimal price (default keep pattern is fine)
| Slot | Regex | Effect |
|---|---|---|
| Pattern | [0-9]+\.[0-9]{2} |
An integer part, a decimal point, and exactly two decimal places |
| Pattern message | Price must include two decimal places, e.g. 12.50. |
Note: Decimal and Number fields ship with a default Keep pattern that already restricts input to numeric characters. You usually do not need to set Keep pattern on those types — only Pattern. Use Keep pattern only when the default’s permissiveness is wrong for your case.
Diagnostic: why is my validation behaving unexpectedly?
| Symptom | Likely cause | Fix |
|---|---|---|
| The user can publish even though the field is empty | The field is not actually required, or the Required condition is never true | Re-check Required and the Required-condition Lucene query. Verify in Assets that the condition’s metadata fields exist |
| The user types something and nothing appears | The Keep pattern is too narrow | Re-check the Keep pattern — typically a missing ] or an over-restrictive character class |
| The field shows a Pattern error for valid-looking values | The Pattern regex does not match what you intended | Re-test the regex in a tool that shows live matches. Common cause: forgotten anchors (^…$) or escaping |
| The user reports a Required field that is not visible | The required field is hidden by the visibility checklist | Visibility hides the field but does not waive the requirement. Either remove the requirement or include the field in the kinds the panel supports |
Cross-references
- 02d — How conditions work — Lucene primer for Required condition; regex primer for Keep and Pattern
- 05a — Fields reference — every Field’s required and pattern options
- 05c — Notifications reference — the companion mechanism for surfacing required-field state to users
- 06b — Disabling components and writing disable conditions — the value-driven equivalent that disables rather than requires
- 12a — Lucene query quick reference
- 12b — Regex quick reference for field validation
Revisions
- 8 May 2026: First publication of the manual
Comments
0 comments