· Woohyun Kim · Platform Engineering

WFF XML 스키마 설계 회고 1 — 요소·속성·타입의 정의와 재사용

워치페이스 XML의 XSD 설계 원칙을 설명합니다. 렌더링·비렌더링 요소의 구분과 추상 타입의 확장, 공통 속성과 도메인 타입의 분리·재사용 구조를 정리합니다.

워치페이스 XML의 XSD 설계에서는 렌더링 scene과 동작을 표현할 요소·속성, 값의 타입과 구성 제약을 정의해야 합니다. 이 글에서는 머리말에서 소개한 설계·구현의 구체적인 내용을 설명합니다.

아날로그 워치페이스 XML 예시

먼저 워치페이스 제작자가 작성하는 간단한 XML을 보겠습니다.

watchface.xml — 아날로그 시계 예시
<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>

위 예시는 제작자가 WatchFace에 가상 캔버스의 크기를 지정하고, Scene 아래에 배경과 시계 눈금 이미지, AnalogClock의 시침·분침·초침을 배치해 아날로그 워치페이스를 구성하는 간단한 사례입니다. 각 요소의 위치와 크기는 x, y, width, height 속성으로 기술합니다.

Condition 내부의 Expression에는 하루 걸음 수([STEP_COUNT])가 5,000보 이상인지 판별하는 식을 선언하고 step_goal_reached라는 식별자를 부여했습니다. Compare는 이 식별자를 참조해, 5,000보를 달성했을 때만 하위의 배경 PartImage를 표시합니다.

배경의 PartImage에는 Transform을 선언해 하루 동안 경과한 초([SECONDS_IN_DAY])를 각도로 변환했습니다. 하루의 86,400초를 240으로 나누면 360도가 되므로, 표시된 배경은 이 각도에 따라 천천히 회전합니다. 눈금 이미지와 시계 바늘은 Condition 밖에 배치해 걸음 수와 관계없이 표시합니다. 눈금 이미지는 Transform 없이 고정된 상태로 배치합니다.

각 바늘 이미지는 투명 여백을 포함한 정사각형으로 준비하고, 이미지의 정중앙에 회전 중심을 맞춥니다. 시침은 180×180 크기로 (90, 90)에, 분침과 초침은 360×360 크기로 (0, 0)에 배치했습니다. 크기와 위치는 다르지만 회전 중심은 모두 캔버스 중앙인 (180, 180)에 일치합니다.

시간에 따른 회전은 각 hand 요소가 직접 지원하므로 별도의 동작 로직을 기술하지 않습니다. 한편 PartText로 디지털 시간을 표현하거나 PartImage로 시계 배경을 구성할 수도 있습니다. 이러한 Part의 위치·각도 등을 동적으로 변경하려면 뒤에서 설명할 Transform 요소로 동작을 기술할 수 있습니다.

이제 이 XML에서 사용할 요소와 속성, 값의 타입을 XSD로 어떻게 정의했는지 설명합니다. 코드 설명은 공개 버전 1을 기준으로 합니다.

요소·속성·타입의 정의

설계하면서 우선한 것은 유사한 정의가 기능별로 반복·확장되는 상황을 방지하는 일이었습니다. 같은 개념을 여러 곳에서 조금씩 다르게 정의하면 코드가 늘어나고, 각 정의의 차이와 적용 범위를 파악하기도 어려워집니다. 따라서 중복을 줄이면서 가독성과 정의의 명확성을 유지하기 위해 요소(element)·속성(attribute)·타입(type)을 분리하고 가능한 한 원자적인 단위로 정의·재사용하는 것을 핵심 원칙으로 정했습니다.

위치·크기·색상처럼 여러 요소가 공유하는 개념을 다음 세 단위로 나누었습니다.

정의 단위설계에서의 역할예시
요소scene의 구성과 기능·동작을 선언PartImage, HourHand, Transform
속성요소의 위치·크기·렌더링 파라미터 등을 기술x, y, width, height, alpha
타입값의 표현과 허용 범위, 요소의 구성 규칙을 정의dimensionType, argbHexadecimalType, AbstractPartType

여기서 원자적이라는 표현은 XSD의 타입 분류가 아니라 정의를 분리하는 설계 기준입니다. 수학적 정의에서 well-definedness를 중시하듯, 워치페이스 XSD에서도 개념의 의미가 사용처에 따라 달라지지 않고 명확하게 해석되도록 정의하고자 했습니다.

요소: 렌더링 구성과 동작 정의

요소는 렌더링 계층을 구성하는 요소와 그 동작을 기술하는 비렌더링 요소로 구분했습니다.

렌더링 계층을 구성하는 요소

디자인의 유연성을 위해 이미지·텍스트·도형을 표현하는 범용 요소를 두었습니다. 한편 워치페이스라는 도메인에서 반복적으로 필요한 시각 요소는 의미가 드러나는 요소로 정의했습니다.

구분대표 요소목적
범용 시각 요소PartImage, PartText, PartDraw이미지·텍스트·도형을 조합해 다양한 디자인을 구성
계층 컨테이너Group하위 렌더링 노드를 묶고 계층 단위로 구성
시계의 의미를 가진 요소HourHand, MinuteHand, SecondHand아날로그 시계의 시·분·초 바늘처럼 역할이 분명한 요소를 선언
시간 외 데이터의 표현ComplicationSlot, Complication워치페이스에 제공되는 다른 데이터를 이미지·텍스트 등으로 표현

Group은 렌더링 계층의 일부이지만 직접 픽셀을 그리지는 않습니다. 공개 groupElement.xsd에서는 하위 계층의 위치·크기·각도·색상에 영향을 주는 컨테이너로 설명합니다.

범용 요소는 다양한 디자인을 지원하고, 시계에 특화된 요소는 도메인 고유의 기능을 명시합니다. 예를 들어 HourHand는 시침을 표현하는 요소이며, ComplicationSlot은 데이터 표시를 위한 슬롯과 하위 Complication을 구성합니다.

XSD의 추상화와 타입 파생

XSD는 추상 요소와 추상 타입, 타입의 확장(extension)과 제약(restriction)을 지원합니다. 속성 선언과 속성 그룹, 데이터 타입 역시 이름을 부여해 재사용할 수 있습니다. 관련 개념은 W3C XML Schema Primer에서도 설명합니다.

예를 들어 AbstractPartType은 abstract="true"인 복합 타입입니다. PartDraw 요소의 타입은 xs:complexContent 안에서 xs:extension base="AbstractPartType"을 사용해 이를 확장합니다.

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

이 정의는 AbstractPartType의 공통 구성을 재사용하면서, PartDraw의 하위 요소로 DrawElement를 선언합니다. 타입의 파생 관계는 공통 정의를 재사용하는 방식이며, XML 요소의 부모·자식 포함 관계와는 구분됩니다.

추상 타입의 확장과 공통 속성의 조합은 객체지향 설계의 추상화·상속 관점을 명세에도 적용한 예입니다. 속성의 조합은 아래의 attributeGroup 사례에서 설명합니다.

비렌더링 요소: 런타임 동작을 선언하기

Transform, Gyro 같은 요소는 자신이 렌더링할 이미지를 정의하는 대신, 부모 렌더링 요소가 런타임 데이터에 따라 어떻게 동작할지 기술합니다.

렌더링 요소에 직접 선언한 위치·크기·각도 등의 속성은 기본적인 상태를 기술합니다. 반면 하위의 동작 요소는 런타임의 동적 조건이나 데이터에 따라 그 상태를 어떻게 변경할지 선언합니다.

  • Transform은 target으로 대상 속성을 지정하고, value에 표현식을 기술합니다.
  • Gyro는 센서 데이터를 사용하는 표현식으로 부모 Group이나 Part의 속성을 조정합니다.

이 구조로 정적인 scene 구성과 런타임 동작을 같은 문서에 선언할 수 있었습니다.

속성: 원자적 정의를 재사용하는 XSD 사례

좌표·크기 정의는 타입, 속성, 속성 그룹, 실제 사용처의 관계를 보여주는 대표 사례입니다. dimensionType을 공통 속성에서 참조하고, 속성 그룹을 조합해 범용 Part와 시계 바늘에 동일한 기하 속성을 적용합니다.

1. 값의 타입과 속성 선언을 분리하기

dimensionType.xsd는 정수 기반 좌표·크기의 타입을 정의합니다. geometricAttributes.xsd는 이 타입을 네 속성에서 참조합니다.

<!-- 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"/>

이 단계에서 속성의 이름과 값의 타입을 분리했습니다. 네 속성이 각각 정수 타입을 정의하지 않고 동일한 도메인 타입을 사용합니다.

2. 속성을 용도별로 묶고 조합하기

같은 파일에서 위치와 크기의 속성 그룹을 각각 정의하고, 두 그룹을 geometricAttributesRequired로 조합합니다. use="required"는 속성 선언을 참조하는 위치에서 지정합니다.

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

원본에는 필수 여부를 지정하지 않은 positionAttributes, sizeAttributes, geometricAttributes도 있습니다. 같은 속성 선언에 사용 조건을 부여해 필요한 그룹을 구성한 것입니다.

3. 서로 다른 요소에서 같은 정의 사용하기

AbstractPartType과 HourHand는 모두 이 속성 그룹을 참조합니다.

<xs:complexType name="AbstractPartType" abstract="true" block="restriction">
  <!-- 하위 요소 생략 -->
  <xs:attributeGroup ref="geometricAttributesRequired"/>
  <!-- 기타 속성 생략 -->
</xs:complexType>

<xs:element name="HourHand">
  <xs:complexType>
    <!-- 하위 요소와 resource 속성 생략 -->
    <xs:attributeGroup ref="geometricAttributesRequired"/>
    <!-- 기타 속성 생략 -->
  </xs:complexType>
</xs:element>

범용 Part를 확장하는 타입과 시침 요소가 같은 좌표·크기 규칙을 사용하면서도 각각의 기능은 별도로 정의합니다. 전체 참조 관계는 다음과 같습니다.

dimensionType
  ↑ type 참조
x, y, width, height
  ↑ ref 참조
positionAttributesRequired + sizeAttributesRequired
  ↑ 그룹 조합
geometricAttributesRequired
  ↑ 그룹 참조
AbstractPartType / HourHand의 타입

이는 상속이 아닌 속성의 조합입니다. 값의 타입과 개별 속성, 사용 조건, 사용처를 나누어 반복 선언을 줄인 구조입니다.

타입: WFF 도메인의 값과 제약을 정의하기

XSD는 xs:string, xs:integer, xs:float 같은 내장 타입을 제공합니다. 필요한 곳에서는 이를 그대로 사용하고, WFF의 도메인에 맞는 값이나 제약이 필요하면 별도의 타입으로 정의했습니다.

sourceType: 도메인별 값을 정의하고 조합하기

sourceType.xsd는 시간·언어·배터리·센서·건강 데이터 등의 source를 타입으로 나누어 정의합니다.

예를 들어 languageSourceType은 xs:string을 기반으로 언어 관련 식별자를 xs:enumeration으로 제한합니다. 시간 관련 source는 timeUnitSourceType과 _timeSourceType으로 나누고 timeSourceType에서 합칩니다. 마지막으로 sourceType이 여러 도메인의 타입을 조합합니다.

공개 정의의 타입 조합 관계를 요약하면 다음과 같습니다.

timeUnitSourceType + _timeSourceType
└── timeSourceType

timeSourceType, languageSourceType, batterySourceType, ...
└── sourceType  (xs:union)

도메인별 값의 집합을 각각 관리하면서, 필요한 범위를 xs:union으로 조합한 구조입니다.

예를 들어 다음 값들은 각 하위 타입에 정의되어 있으며, 이들을 조합한 sourceType에서도 모두 허용됩니다.

하위 타입에서 sourceType까지의 조합 경로허용되는 값의 예시
timeUnitSourceType → timeSourceType → sourceTypeSECOND, MINUTE
_timeSourceType → timeSourceType → sourceTypeSECONDS_IN_DAY, HOUR_0_23
languageSourceType → sourceTypeLANGUAGE_CODE
batterySourceType → sourceTypeBATTERY_PERCENT

앞선 배경 회전 예시의 [SECONDS_IN_DAY]도 이 정의를 사용합니다. 타입에서 허용하는 식별자는 SECONDS_IN_DAY이며, 표현식에서는 대괄호로 감싸 해당 데이터를 참조합니다.

argbHexadecimalType: 내장 타입에 도메인 제약 추가하기

colorAttributes.xsd의 argbHexadecimalType은 xs:string에서 파생한 타입입니다. xs:restriction 안에 xs:pattern을 두어 #AARRGGBB 또는 #RRGGBB 색상 표기를 위한 패턴 제약을 정의합니다.

예를 들어 #FF336699는 알파값을 포함한 #AARRGGBB 형식이고, #336699는 #RRGGBB 형식입니다. 두 문자열 모두 이 타입의 패턴에 부합합니다. 내장 문자열 타입에 색상 코드의 길이와 16진수 문자 제약을 추가한 것입니다.

arithmeticExpressionType: 런타임 동작을 표현식으로 기술하기

앞선 시계 바늘처럼 정해진 동작을 제공하는 요소 외에, 제작자가 런타임 동작을 직접 기술할 수 있는 표현식도 필요했습니다. 예를 들어 렌더링 요소 아래에 다음 Transform을 선언하면 초 단위 데이터로 부모 요소의 각도를 계산할 수 있습니다.

<Transform target="angle" value="[SECOND] * 6 + 180" />

[SECOND]는 현재 시각의 초 단위 데이터입니다. 여기에 6을 곱하고 180을 더해 각도를 구합니다. 이 수식은 공개 XSD 주석에도 제시되어 있습니다. Runtime은 런타임 데이터에 따라 표현식을 평가하고 결과를 target="angle"로 지정한 부모 요소의 속성에 적용합니다. Gyro도 센서 데이터를 사용하는 표현식으로 렌더링 요소의 동작을 기술합니다.

이러한 값을 명세하는 타입이 Transform.value에서 참조하는 arithmeticExpressionType입니다. arithmeticExpressionType.xsd에서는 표현식의 구성 항목을 각각 정의하고 다음과 같이 조합합니다.

source 데이터 · 연산자 · 함수 · 기호 · 문자열
  ↓ xs:union
_arithmeticType
  └── xs:list → _arithmeticListType

_arithmeticType + _arithmeticListType
  ↓ xs:union
arithmeticExpressionType

개별 구성 항목과 이를 나열한 목록을 조합해, 요소의 속성에서 참조할 표현식 타입으로 정의한 것입니다. 센서 기반 표현식도 같은 구조를 사용하되 source를 sensorSourceType으로 두어 gyroArithmeticExpressionType으로 정의합니다.

표현식에는 XML 마크업과 구분해야 하는 수학 기호가 포함될 수 있어, 공개 XSD 주석에도 필요한 경우 CDATA를 사용하도록 안내합니다. 요소의 문자 데이터에는 CDATA 구간을 사용할 수 있으며, Transform.value 같은 속성값의 <, &는 각각 &lt;, &amp;로 이스케이프합니다.

공통 정의와 지역적 확장

공통 정의에서 확장이 필요한 요구는 해당 기능의 범위에서 지역적으로 정의할 수 있도록 설계했습니다. 여러 기능이 공유하는 정의를 유지하면서도, 개별 기능에 필요한 세부 제약과 구성을 추가할 수 있도록 한 것입니다.

예를 들어 expressionsElement.xsd는 Expressions 내부에 지역 요소 Expression을 선언합니다. 이 요소의 익명 복합 타입에서는 앞서 설명한 공통 arithmeticExpressionType을 확장해, 표현식에 식별자를 부여하는 name 속성을 추가합니다. 같은 Condition 안의 Compare는 이 식별자를 expression 속성에 지정해 해당 표현식을 참조합니다. 앞선 XML 예시의 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>

표현식 값의 공통 정의는 유지하면서, 다른 선언에서 식별하고 참조하는 데 필요한 속성을 해당 지역 선언 안에서 추가한 사례입니다.

지역적 확장의 적용 기준과 정의 방식, 내부 보조 정의의 명명 규칙은 정의의 구성과 작성 규칙 편에서 설명합니다.

초기 설계의 제약: 적응형 레이아웃

공개 버전 1의 watchface.xsd는 width와 height로 가상 캔버스의 크기를 정의하고, 하위 요소는 이 가상 좌표계를 기준으로 위치와 크기를 기술합니다. 다만 물리 디스플레이의 해상도·화면비(aspect ratio)에 따라 노드 간 배치 관계를 바꾸는 적응형 레이아웃은 초기 범위에 포함하지 않았습니다. 예를 들어 1:1과 다른 화면비에서 요소를 서로 다른 관계로 재배치하는 규칙은 선언할 수 없었습니다.

당시 워치 하드웨어는 디스플레이의 형태와 화면비 차이가 크지 않아 적응형 레이아웃의 수요도 낮을 것으로 판단했습니다. 초기부터 이를 지원하면 포맷과 Runtime의 개발 복잡도가 증가하고, 제작자도 다양한 디스플레이에 맞는 배치 규칙을 결정해야 했습니다. 레이아웃을 제외하는 것은 초기 구현 비용과 제작자의 설계 부담을 함께 줄이는 선택이었습니다.

대신 가상 캔버스를 실제 디스플레이에 대응시킬 때는 Android의 scaleType="fitCenter"와 유사하게, 비율을 유지한 채 전체 구성이 디스플레이 안에 들어오도록 스케일링하고 중앙에 배치하는 묵시적 동작을 가정했습니다. 제작자는 해상도별 레이아웃을 따로 명세하지 않고 같은 구성을 사용할 수 있었습니다.

물리 디스플레이의 해상도, 가상 캔버스의 크기, 노드 간 배치 규칙은 각각 구분되는 설계 대상입니다. 초기 설계는 가상 좌표와 스케일링으로 대응하되 화면비에 따른 배치 관계의 변경은 지원하지 않는 것을 합리적인 제약으로 판단했습니다. 이후 하드웨어 다양성이나 사용 요구가 증가하면 후속 버전에서 레이아웃 요소를 확장 정의하는 방식을 고려했습니다.

명명에 대한 회고: Part 접두어

구체 Part의 요소 이름에는 공통 접두어 Part를 사용하도록 제안했습니다. 워치페이스 XML을 직접 작성하는 개발자가 관련 요소를 쉽게 찾을 수 있도록, 포맷의 discoverability를 고려한 결정이었습니다.

개발자가 ‘사용할 수 있는 Part에는 무엇이 있을까?’라고 생각하며 Part를 입력하면, IDE가 관련 요소를 함께 제안하는 흐름을 기대했습니다.

Part
├── PartDraw
├── PartImage
└── PartText

팀에서도 이 제안의 이유를 합리적이라고 보아 해당 명명 방식을 채택했습니다.

DrawPart, ImagePart, TextPart가 영어권 사용자에게 더 자연스러울 가능성도 고려했지만, 당시에는 공통 접두어를 통한 요소 탐색을 우선했습니다.

지금 돌이켜 생각해보면, IDE의 접두어 기반 탐색보다 영어 어순에 따른 명칭의 자연스러움을 우선해 DrawPart, ImagePart, TextPart처럼 Part를 접미사로 정의했을 것 같습니다.

시리즈 목차


코드 출처: 공개 WFF XSD 버전 1, Copyright 2023 Samsung Electronics Co., Ltd, Apache License 2.0. XSD 발췌는 설명에 필요한 부분만 남겼으며, watchface.xml과 Transform 사용 예시는 별도로 작성했습니다.

  • Wear OS
  • WFF
  • XML
  • XSD
  • Schema Design
Share:
블로그로 돌아가기