· Woohyun Kim · Platform Engineering
Designing the WFF XML Schema, Part 1 — Defining and Reusing Elements, Attributes, and Types
The principles behind the watch face XSD: rendering and behavior elements, abstract type extension, and the separation and reuse of common attributes and domain-specific types.
Designing an XSD for watch face XML means defining the elements and attributes that express the rendering scene and its behavior, together with value types and composition constraints. This article explains the design and implementation introduced in the preface.
An Analog Watch Face XML Example
First, consider a simple XML document written by a watch face author.
watchface.xml — an analog watch face example
<WatchFace width="360" height="360">
<Scene>
<Condition>
<Expressions>
<Expression name="step_goal_reached"><![CDATA[[STEP_COUNT] >= 5000]]></Expression>
</Expressions>
<Compare expression="step_goal_reached">
<PartImage x="0" y="0" width="360" height="360">
<Image resource="rotating_bg_by_step_goal" />
<Transform target="angle" value="[SECONDS_IN_DAY] / 240" />
</PartImage>
</Compare>
</Condition>
<PartImage x="0" y="0" width="360" height="360"><Image resource="clock_index" /></PartImage>
<AnalogClock x="0" y="0" width="360" height="360">
<HourHand resource="hour_hand" x="90" y="90" width="180" height="180" />
<MinuteHand resource="minute_hand" x="0" y="0" width="360" height="360" />
<SecondHand resource="second_hand" x="0" y="0" width="360" height="360" />
</AnalogClock>
</Scene>
</WatchFace>This example shows an author building an analog watch face by specifying a virtual canvas size on WatchFace, then placing a background, a dial-marker image, and the hour, minute, and second hands of an AnalogClock under Scene. Each element’s position and size are expressed through x, y, width, and height.
Inside Condition, an Expression tests whether the daily step count ([STEP_COUNT]) has reached 5,000 and is assigned the identifier step_goal_reached. Compare references that identifier, displaying its child background PartImage only after the 5,000-step goal has been reached.
The background PartImage contains a Transform that converts the seconds elapsed in the day ([SECONDS_IN_DAY]) into an angle. Dividing the day’s 86,400 seconds by 240 gives 360 degrees, so the visible background rotates slowly according to that angle. The dial-marker image and clock hands are outside Condition and remain visible regardless of the step count. The dial-marker image has no Transform and stays fixed.
Each hand image is square, including its transparent margins, with its rotation pivot at the image center. The hour hand is 180×180 at (90, 90); the minute and second hands are 360×360 at (0, 0). Their sizes and positions differ, but all three pivots coincide with the canvas center at (180, 180).
The hand elements directly support rotation with time, so no separate behavior logic is needed. Authors can also use PartText for digital time or PartImage for a watch face background. To change a Part’s position or angle dynamically, they can describe its behavior with the Transform element discussed below.
I will now explain how we defined these XML elements, attributes, and value types in XSD. The code explanations use public version 1.
Defining Elements, Attributes, and Types
A priority in the design was to prevent similar definitions from being repeatedly introduced and extended in different features. Defining the same concept slightly differently in several places increases code volume and makes differences and scope harder to understand. To reduce duplication while preserving readability and clarity, I made separating elements, attributes, and types, and defining and reusing them in units as atomic as practical the central design principle.
Concepts shared across elements, such as position, size, and color, were expressed through three kinds of definition.
| Definition | Role in the design | Examples |
|---|---|---|
| Element | Declares scene structure, functionality, and behavior | PartImage, HourHand, Transform |
| Attribute | Describes an element’s position, size, and rendering parameters | x, y, width, height, alpha |
| Type | Defines value representations and allowed ranges, or rules for element composition | dimensionType, argbHexadecimalType, AbstractPartType |
Here, “atomic” describes a criterion for separating definitions, rather than an XSD type category. Just as mathematical definitions require well-definedness, I wanted watch face XSD definitions to have clear meanings that did not change with their context of use.
Elements: Rendering Structure and Behavior
I distinguished elements that form the rendering hierarchy from non-rendering elements that describe behavior.
Elements in the Rendering Hierarchy
Generic elements for images, text, and shapes provide design flexibility. Visual elements that recur specifically in watch faces were given definitions that express their domain meaning.
| Category | Representative elements | Purpose |
|---|---|---|
| Generic visual elements | PartImage, PartText, PartDraw | Combine images, text, and shapes into different designs |
| Hierarchy container | Group | Organize child rendering nodes as a hierarchy |
| Clock-specific elements | HourHand, MinuteHand, SecondHand | Declare elements with explicit roles, such as the hands of an analog clock |
| Data beyond time | ComplicationSlot, Complication | Present other watch face data through images, text, and related content |
Group participates in the rendering hierarchy but does not draw pixels itself. The public groupElement.xsd describes it as a container that affects the position, size, angle, and color of its child hierarchy.
Generic elements support varied designs, while clock-specific elements declare domain functionality. For example, HourHand represents an hour hand, and ComplicationSlot defines a data-display slot and its child Complication elements.
Abstraction and Type Derivation in XSD
XSD supports abstract elements and types, as well as type extension and restriction. Attribute declarations, attribute groups, and data types can also be named and reused. The W3C XML Schema Primer explains these concepts.
For example, AbstractPartType is a complex type with abstract="true". The type of the PartDraw element extends it through xs:extension base="AbstractPartType" within xs:complexContent.
<xs:element name="PartDraw">
<xs:complexType>
<xs:complexContent>
<xs:extension base="AbstractPartType">
<xs:all>
<xs:element ref="DrawElement" minOccurs="1" maxOccurs="unbounded"/>
</xs:all>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>This reuses the common composition of AbstractPartType and declares DrawElement as a child of PartDraw. Type derivation is a mechanism for reusing definitions; it is distinct from parent–child containment between XML elements.
Extending abstract types and combining shared attributes apply the perspectives of abstraction and inheritance from object-oriented design to the specification. The attributeGroup example below explains attribute composition.
Non-rendering Elements: Declaring Runtime Behavior
Elements such as Transform and Gyro describe how their parent rendering element behaves in response to runtime data, rather than defining an image to render themselves.
Position, size, angle, and similar attributes declared directly on a rendering element describe its base state. Child behavior elements instead declare how that state changes with dynamic runtime conditions or data.
- Transform identifies the affected attribute through
targetand supplies an expression invalue. - Gyro uses sensor-data expressions to adjust attributes of its parent
Groupor Part.
This lets a single document declare both the static scene structure and runtime behavior.
Attributes: Reusing Atomic Definitions
The coordinate and size definitions illustrate the relationship between types, attributes, attribute groups, and their use sites. Shared attributes reference dimensionType; attribute groups combine those attributes so that generic Parts and clock hands use the same geometry definitions.
1. Separating Value Types from Attribute Declarations
dimensionType.xsd defines a type for integer coordinates and dimensions. In geometricAttributes.xsd, four attributes reference that type.
<!-- dimensionType.xsd -->
<xs:simpleType name="dimensionType">
<xs:restriction base="xs:integer"/>
</xs:simpleType>
<!-- geometricAttributes.xsd -->
<xs:attribute name="x" type="dimensionType"/>
<xs:attribute name="y" type="dimensionType"/>
<xs:attribute name="width" type="dimensionType"/>
<xs:attribute name="height" type="dimensionType"/>At this level, attribute names and value types are separate. The four attributes share a single domain type rather than each declaring an integer type independently.
2. Grouping and Combining Attributes by Purpose
The same file defines separate position and size attribute groups, then combines them in geometricAttributesRequired. use="required" is specified at the point where the attribute declaration is referenced.
<xs:attributeGroup name="positionAttributesRequired">
<xs:attribute ref="x" use="required"/>
<xs:attribute ref="y" use="required"/>
</xs:attributeGroup>
<xs:attributeGroup name="sizeAttributesRequired">
<xs:attribute ref="width" use="required"/>
<xs:attribute ref="height" use="required"/>
</xs:attributeGroup>
<xs:attributeGroup name="geometricAttributesRequired">
<xs:attributeGroup ref="positionAttributesRequired"/>
<xs:attributeGroup ref="sizeAttributesRequired"/>
</xs:attributeGroup>The original also includes positionAttributes, sizeAttributes, and geometricAttributes, which do not specify requiredness. The same attribute declarations can thus be assembled into groups with the usage conditions needed at each use site.
3. Using the Same Definitions Across Elements
AbstractPartType and HourHand both reference this attribute group.
<xs:complexType name="AbstractPartType" abstract="true" block="restriction">
<!-- Child elements omitted -->
<xs:attributeGroup ref="geometricAttributesRequired"/>
<!-- Other attributes omitted -->
</xs:complexType>
<xs:element name="HourHand">
<xs:complexType>
<!-- Child elements and resource attribute omitted -->
<xs:attributeGroup ref="geometricAttributesRequired"/>
<!-- Other attributes omitted -->
</xs:complexType>
</xs:element>Types extending the generic Part and the hour-hand element therefore use the same coordinate and size rules while defining their own functionality separately. The full reference chain is:
dimensionType
↑ type reference
x, y, width, height
↑ ref reference
positionAttributesRequired + sizeAttributesRequired
↑ group composition
geometricAttributesRequired
↑ group reference
Types of AbstractPartType / HourHandThis is attribute composition rather than inheritance. Separating value types, individual attributes, usage conditions, and use sites reduces repeated declarations.
Types: WFF Domain Values and Constraints
XSD provides built-in types such as xs:string, xs:integer, and xs:float. We used these directly where appropriate and defined separate types where the WFF domain required specific values or constraints.
sourceType: Defining and Combining Domain Values
sourceType.xsd defines separate types for sources such as time, language, battery, sensor, and health data.
For example, languageSourceType derives from xs:string and restricts language-related identifiers through xs:enumeration. Time sources are split into timeUnitSourceType and _timeSourceType, then combined in timeSourceType. Finally, sourceType combines types from the different domains.
The public definitions form the following composition:
timeUnitSourceType + _timeSourceType
└── timeSourceType
timeSourceType, languageSourceType, batterySourceType, ...
└── sourceType (xs:union)Each domain’s value set is maintained separately, and xs:union combines the sets needed by the consuming definition.
For example, the following values are declared in their respective constituent types and are all allowed by the combined sourceType.
Composition path to sourceType | Example allowed values |
|---|---|
timeUnitSourceType → timeSourceType → sourceType | SECOND, MINUTE |
_timeSourceType → timeSourceType → sourceType | SECONDS_IN_DAY, HOUR_0_23 |
languageSourceType → sourceType | LANGUAGE_CODE |
batterySourceType → sourceType | BATTERY_PERCENT |
The earlier background rotation example’s [SECONDS_IN_DAY] uses this definition. The type allows the identifier SECONDS_IN_DAY; expressions enclose it in square brackets to reference the corresponding data.
argbHexadecimalType: Adding Domain Constraints to a Built-in Type
In colorAttributes.xsd, argbHexadecimalType derives from xs:string. An xs:pattern within xs:restriction defines a pattern constraint for #AARRGGBB or #RRGGBB color notation.
For example, #FF336699 uses #AARRGGBB, including alpha, while #336699 uses #RRGGBB. Both strings match this type’s pattern. This adds color-code length and hexadecimal-character constraints to the built-in string type.
arithmeticExpressionType: Expressing Runtime Behavior
Alongside elements with predefined behavior, such as clock hands, we needed expressions that let authors specify runtime behavior directly. For example, declaring the following Transform under a rendering element calculates the parent’s angle from seconds data.
<Transform target="angle" value="[SECOND] * 6 + 180" />[SECOND] is the seconds component of the current time. Multiplying it by 6 and adding 180 produces the angle. This expression also appears in the public XSD comments. The Runtime evaluates it using runtime data and applies the result to the parent’s attribute identified by target="angle". Gyro similarly uses expressions based on sensor data to describe rendering-element behavior.
The type for such values is arithmeticExpressionType, referenced by Transform.value. In arithmeticExpressionType.xsd, the expression components are defined individually and combined as follows.
source data · operators · functions · symbols · strings
↓ xs:union
_arithmeticType
└── xs:list → _arithmeticListType
_arithmeticType + _arithmeticListType
↓ xs:union
arithmeticExpressionTypeIndividual components and lists of those components are combined into an expression type that element attributes can reference. Sensor-based expressions use the same structure, with sensorSourceType as their source type, to define gyroArithmeticExpressionType.
Expressions can contain mathematical symbols that must be distinguished from XML markup; the public XSD comments recommend CDATA where needed. Element character data can use a CDATA section. Within attribute values such as Transform.value, < and & are escaped as < and &.
Shared Definitions and Local Extensions
The design allowed requirements that extend common definitions to be defined locally within the relevant feature. Shared definitions could remain intact while individual features added the detailed constraints and composition they needed.
For example, expressionsElement.xsd declares the local element Expression inside Expressions. Its anonymous complex type extends the common arithmeticExpressionType with a name attribute that identifies the expression. A Compare within the same Condition references that identifier through its expression attribute. In the XML example, the identifier is step_goal_reached.
<xs:element name="Expressions">
<xs:complexType>
<xs:choice minOccurs="1" maxOccurs="unbounded">
<xs:element name="Expression">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="arithmeticExpressionType">
<xs:attribute name="name" type="xs:string" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>The common definition of an expression value is preserved, while the attribute needed to identify and reference it from other declarations is added within that local declaration.
The organization and authoring rules article explains when and how to use local extensions, along with the naming convention for internal helper definitions.
An Initial Design Constraint: Adaptive Layout
Public version 1’s watchface.xsd defines a virtual canvas size through width and height; child elements specify positions and sizes in that virtual coordinate system. Adaptive layout that changes relationships between nodes according to the physical display’s resolution or aspect ratio was outside the initial scope. For example, authors could not declare rules that rearrange elements for an aspect ratio other than 1:1.
At the time, watch displays were sufficiently similar in shape and aspect ratio that we expected little demand for adaptive layout. Supporting it from the outset would have increased the complexity of both the format and the Runtime, while requiring authors to decide on layout rules for different displays. Leaving it out reduced both the initial implementation cost and the author’s design burden.
Instead, we assumed an implicit mapping from the virtual canvas to the physical display, similar to Android’s scaleType=“fitCenter”: scale the entire composition to fit within the display while preserving its aspect ratio, and center it. Authors could reuse the same composition without specifying layouts for each resolution.
Physical display resolution, virtual canvas size, and layout relationships between nodes are separate design concerns. For the initial design, we considered virtual coordinates and scaling a reasonable solution, with the explicit constraint that layout relationships would not change with the display’s aspect ratio. If hardware diversity or user needs increased, we could extend the format with layout elements in a later version.
Reconsidering the Part Prefix
I proposed using the common prefix Part for concrete Part element names. This was a discoverability decision intended to help developers find related elements when writing watch face XML directly.
I expected a developer thinking “What Parts can I use?” to type Part and see the relevant elements suggested together by the IDE.
Part
├── PartDraw
├── PartImage
└── PartTextThe team found the reasoning sound and adopted the naming scheme.
I also considered that DrawPart, ImagePart, and TextPart might read more naturally to English-speaking users, but at the time I prioritized discovery through the common prefix.
Looking back, I would probably have prioritized natural English word order over prefix-based IDE discovery and chosen Part as a suffix: DrawPart, ImagePart, and TextPart.
Series Contents
Code source: Public WFF XSD, version 1, Copyright 2023 Samsung Electronics Co., Ltd, Apache License 2.0. XSD excerpts retain only the parts needed for the explanation. The watchface.xml and Transform usage examples were written separately.
- Wear OS
- WFF
- XML
- XSD
- Schema Design