· Woohyun Kim · Platform Engineering

Designing the WFF XML Schema

The context and reasoning behind the initial WFF XSD design and implementation: definitions, authoring rules, and validation, and what they reveal about the strengths and limits of XSD.

WFF (Watch Face Format) is a declarative format for describing the appearance and behavior of a Wear OS watch face in XML. Authors declare rendering elements and behavior, and the Wear OS renderer interprets those declarations to render the watch face. Google and Samsung developed the format together; the Android documentation explains its structure and use.

At Samsung, I was responsible for analyzing the existing watch face XML structure and designing and implementing its XSD (XML Schema Definition). The work covered the organization of elements, attributes, and types, schema constraints, and how the schema would support development.

This series explains the initial WFF specification design and implementation, and the reasoning behind them. It adds the original design intent and decisions to the element, attribute, and type definitions available in the public code, and examines the benefits and limitations of using XSD to specify an XML format.

From Tizen to Wear OS

Samsung watch faces already used a declarative XML format on Tizen. The XML described rendering elements and behavior, which the Runtime interpreted.

The authoring tool at the time, GWD (Galaxy Watch Designer), was later renamed Galaxy Watch Studio. When Samsung watches adopted Wear OS, we developed WFS (Watch Face Studio) as the authoring tool for that platform.

The project began as an effort to rework the authoring tools and watch face structure for Samsung’s platform transition. Creating a standard Android format was not the original objective.

The project was introduced during regular meetings with Google, which was developing Wear OS. Google’s positive assessment led to collaboration between the development teams.

During my involvement in the watch face project, Samsung led development and carried out the implementation. Discussions with Google focused mainly on which features and extensions to include in subsequent versions of the watch face standard. At the code level, Samsung provided its implementation to Google for review.

Both the watch face format and the Watch Face Runtime—the module that loads it, renders it, and executes its behavior—were subsequently adopted and integrated into the Android platform. The format, initially called DWF (Declarative Watch Face) during internal development, received its official name, WFF, in that process.

Why XML and XSD

During the platform transition, we reviewed the existing XML specification. Its developers had documented and maintained it as text on an internal wiki, but interpreting and maintaining the format still depended in part on their knowledge. I wanted to improve this by defining elements, attributes, data types, and their composition in a schema that tools could interpret and validate.

  1. Reusing Existing Watch Face Assets

    An important reason to retain XML was to carry forward the watch face ecosystem built around GWD. Even as Samsung watches moved to Wear OS, I expected that we could reuse the existing Tizen watch face design assets and XML-based structure. The legacy and new formats still differed, so a senior colleague on the team developed an automatic conversion utility for moving Tizen watch faces to Wear OS, which was then distributed. The official Galaxy Watch Studio Converter documentation describes this migration tool.

  2. A Declarative Structure for the Scene Graph

    The XML element tree was also a good fit for a rendering scene graph. Parent–child relationships between rendering nodes mapped directly to nested XML elements, while preserving the existing format’s declarative model. We rendered elements in their XML declaration order as the scene was traversed. Authors could understand the rendering structure from the nesting and ordering of elements. The Android rendering documentation also describes this traversal model.

  3. Using Standard Validation Tools

    Defining elements, attributes, types, and composition constraints in XSD lets standard validators check individual watch face XML documents for schema conformance. I considered direct use of the specification for validation a way to improve development quality and reduce validation costs over time. Alongside the schema structure, we therefore examined which validation rules XSD could express.

  4. Keeping a Future Transition to JSON Schema Feasible

    When choosing XSD, I also considered JSON Schema. During that review, I found libraries that could translate XSD into JSON Schema. This led me to expect that, even if we started with XSD, reusing the existing specification would keep the effort of a future transition to a JSON-based format manageable.

Team Design Reviews and XSD Implementation

We periodically discussed improvements to the existing XML structure within the team. Based on those discussions, I implemented the declarative model as XSD elements, attributes, and types.

As I took responsibility for designing and implementing the XSD, we also needed to review its syntax and definition mechanisms within the team. As I studied it, I organized seminars to share its concepts, design philosophy, expressive capabilities, and limitations. I explained how I had defined the watch face elements, attributes, and types, and covered topics such as coding conventions for writing a consistent, unambiguous specification.

The design and implementation details are covered in the articles that follow.

Use in Authoring and Distribution

Alongside the XSD specification, I developed a Validator that takes watch face XML as input and checks its schema conformance. Google Play checks format validity during watch face uploads, and this Validator was integrated into that validation system. The validator is publicly available through Google’s official repository and as a published package.

Reflections

Collaboration History and Reference Material

Security agreements and system constraints between Samsung and Google meant that colleagues’ change histories were not preserved continuously across the two companies’ repositories. One regret from that collaboration is how difficult it became to trace the design and implementation process through the commit history.

The public code shows the resulting structure, but the reasons for choosing it and the review process are harder to reconstruct. I am writing this series to supplement the design intent and reasoning that the commit history does not fully convey.

The work was managed in Samsung’s internal sec.github and ecode repositories. These articles draw on my experience and recollection of that work, within the scope I can share publicly. The code explanations refer to the public WFF XSD.

All code explanations use version 1 from the Adds WFF XML validator commit.

Choosing the Watch Face Runtime Renderer

The Watch Face Runtime reads watch face XML, renders its declared elements, and executes their behavior. At the time, we implemented its renderer using Android Views.

Given the importance of performance on watch hardware, I considered a renderer built directly on a low-level graphics API such as OpenGL ES (GLES) or Vulkan the ideal approach. Choosing an implementation also required considering the team’s graphics expertise and the project’s maintenance burden. Every Runtime developer would have needed to build deeper graphics expertise, and managing a low-level renderer within an already large Runtime project would have required substantial development and maintenance effort.

Within those constraints, we evaluated whether Android Views could meet the requirements. We anticipated performance problems with watch faces that placed a heavy rendering load on the device, but expected typical watch face designs to meet our performance targets. We adopted a View-based rendering implementation after considering the required performance alongside the team’s development and maintenance capacity.

Extending WFF rendering features within a View-based Runtime means working within the capabilities and control exposed by the View graphics APIs. Effects such as glow, blur, reflection, and distortion can be implemented with simple shading, but our initial evaluation identified limitations in the View-based approach, including the inability to directly control multipass rendering configurations and buffer dimensions, even with RuntimeShader and RenderEffect. A limitation of this approach was that implementation constraints in the Runtime could end up limiting the designs and features WFF could support.

Now that the Runtime has been formally integrated into the Android platform, I see a longer-term need to move beyond the dependency on Views, both for watch performance and for the extensibility of the standard itself.

The Articles in This Series

The design details are divided into three articles.

I hope this experience helps developers considering XSD for an XML specification assess its suitability and trade-offs.


References — examples of tools that generate JSON Schema from XSD: xsd2jsonschema, JSON Schema generation in Jsonix Schema Compiler.

  • 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.