· Woohyun Kim · Platform Engineering
Designing the WFF XML Schema, Part 2 — Organization and Authoring Rules
How we organized and maintained reusable XSD definitions: files aligned with element hierarchies and semantic groups, shared and local definitions, naming rules, and input assistance through Preferences.
The previous article explained how we defined and reused watch face XML elements, attributes, and types in XSD. This article describes how we organized and maintained those definitions in the project.
The central principle of the initial WFF design was to define and reuse concepts in units as atomic as practical. Breaking definitions into small units did not mean placing each one in a separate file. We distinguished the unit of reuse from the unit of file organization, and established placement rules based on element composition and the meaning of each feature.
Separating Definitions and Files
XSD definitions can be split across files that reference one another. Since WFF elements form a hierarchy, I considered a similar organization for the definition files an intuitive way to understand and maintain them.
Shared attributes and types were grouped by meaning in separate files and referenced with xs:include where needed. Extensions specific to an element could be added in the directory containing that element’s definition. This made the locations of shared definitions and feature-specific extensions understandable in terms of the element hierarchy.
The base directory is wff/specification/documents/1. The following tree shows a relevant subset.
documents/1/
├── watchface.xsd
├── sceneElement.xsd
├── group/
│ ├── groupElement.xsd
│ ├── renderModeType.xsd
│ └── part/
│ ├── abstractPartType.xsd
│ ├── draw/
│ │ ├── partDrawElement.xsd
│ │ ├── shape/
│ │ └── style/
│ ├── image/
│ │ └── partImageElement.xsd
│ └── text/
│ └── partTextElement.xsd
└── common/
├── attributes/
│ ├── geometricAttributes.xsd
│ ├── dimensionType.xsd
│ └── colorAttributes.xsd
└── transform/
└── transformElements.xsdElement Definitions: Composition and Scale
For example, group/part/ holds the common Part definitions, while draw/, image/, and text/ contain the concrete definitions for each kind of Part. Within draw/, shapes and styles such as fills and strokes are separated into shape/ and style/. Related definitions can be located through paths that reflect their composition and function.
We split files around substantial elements with a meaningful role. Simple child elements could be declared locally within their parent, reducing the file count and keeping related definitions together for review. Definitions that grew larger or became important enough to examine independently were moved into their own files. Developers could judge the exact boundary based on the element’s meaning and size.
Attribute and Type Definitions: Semantic Groups
Instead of creating a file for every attribute or type name, we grouped related definitions by meaning. For example, x, y, width, and height each have their own declaration, but all describe geometry, so they were maintained together in geometricAttributes.xsd. The attributeGroup definitions that combine them were placed in the same file.
Individual attributes could still be referenced and reused as atomic definitions, while related declarations could be reviewed together in one file. colorAttributes.xsd, which groups color-related attributes and types, follows the same approach.
Shared and Local Definition Scope
Definitions shared by multiple elements were placed under common/. Geometry attributes and coordinate and size types are in common/attributes/; common behavior elements such as Transform are in common/transform/. Definitions associated with a particular element hierarchy were placed with that feature, as in group/renderModeType.xsd.
We used the following criteria to decide placement, declaration form, and names that indicate internal use.
| Decision | Approach | Purpose |
|---|---|---|
| Is the definition shared across elements, or specific to a feature? | Place shared definitions in common/; keep feature definitions and extensions with the relevant element. | Preserve shared definitions while keeping extension-related changes with the feature. |
| Is it reused within a feature, or used in only one declaration? | Name reusable definitions; use an anonymous type when the definition is specific to one declaration. | Match the declaration form to the scope of reuse. |
| Is a named definition an internal helper? | Prefix its name with _. | Distinguish it from shared definitions intended for use by other features. |
The Expression inside Expressions in the previous article extends a shared expression type through an anonymous type specific to that declaration. For attributes, the TO and BY values of Transform.mode are defined through an anonymous type within the attribute itself.
The _ Prefix for Internal Helper Definitions
Named definitions intended for use only within a feature received the _ prefix. Examples include _operatorType, _functionType, and _arithmeticType in arithmeticExpressionType.xsd.
This convention was necessary because XSD does not provide visibility controls for these named internal definitions. Including definitions in the same namespace through xs:include also exposes their helper types. Since the schema cannot enforce a file- or directory-level usage boundary, the name signals that a declaration is intended for internal use within the feature.
Identifying Definitions by File Name
File names used camelCase, with suffixes to identify the kind of definition they contained. The casing itself had no special technical significance; the aim was to make the subject of each file consistently recognizable.
| Definition | Suffix | Example files |
|---|---|---|
| Element | Element, Elements | partImageElement.xsd, transformElements.xsd |
| Attribute | Attribute, Attributes | alignmentAttribute.xsd, geometricAttributes.xsd |
| Type | Type, Types | unsignedCharacterType.xsd, primitiveListTypes.xsd |
Element files were named after their principal element, as with partImageElement.xsd for PartImage. Even when simple child elements were defined inline, the file name followed the principal element. Attribute and type files were named after the meaning of the group, as in geometricAttributes.xsd. Plural suffixes were used for files containing multiple attributes or types, or attribute groups.
These were the naming rules we aimed for during the initial design. Public version 1 also contains files without the Element suffix, such as clock/hourHand.xsd.
Preferences: Suggestions for Frequently Used Values
When specifying opacity in watch face XML, I wanted authors to be able to select 0, 128, and 255—fully transparent, an intermediate level, and fully opaque—from input suggestions. The Preferences suffix identified definitions intended to help an IDE suggest frequently used values. It was a small authoring convenience for developers writing XML directly.
In colorAttributes.xsd, _colorValuePreferences lists those three suggested values using unsignedCharacterType, which allows integers from 0 to 255.
<xs:simpleType name="_colorValuePreferences">
<xs:restriction base="unsignedCharacterType">
<xs:enumeration value="0"/>
<xs:enumeration value="128"/>
<xs:enumeration value="255"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="_colorComponentType">
<xs:union memberTypes="_colorValuePreferences unsignedCharacterType"/>
</xs:simpleType>
<xs:attribute name="alpha" type="_colorComponentType"/>Although _colorValuePreferences itself is restricted to three values, the actual alpha attribute uses a type that combines it with the original unsignedCharacterType. Consequently, alpha="64" is valid even though it is absent from the suggestion list, while alpha="256" exceeds the common type’s range and is rejected.
This expresses frequently used input candidates in the schema while preserving the full range of allowed values. The actual suggestion behavior depends on the IDE’s schema support. The _ in the name indicates an internal helper definition; Preferences indicates its input-assistance purpose.
Series Contents
Code source: Public WFF XSD, version 1, Copyright 2023 Samsung Electronics Co., Ltd, Apache License 2.0. The file tree shows selected paths, and code excerpts retain only the definitions needed for the explanation.
- Wear OS
- WFF
- XML
- XSD
- Schema Design