Orbeon Forms
  • Getting started
  • Installation
    • Logging
    • Configuration banner
    • Docker
    • Azure
    • Tomcat
    • WildFly
    • WebSphere
    • WebLogic
    • GlassFish
    • Caches
    • Replication
    • Upgrading
  • Configuration
    • Properties
      • General
        • HTTP client
      • Form Runner
        • Detail page
          • Attachments
          • Email properties
          • PDF
          • Table of contents
        • Persistence
        • Summary page
      • Form Builder
      • XForms
    • Advanced
      • Workflows
      • Session management
      • State handling
      • Client-side error handling
      • Clustering and High Availability
      • Configuring a Form Runner eXist database
      • Creating a production WAR
      • Environments
      • JavaScript and CSS assets
      • Limiter filter
      • Run modes
      • Security
        • Content-Security-Policy header
      • SAP Hybris Module
      • XForms logging
    • Troubleshooting
      • Troubleshooting with the orbeon.log
      • Memory and threads
      • Relational database logging
      • Misc
  • Form Builder
    • Form settings
      • Time window
    • Form editor
      • Form area
      • Toolbox
      • Buttons bar
      • Control settings
      • Dependent fields and sections
      • Validation
      • Choices editor
      • Publishing
      • Cut, copy and paste
      • Section and grid settings
      • Section settings
      • Grid settings
      • Quick control search
      • Repeat settings
      • Repeated grids
      • Undo and redo
      • Keyboard shortcuts
    • Formulas
      • Examples of formulas
      • Formulas inspector
      • Formulas console
    • Summary page
    • Form localization
    • Advanced
      • Edit source
      • Services and actions
        • HTTP services
        • Database services
        • Simple Actions
        • Action Syntax
        • Action Syntax examples
        • Synchronizing repeated content
      • Testing a form in web mode
      • Testing PDF production
      • Testing offline functionality
      • Email Settings dialog
      • Field-level encryption
      • Messages
      • Section templates
      • Template syntax
      • XML Schemas support
      • Extensibility
        • Extension API
        • Integration
        • Toolbox component metadata
  • Form Runner
    • Overview
      • Terminology
    • Pages
      • Landing page
      • Published Forms page
      • Forms Admin page
      • Summary page
    • Components
      • Alert dialog
      • Attachment
      • Autocomplete
      • Captcha
      • Character counter
      • Checkbox input
      • Currency
      • Date
      • Dropdown date
      • Static and dynamic dropdown
      • Error summary
      • Grid
      • Handwritten signature
      • Hidden field
      • Image
      • Image annotation
      • Image attachment
      • Number
      • Open selection
      • Repeater
      • Formatted Text / Rich Text Editor
      • Section
      • Single-selection tree
      • Source code editor
      • Time
      • US phone
      • US state
      • Video
      • Video attachment
      • Wizard
      • XForms inspector
      • Yes/No answer
    • Features
      • Automatic calculations dependencies
      • Datasets
      • Excel and XML import
      • Excel and XML export
      • Summary page Excel Export
      • Form definitions and form data Zip Export
      • Purging historical data
      • Lease
      • Localization
      • Supported languages
      • Mobile support
      • Multitenancy
      • Form Runner navigation bar
      • PDF production
        • Automatic PDF
        • Automatic PDF header and footer configuration
        • PDF templates
      • Responsive design
      • Revision history
      • S3 storage
      • Simple data migration
      • TIFF production
      • Versioning
      • Wizard view
      • Workflow stage
    • Persistence
      • Using a relational database
      • Relational database schema
      • Purging old data using SQL
      • Auditing
      • Autosave
      • Database support
      • Flat view
    • Linking and embedding
      • Linking
      • Java Embedding API
      • JavaScript Embedding API
      • Liferay full portlet
      • Liferay proxy portlet
      • Securing Form Runner access
      • Form Runner offline embedding API
      • Angular component
      • React component
    • Access control and permissions
      • Users
      • Login & Logout
      • Deployed forms
      • Form fields
      • Editing forms
      • Owner and group member
      • Organizations
      • Scenarios
      • Token-based permissions
    • Styling
      • CSS
      • Grids CSS
      • Automatic PDF styling and CSS
    • APIs
      • Authentication of server-side service APIs
      • Persistence API
        • CRUD API
        • Search API
        • List form data attachments API
        • Form Metadata API
        • Lease API
        • Reindexing API
        • Caching
        • Versioning
        • Revision History API
        • Zip Export API
        • Custom persistence providers
      • Other APIs
        • Connection context API
        • Duplicate form data API
        • File scan API
        • Form Runner JavaScript API
        • Generate XML Schema API
        • PDF API
        • Publish form definition API
        • Run form in the background API
      • Data formats
        • Form data
        • Date and time
        • Form definition
    • Architecture and integration
      • Architecture
      • Access form data
      • Integration
    • Advanced
      • Buttons and processes
        • Simple process syntax
        • Core actions
        • Form Runner actions
          • Save action
          • Send action
          • Email action
        • XForms actions
        • Predefined buttons, processes and dialogs
        • Summary page buttons and processes
      • Custom dialogs/model logic
      • Services
      • Singleton form
      • Monitoring HTTP requests
  • XForms
    • Core
      • Attribute Value Templates (AVTs)
      • Binds
      • Validation
      • Variables
      • Keyboard focus
      • XForms JavaScript API
      • Error handling
        • Detailed behavior
      • Model-Bind variables
      • XForms 2.0 support
    • Events
      • Standard support
      • UI refresh events
      • Keyboard events
      • Extension events
      • Extension context information
      • Other event extensions
    • Actions
      • Repeat, insert and delete
      • Scripting actions
      • Extensions
    • Controls
      • Label, hint, help
      • Input
      • Output
      • Text area
      • Button
      • Upload
      • Dialog
    • Submission
      • Standard support
      • JSON support
      • Asynchronous submissions
      • Caching extension
      • Other submission extensions
    • XPath
      • Type annotations
      • Expression analysis
      • Tips
      • Compatibility
      • Standard functions
      • Maps and arrays Functions
      • Extension functions
        • Core functions
        • Utility functions
        • Model functions
        • Controls functions
        • XML functions
        • JSON functions
        • HTTP functions
        • Form Runner functions
        • Other functions
        • Deprecated functions
    • XBL components
      • FAQ
      • Guide
        • XBL Tutorial
        • Bindings
        • XForms models
        • Including content
        • Event handling
        • Conventions
        • Map XBL example
        • Learning from existing components
      • Advanced topics
        • XBL Modes
        • JavaScript companion classes
        • XBL library
        • Extensions
        • Attachment controls
    • XForms tutorial
      • Introduction
      • Installation
      • The Hello application
      • The Bookcast application
        • The basic app
        • Database access
        • Polishing the app
        • Adding a feed
    • Using XForms from Java apps
  • XML Platform
    • Page Flow Controller
      • Basics
      • XML submission
      • Navigating between pages
      • Paths and matchers
      • Other configuration elements
      • Typical combinations of page model and page view
      • Examples
      • Authorizing pages and services
    • Processors
      • URL generator
      • Request generator
      • PDF to image converter
    • Resources
      • Resource managers
      • Setting up an external resources directory
    • Other
      • Binary and text documents
  • FAQ
    • Licensing
    • PE and Dev Support
    • Form Builder and Form Runner
    • Resources and support
    • Other technical questions
  • Contributors
    • Automated tests
    • Building Orbeon Forms
    • Localizing Orbeon Forms
    • Validation functions
    • Contributor License Agreement
  • Release notes
    • Orbeon Forms 2022.1.9
    • Orbeon Forms 2024.1.1
    • Orbeon Forms 2023.1.7
    • Orbeon Forms 2024.1
    • Orbeon Forms 2023.1.6
    • Orbeon Forms 2023.1.5
    • Orbeon Forms 2021.1.11
    • Orbeon Forms 2022.1.8
    • Orbeon Forms 2023.1.4
    • Orbeon Forms 2023.1.3
    • Orbeon Forms 2023.1.2
    • Orbeon Forms 2022.1.7
    • Orbeon Forms 2023.1.1
    • Orbeon Forms 2023.1
    • Orbeon Forms 2022.1.6
    • Orbeon Forms 2021.1.10
    • Orbeon Forms 2022.1.5
    • Orbeon Forms 2021.1.9
    • Orbeon Forms 2022.1.4
    • Orbeon Forms 2022.1.3
    • Orbeon Forms 2021.1.8
    • Orbeon Forms 2022.1.2
    • Orbeon Forms 2022.1.1
    • Orbeon Forms 2022.1
    • Orbeon Forms 2021.1.7
    • Orbeon Forms 2021.1.6
    • Orbeon Forms 2021.1.5
    • Orbeon Forms 2021.1.4
    • Orbeon Forms 2021.1.3
    • Orbeon Forms 2021.1.2
    • Orbeon Forms 2021.1.1
    • Orbeon Forms 2021.1
    • Orbeon Forms 2020.1.6
    • Orbeon Forms 2019.2.4
    • Orbeon Forms 2019.1.2
    • Orbeon Forms 2018.2.5
    • Orbeon Forms 2018.1.4
    • Orbeon Forms 2020.1.5
    • Orbeon Forms 2020.1.4
    • Orbeon Forms 2020.1.3
    • Orbeon Forms 2020.1.2
    • Orbeon Forms 2019.2.3
    • Orbeon Forms 2020.1.1
    • Orbeon Forms 2020.1
    • Orbeon Forms 2019.2.2
    • Orbeon Forms 2019.2.1
    • Orbeon Forms 2019.1.1
    • Orbeon Forms 2019.2
    • Orbeon Forms 2019.1
    • Orbeon Forms 2018.2.4
  • Release history
  • Use cases
  • Product roadmap
  • Index of features
Powered by GitBook
On this page
  • Introduction
  • Validation constructs
  • Validation order
  • Extensions
  • Multiple constraints and alerts
  • Validation levels
  • Nested validation elements
  • Multiple alerts
  • Validation mode
  • xxforms-valid and xxforms-invalid events
  • xxforms-constraints-changed event
  • xxf:valid() and xxf:invalid() XPath functions
  • xxf:xml type
  • xxf:xpath2 type
  • xxf:XPath2ValueTemplate type
  • Controlling the XML Schema validation mode
  • XML Schema validation
  • Validation and submission
  • Validation and controls
  1. XForms
  2. Core

Validation

PreviousBindsNextVariables

Last updated 4 years ago

See also .

Introduction

Orbeon Forms validates XForms instances following XForms 1.1 and adds some extensions to facilitate validation.

Validation constructs

There are two main methods for validating data in XForms:

  • with an imported XML Schema

  • with xf:bind

Using a bind allows you to create precise error messages to the user based on the type of data entry error.

Validation order

Orbeon Forms performs validation of a node in the following order:

  • data type validation

    • XML Schema validation (lax/strict/none on model instances)

    • xf:bind/@type

    • xf:type

  • required validation

    • required-but-empty

    • xf:bind/@required

    • xf:required/@value

  • constraints

    • xf:bind/@constraint

    • xf:constraint/@value

    • are checked only if the control's data type is valid

Extensions

Multiple constraints and alerts

[SINCE Orbeon Forms 4.3]

XForms allows a single constraint attribute on the xf:bind element. Orbeon Forms extends this to support any number of nested xf:constraint elements, each specifying a single validation:

<xf:bind ref="." id="input-bind">
    <xf:constraint
        id="length-constraint"
        level="error"
        value="string-length() gt 1"/>
    <xf:constraint
        id="uppercase-constraint"
        level="warning"
        value="for $first in substring(., 1, 1) return upper-case($first) = $first"/>
</xf:bind>

Each constraint applies to the enclosing xf:bind.

Attributes:

  • level: optional, specifies an alert level (defaults to error)

  • constraint: XPath expression specifying the constraint

The id attribute is optional and useful to attach alerts.

Constraints combine with a logical "and" for a given level. For example, if the error level is used (the default), the value is valid only if all constraints evaluate to true().

If there is a single error constraint, the following binds are equivalent:

<xf:bind ref="." id="input-bind" constraint="string-length() gt 1"/>

<xf:bind ref="." id="input-bind">
    <xf:constraint level="error" value="string-length() gt 1"/>
</xf:bind>

Validation levels

[SINCE Orbeon Forms 4.3]

Orbeon Forms supports the following validation levels:

  • error (which corresponds to XForms's valid/invalid)

  • warning

  • info

The default validation level is error.

The warning and info levels allow checking validation conditions that are weaker than errors.

Levels are hierarchical. If a control is valid, it can have a warning level. This is the case if there is at least one failed warning constraint.

If a control doesn't have a warning level, it can have an info level. This is the case if there is at least one failed info constraint.

A warning or info level does not make the control value invalid and it is still possible to submit form data.

Nested validation elements

[SINCE Orbeon Forms 4.9]

Instead of type and required attributes, you can use xf:type and xf:required elements nested within xf:bind.

This allows assigning a specific identifier to a validation with the id attribute, so that xf:alert can refer to those with the validation attribute:

<xf:bind id="control-1-bind" name="control-1" ref="control-1">
    <xf:required value="true()" id="validation-3-validation"/>
    <xf:type id="validation-4-validation">xs:decimal</xf:type>
    <xf:constraint value=". ge 10" id="validation-5-validation"/>
    <xf:constraint value=". ge 20" id="validation-6-validation" level="warning"/>
</xf:bind>
<fr:number bind="control-1-bind">
    <xf:alert ref="$form-resources/control-1/alert[1]" validation="validation-3-validation"/>
    <xf:alert ref="$form-resources/control-1/alert[2]" validation="validation-4-validation"/>
    <xf:alert ref="$form-resources/control-1/alert[3]" validation="validation-5-validation"/>
    <xf:alert ref="$form-resources/control-1/alert[4]" validation="validation-6-validation"/>
    <xf:alert ref="$fr-resources/detail/labels/alert"/>
</fr:number>

This allows having distinct alerts for indicating:

  • that the value is required

  • that the value must be of the given datatype

  • that the value must satisfy constraints expressed in XPath

LIMITATION: As of Orbeon Forms 2018.2, only the first type and the first required attribute or element associated with an xf:bind element are taken into account. On the other hand, all constraint elements are handled.

Multiple alerts

[SINCE Orbeon Forms 4.3]

A control can have more than one xf:alert element. By default, an xf:alert is considered the default alert for the control and is active for all validation levels and constraints:

<xf:alert>

If a level attribute is specified, the alert is active for the given levels:

<xf:alert level="warning info">

If a validation attribute is specified, the alert is active only for the given validations:

<xf:alert validation="c1 c2">

In this example, c1 and c2 refer to id attributes on xf:constraint elements. Only xf:constraint elements associated with a bind pointing to the node to which the control is bound are considered.

Blank level and validation attributes are equivalent to no attributes.

If both level and validation attributes are specified, level is ignored:

<xf:alert level="error" validation="c1 c2">

More than one alert can be active at the same time, following a hierarchy:

  • If the control doesn't have a validation level, no alert is active.

  • If there is a level:

    • If there is a failed required validation, the default alert is active.

    • Otherwise, if there is a failed data type validation, the default alert is active.

    • Otherwise, if there are alerts that match specific failed constraints, those alerts and no others are active.

    • Otherwise, if there are alerts that match the specific level, those alerts and no others are active.

    • Otherwise, if present, the default alert is active.

    • Otherwise, no alert is active.

Example:

<xf:bind ref="." id="input-bind">
    <xf:constraint
        id="length-constraint"
        level="error"
        value="string-length() gt 1"/>
    <xf:constraint
        id="uppercase-constraint"
        level="warning"
        value="for $first in substring(., 1, 1) return upper-case($first) = $first"/>
</xf:bind>

<xf:input id="my-input" ref=".">
    <xf:alert id="alert-1">All levels</xf:alert>
    <xf:alert id="alert-2" level="error">Error level</xf:alert>
    <xf:alert id="alert-3" level="warning">Warning level</xf:alert>
    <xf:alert id="alert-4" level="error warning">Error and warning level</xf:alert>
    <xf:alert id="alert-5" validation="length-constraint">Length constraint</xf:alert>
    <xf:alert id="alert-6" validation="uppercase-constraint">Uppercase constraint</xf:alert>
    <xf:alert id="alert-7" validation="length-constraint uppercase-constraint">Both constraints</xf:alert>
</xf:input>

Validation mode

[SINCE Orbeon Forms 2016.3]

Single-node controls support the xxf:validation-mode attribute, with the following values:

  • incremental: upon refresh, update the control's validity information (default)

  • explicit: upon refresh, don't update the control's validity information

When used on grouping controls, descendant controls inherit the value.

With the explicit mode, the following action allows explicitly updating the validity information on a control or subtree of controls:

<xxf:update-validity
    control="control1 control2"
    recurse="true"/>

The action:

  • makes sure the UI is up to date

  • updates the validity of the selected controls which have xxf:validation-mode set to explicit

  • marks the UI for a subsequent refresh

Attributes:

  • control: space-separated list of controls to update

  • recurse: when set to true, check all descendant controls of the specified controls as well

xxforms-valid and xxforms-invalid events

Orbeon Forms supports extensions events dispatched to an instance when it becomes valid or invalid:

  • xxforms-valid

  • xxforms-invalid

Orbeon Forms (4 and newer) behavior

These events are dispatched just after xforms-revalidate completes on a given model to all instances that change their validation state (from valid to invalid or from invalid to valid):

  • If the instance is newly valid, xxforms-valid is dispatched

  • If the instance is newly invalid, xxforms-invalid is dispatched

Before the initial validation of a model, instances are assumed to be in the valid state.

These events can be used, for example, to toggle the appearance of icons indicating that a form is valid or invalid:

<xf:instance id="my-instance">
    ...
</xf:instance>
<xf:action ev:event="xxforms-invalid" ev:observer="my-instance">
    <xf:toggle case="invalid-form-case"/>
</xf:action>
<xf:action ev:event="xxforms-valid" ev:observer="my-instance">
    <xf:toggle case="valid-form-case"/>
</xf:action>

Orbeon Forms 3.9 behavior

These events are dispatched just before xforms-revalidate completes, to all instances of the model being revalidated. For a given instance, either xxforms-valid or xxforms-invalid is dispatched for a given revalidation.

xxforms-constraints-changed event

[SINCE Orbeon Forms 4.3]

This event is dispatched to a control whenever the list of failed constraints associated with the control's bound node change.

Context information:

  • level: the control's current validation level ("error", "warning", "info", or the empty sequence)

  • constraints: ids of all current failed constraints

  • errors: ids of current failed error constraints

  • warnings: ids of current failed warning constraints (empty if current level is "error")

  • infos: ids of current failed info constraints (empty if current level is "warning" or "error")

  • added-errors: ids of current errors added since the last refresh

  • removed-errors: ids of current errors removed since the last refresh

  • added-warnings: ids of current warnings added since the last refresh

  • removed-warnings: ids of current warnings removed since the last refresh

  • added-infos: ids of current infos added since the last refresh

  • removed-infos: ids of current infos removed since the last refresh

xxf:valid() and xxf:invalid() XPath functions

xxf:valid() returns the validity of a instance data node or of a subtree of instance data.

xxf:invalid-binds() allows you to determine which bind caused node invalidity.

xxf:xml type

This types checks that the value is well-formed XML:

<xf:bind ref="my-xml" type="xxf:xml"/>

Note that this checks the string value of the node, which means that the node must contain escaped XML.

[SINCE Orbeon Forms 2020.1]

The xxf:XML capitalization is supported and preferred, for consistency with xxf:XPath2ValueTemplate.

<xf:bind ref="my-xml" type="xxf:XML"/>

xxf:xpath2 type

This types checks that the value is well-formed XPath 2.0. Any variable used by the expression is assumed to be in scope:

<xf:bind ref="my-xpath" type="xxf:xpath2"/>

NOTE: In both these cases, Orbeon Forms checks for the required MIP: if it evaluates to false() and the value is the empty string, then the instance data node is considered valid. This is contrary to XForms 1.1 but follows XForms 2.0.

[SINCE Orbeon Forms 2020.1]

The xxf:XPath2 capitalization is supported and preferred, for consistency with xxf:XPath2ValueTemplate.

<xf:bind ref="my-xpath" type="xxf:XPath2"/>

xxf:XPath2ValueTemplate type

[SINCE Orbeon Forms 2020.1]

This types checks that the value is a well-formed XPath 2.0 value template. Any variable used by the expression is assumed to be in scope:

<xf:bind ref="my-xpath" type="xxf:XPath2ValueTemplate"/>

Controlling the XML Schema validation mode

When an XML Schema is provided, Orbeon Forms supports controlling whether a particular instance is validated in the following modes:

  • "lax" mode

  • "strict" mode

  • not validated at all ("skip" mode)

Orbeon Forms implements a "lax" validation mode by default, where only elements that have definitions in the imported schemas are validated. Other elements are not considered for validation. This is in line with XML Schema and XSLT 2.0 lax validation modes, and with the default validation mode as specified in XForms 1.1

In addition, the author can specify the validation mode directly on each instance with the extension attribute xxf:validation, which takes values:

  • lax (the default)

  • strict (the root element has to have a definition in the schema and must be valid)

  • skip (no validation at all for that instance)

<xf:model schema="my-schema.xsd">
    <xf:instance id="my-form" xxf:validation="strict">
        <my-form> ... </my-form>
    </xf:instance>
    <xf:instance id="items" xxf:validation="skip">
        <items> ... </items>
    </xf:instance>
</xf:model>

Nodes validated through an XML Schema receive data type annotations, which means that if an element or attribute is validated against xs:date in a schema, an XForms control bound to that node will display a date picker.

XML Schema validation

[IN PROGRESS]

Validation and submission

[IN PROGRESS]

Validation and controls

[IN PROGRESS]

NOTE: As of Orbeon Forms 2018.2, it is only possible to associate a warning or info validation level to a constraint specified with xf:constraint/@value. It is not possible to associate these levels to the required or data type validations: they always use the error level. See also

NOTE: This is the behavior as of Orbeon Forms 4.6.2 and newer, see . Prior to that, a failed required validation was at the same level as other failed validations. The 4.6.2 behavior makes it so that the required validation has priority over other error validations.

NOTE: A until Orbeon Forms 2017.2 caused the event to be dispatched to all controls during the first refresh..

Form Builder Validation
issue #3571
#1830
bug