· Woohyun Kim · Platform Engineering

Designing the WFF XML Schema, Part 3 — Validation: Purpose and Boundaries

What WFF element, attribute, and type declarations validate, how uniqueness constraints and XSD 1.1 assertions fit in, and how validation requirements can prompt a review of the definitions themselves.

An important reason for specifying WFF in XSD was that the definitions themselves could be used to validate XML. In this article, validation means checking whether a watch face XML document satisfies the structure and constraints declared in its XSD.

Because XSD is a standard, we can use existing APIs and libraries to load a schema and check XML against it. Java, for example, provides javax.xml.validation. Declaring the allowed elements, attributes, and values in a schema reduces the amount of code needed to check those rules individually. Development and maintenance costs were an important consideration when we adopted XSD.

A Concrete Example: Defining Group

I will use WFF’s Group definition to explain the validation rules that follow. A Group is a container for rendering elements and other groups. The declarations below, from groupElement.xsd, provide an example of child composition, attributes, and value validation.

groupElement.xsd — XSD excerpt
<xs:element name="Group">
  <xs:complexType>
    <xs:all>
      <xs:element ref="Gyro" minOccurs="0" maxOccurs="1"/>
      <xs:element ref="Transform" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element ref="Group" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element ref="PartImage" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element ref="PartAnimatedImage" minOccurs="0" maxOccurs="unbounded"/>
      <!-- Other child element definitions omitted -->
    </xs:all>

    <xs:attribute name="name" use="required">
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:minLength value="1"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:attributeGroup ref="geometricAttributesRequired"/>
    <!-- Other attribute definitions omitted -->
  </xs:complexType>
</xs:element>

Rules Validated by Element, Attribute, and Type Declarations

Allowed Children and Occurrence Counts

all specifies the allowed child elements and their occurrence counts without fixing the order in which different kinds of children appear. For example, this composition rule does not constrain the order of PartImage and Transform declarations within a Group.

Other composition constructs include sequence, which specifies the order of child elements, and choice, which selects one of the allowed alternatives.

The declarations above are enough to check the following structural rules. If omitted, minOccurs and maxOccurs each default to 1.

Child elementAllowed compositionValidation meaning
GyroNone or oneTwo declarations fail validation.
Transform, Group, PartImage, PartAnimatedImageZero or more of eachEach has no upper occurrence limit, and they may coexist.
An element not allowed as a child of GroupCannot be placed directly inside itFor example, a direct child Compare fails validation.

minOccurs="0" allows omission; unbounded places no upper limit on the occurrence count.

Allowed and Required Attributes

Attributes are checked against the element’s attribute and attributeGroup declarations. In this example, Group.name must be present because it has use="required", and cannot be an empty string because it has minLength="1".

Through geometricAttributesRequired, Group also requires x, y, width, and height. Constraints from reused attribute groups therefore participate in the element’s validation.

For example, the following Group supplies its required geometry attributes and name. Omitting width or adding an undeclared attribute such as opacity causes schema validation to fail.

<Group name="clock" x="0" y="0" width="360" height="360" />

XML attributes have no declaration-order semantics, so rearranging these attributes does not change the result. An element also cannot contain duplicate occurrences of the same attribute. Such duplication violates XML well-formedness and is rejected during parsing, before any additional XSD validation.

Value Types and Ranges

An attribute’s value must also satisfy its type constraints. For example, if a geometry attribute uses an integer type, width="wide" is invalid.

The color-related type argbHexadecimalType applies the following pattern constraint to strings.

<xs:simpleType name="argbHexadecimalType">
  <xs:restriction base="xs:string">
    <xs:pattern value="#([A-Fa-f0-9]{8}|[A-Fa-f0-9]{6})"/>
  </xs:restriction>
</xs:simpleType>

#FF336699 and #336699 match the pattern. #GG336699, which contains the non-hexadecimal character G, and the color name blue do not.

Dedicated Validation Constructs and Uniqueness

So far, element, attribute, and type declarations have supplied the validation rules themselves. XSD also provides dedicated constructs for checking value uniqueness and references. Here, I will use xs:unique as an example.

In watchface.xsd, the following rule prevents duplicate bitmap font names within a WatchFace.

<xs:unique name="Validation.Unique.WatchFace.BitmapFonts.BitmapFont.name">
  <xs:selector xpath="BitmapFonts/*"/>
  <xs:field xpath="@name"/>
</xs:unique>

selector selects the set of elements to check, and field specifies the value to compare. Here, it compares the name values of fonts declared under BitmapFonts.

The names of Character and Word elements within a font are checked separately for uniqueness in bitmapFontsElement.xsd. For example, declaring two characters with name="0" in the same font violates that constraint.

XSD 1.1 also provides xs:assert for specifying conditions directly. I will cover it below in the discussion of conditional relationships.

Rules That Need More Than Structural Declarations

A domain may have relationship rules that are difficult to express within the usual flow of defining elements, attributes, and types.

Conditional Relationships Between Siblings

Consider a hypothetical rule: if a parent has three or more PartImage children, it must not contain a PartAnimatedImage. Whether one kind of element is allowed depends on the count of another kind. Specifying the occurrence count of each element independently cannot directly express that relationship.

Relationships Involving Both Elements and Attributes

Another hypothetical rule might state that if an attribute of element A has a particular value, element B must not have a certain attribute. Again, specifying types and requiredness in the individual element and attribute definitions cannot directly express this relationship.

A WFF Part permits both geometry attributes such as x, y, width, and height and a child Transform. We could imagine a rule that prohibits the parent’s geometry attributes when a Transform is present. This, too, is a relationship that cannot be implemented directly through those individual element and attribute declarations.

Fortunately, in WFF the geometry attributes define the base, static geometric state, while Transform defines dynamic geometric transformations at runtime. Their meanings therefore do not overlap, and using them together creates no conflict in the design.

Conditional Validation in XSD 1.1

XSD 1.1’s xs:assert allows validation conditions written as XPath expressions to consider element counts and attribute values together.

For example, the sibling-element condition above could be added to the parent’s complex type as follows.

<xs:assert test="count(PartImage) lt 3 or empty(PartAnimatedImage)"/>

The condition requires either fewer than three child PartImage elements or no child PartAnimatedImage elements.

The point to notice is that this adds a validation condition separately from the declarations of element and attribute structure. Although xs:assert can be placed within a complex type, it expresses an additional relationship rule rather than expressing that relationship through the child element or attribute declarations themselves.

Reviewing Definitions Through Validation Requirements

Increasingly complex validation conditions can signal unclear responsibilities or relationships in the definitions. We should examine whether a condition expresses a relationship the domain actually requires, or arises because responsibilities have become mixed or the same concept has acquired different meanings in different contexts. This follows the well-definedness perspective from Part 1: checking that each definition and its relationships have a clear, consistent interpretation.

Finally, assert provides a more flexible and powerful way to express validation rules. Before using it to add a rule, however, we need to carefully review whether the definitions have appropriate responsibilities and boundaries.

Series Contents


Code source: Public WFF XSD, version 1, Copyright 2023 Samsung Electronics Co., Ltd, Apache License 2.0. XSD excerpts omit annotations, includes, and definitions outside the explanation’s scope. The XML usage examples and assertion were written for this article.

References: Java XML Validation API, XML Attribute Uniqueness, XSD 1.0 Primer, XSD 1.1: Assertions.

  • Wear OS
  • WFF
  • XML
  • XSD
  • Schema Design
Share:
Back to Blog

Related Posts

View All Posts »

Rotating Objects in 3D Engines

Three practical rotation patterns for objects and cameras in 3D engines, from drag-based object control to camera-aware transforms.