Generate XML Schema API

Availability

This is an Orbeon Forms PE feature.

What it does

This is a Form Runner service that generates an XML Schema 1.0 or 1.1 schema for a published form. The schema is specific for the app and form name selected.

You access the service using the following URL:

• Orbeon Forms 4.4 and newer: /fr/service/[app]/[form]/schema

• Orbeon Forms 4.0 to 4.3: /fr/[app]/[form]/schema

With 4.4 and newer, the service must be authorized like other services.

The service assumes that the data model of the form is standard XML data model as generated by Form Builder. Custom XML data models are not supported.

Parameters

Form version

If the persistence layer on which your form is published supports versioning, by default the latest version of the form is used. If instead, you'd like to produce the schema for a specific form version, you can pass that version number with the form-version request parameter:

?form-version=42

Data format version

The XML form data format used in the database, and by the various Orbeon Forms APIs, is typically always the same, irrelevant of the Orbeon Forms version you are on. This format is referred as the 4.0.0 format.

• Because of this [UNTIL Orbeon Forms 2020.1], the schema API always produced a schema for data in the 4.0.0 format.

• Should you want this API to produce a schema corresponding to another format, [SINCE Orbeon Forms 2021.1], you can specify the format you want through the data-format-version request parameter. The accepted values are:

  • 4.0.0 (this is equivalent to not having a data-format-version request parameter but allows you to be explicit)

  • 4.8.0

  • 2019.1.0

  • edge (this means "use the latest data version", which is currently equivalent to 2019.1.0; in most cases, it is better to explicitly specify the version you want, to avoid the possibility of the format changing in case a new data format is introduced by a future version of Orbeon Forms)

?data-format-version=2019.1.0

Type for maybe non-relevant elements

[SINCE Orbeon Forms 2018.2.3]

When you create a form in Form Builder, if you specify a type for a field, and also make that field only show when some condition is met, should that condition not be met, then the type constraint isn't enforced as users have no way of providing a value for a field that isn't shown.

Consequently, when producing a schema from a form definition, Orbeon Forms doesn't specify the type for fields that under some condition might not be shown. Doing so would mean that, in some cases, form data that passes the Orbeon Forms validation wouldn't be considered valid according to the generated schema.

However, in some cases, you might still want to have that type information in the schema. This could be because you're not using the schema to validate data, but to extract some information from it. If you are in one of those situation, you can instruct Orbeon Forms to always generate the type for elements in the schema, even if the corresponding field might, under some condition, not be shown. This is done by adding the following request parameter to the URL:

?produce-type-for-maybe-nonrelevant=true

Limitations

• Not all form validations can be encoded in an XML Schema. For example, validations specified with the XForms constraint attribute are not present, as they are expressed with XPath an XML Schema 1.0 does not support XPath constraints.

Example

Here is the schema produced for the W9 form as of Orbeon Forms 4.4:

<xs:schema
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xf="http://www.w3.org/2002/xforms" >
    <xs:import
        namespace="http://www.w3.org/2002/xforms"
        schemaLocation="http://www.w3.org/MarkUp/Forms/2007/XForms-11-Schema.xsd"/>
    <xs:element name="form">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="applicant">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="name"/>
                            <xs:element name="business-name"/>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
                <xs:element name="classification">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="federal-tax-classification">
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:enumeration value="1"/>
                                        <xs:enumeration value="2"/>
                                        <xs:enumeration value="3"/>
                                        <xs:enumeration value="4"/>
                                        <xs:enumeration value="5"/>
                                        <xs:enumeration value="6"/>
                                        <xs:enumeration value="7"/>
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                            <xs:element name="llc-classification"/>
                            <xs:element name="other-classification"/>
                            <xs:element type="xf:boolean" name="exempt-payee"/>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
                <xs:element name="address-account">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="address-1"/>
                            <xs:element name="address-2"/>
                            <xs:element name="account-numbers"/>
                            <xs:element name="requester-name-address"/>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
                <xs:element name="tin">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="ssn-or-ein">
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:enumeration value="ssn"/>
                                        <xs:enumeration value="ein"/>
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                            <xs:element name="ssn"/>
                            <xs:element name="ein"/>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
                <xs:element name="hidden">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element type="xf:date" name="current-date"/>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>