· Woohyun Kim · Platform Engineering

WFF XML 스키마 설계 회고 2 — 정의의 구성과 작성 규칙

원자적으로 나눈 XSD 정의를 실제 프로젝트에서 관리한 방식을 설명합니다. 요소 계층과 의미 단위에 따른 파일 구성, 공통·지역 정의의 구분, 명명 규칙과 Preferences를 통한 입력 지원을 다룹니다.

앞선 글에서는 워치페이스 XML의 요소·속성·타입을 XSD로 정의하고 재사용하는 구조를 설명했습니다. 이 글에서는 그렇게 나눈 정의를 실제 프로젝트에서 어떻게 구성하고 관리했는지 설명합니다.

WFF 초기 설계의 중심 원칙은 가능한 한 원자적인 단위로 정의·재사용하는 것이었습니다. 정의의 단위를 작게 나누더라도 각각을 모두 별도 파일로 만들 필요는 없었습니다. 재사용할 정의의 단위와 함께 관리할 파일의 단위를 구분하고, 요소의 구성과 기능의 의미에 따라 배치하는 기준을 정했습니다.

정의와 파일의 분리 단위

XSD는 정의를 여러 파일로 나누고 참조할 수 있습니다. WFF에서는 요소가 계층적으로 구성되는 만큼, 정의 파일도 그 구성에 가깝게 배치하면 직관적으로 이해하고 관리할 수 있다고 판단했습니다.

공통 속성과 타입은 의미 단위로 묶어 별도 파일로 정의하고, 필요한 요소에서 xs:include로 참조했습니다. 그 요소에만 필요한 확장은 요소가 정의된 경로에서 추가할 수 있도록 했습니다. 공통 정의의 위치와 기능별 확장의 위치를 요소 계층에 맞춰 파악할 수 있게 한 것입니다.

파일 구성의 기준 경로는 wff/specification/documents/1이며, 아래는 관련 부분만 추린 구조입니다.

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

요소 정의: 구성 관계와 규모를 기준으로 분리하기

예를 들어 group/part/에는 Part의 공통 정의를 두고, draw/, image/, text/ 아래에 각 Part의 구체적인 정의를 배치했습니다. draw/ 내부에서는 도형을 shape/, 채우기와 선 스타일을 style/로 나누었습니다. 관련 정의를 요소의 구성과 기능에 따라 경로에서 찾을 수 있는 구조입니다.

파일은 의미와 규모가 있는 주요 요소를 기준으로 분리했습니다. 간단한 하위 요소는 상위 요소 안에 지역 요소로 선언해 파일 수를 줄이고 함께 검토할 수 있도록 했습니다. 정의의 규모가 커지거나 독립적으로 다룰 중요도가 높으면 별도 파일로 분리했습니다. 구체적인 경계는 요소의 의미와 규모에 따라 개발자가 판단할 수 있도록 했습니다.

속성·타입 정의: 의미 단위로 묶기

속성과 타입은 개별 이름마다 파일을 만드는 대신 공통된 의미를 기준으로 묶었습니다. 예를 들어 x, y, width, height는 각각 정의하되, 기하 정보를 표현한다는 공통점이 있어 geometricAttributes.xsd에서 함께 관리했습니다. 이 속성들을 조합하는 attributeGroup도 같은 파일에 배치했습니다.

개별 속성은 원자적으로 참조·재사용하면서, 관련 정의는 한 파일에서 검토할 수 있는 구성입니다. colorAttributes.xsd도 색상과 관련된 속성·타입을 함께 다루는 같은 방식의 사례입니다.

공통 정의와 지역적 정의의 범위

여러 요소에서 공유하는 정의는 common/에 배치했습니다. 기하 속성과 좌표·크기 타입은 common/attributes/, 공통 동작 요소인 Transform은 common/transform/에 있습니다. 특정 요소 계층과 관련된 정의는 group/renderModeType.xsd처럼 해당 기능의 경로에 두었습니다.

정의를 배치하는 경로와 선언 방식, 내부용임을 표시하는 이름은 다음 기준으로 구분했습니다.

구분 기준적용 방식목적
여러 요소에서 공유하는가, 특정 기능에 필요한가공통 정의는 common/, 기능별 정의와 확장은 해당 요소의 경로에 배치공통 정의를 유지하면서 확장과 관련된 변경을 해당 기능의 위치에서 관리
기능 내부에서 재사용하는가, 특정 선언에서만 사용하는가재사용할 정의에는 이름을 부여하고, 특정 선언에 한정되면 익명 타입 사용정의의 재사용 범위에 맞게 선언
이름 있는 정의가 내부 보조 용도인가이름에 _ 접두어 사용다른 기능에서 참조할 공통 정의와 구분

앞선 글의 Expressions 내부 Expression은 특정 선언의 익명 타입에서 공통 표현식 타입을 확장한 사례입니다. 속성에서는 Transform.mode의 TO, BY 값을 해당 속성 안의 익명 타입으로 정의했습니다.

내부 보조 정의의 _ 접두어

기능 내부에서만 사용할 이름 있는 정의에는 _ 접두어를 붙였습니다. arithmeticExpressionType.xsd의 _operatorType, _functionType, _arithmeticType 등이 이에 해당합니다.

이 규칙은 XSD에서 이름 있는 내부 정의를 은닉할 수 없다는 한계 때문에 필요했습니다. 같은 네임스페이스의 정의를 xs:include로 포함하면 보조 타입도 함께 노출됩니다. 파일·디렉터리 단위의 사용 범위를 스키마로 강제할 수 없어, 이름을 통해 해당 기능 내부에서 사용할 선언임을 표시했습니다.

이름으로 정의의 종류 구분하기

파일명에는 낙타 표기법(camelCase)을 사용하고, 접미사로 정의의 종류를 구분하도록 했습니다. 표기법 자체에 특별한 기술적 의미를 부여하기보다 파일의 대상을 일관되게 파악하기 위한 규칙이었습니다.

정의 종류접미사파일 예시
요소Element, ElementspartImageElement.xsd, transformElements.xsd
속성Attribute, AttributesalignmentAttribute.xsd, geometricAttributes.xsd
타입Type, TypesunsignedCharacterType.xsd, primitiveListTypes.xsd

요소 파일은 PartImage의 partImageElement.xsd처럼 대표하는 요소의 이름으로 작명했습니다. 간단한 하위 요소를 중첩해 정의하더라도 파일명은 대표 요소를 기준으로 했습니다. 속성·타입 파일은 geometricAttributes.xsd처럼 정의를 묶는 의미를 기준으로 작명했습니다. 여러 속성·타입이나 속성 그룹을 함께 정의하면 복수형을 사용했습니다.

이는 초기 설계에서 지향한 명명 기준입니다. 공개 버전 1에는 clock/hourHand.xsd처럼 Element 접미사를 사용하지 않은 파일도 있습니다.

Preferences: 자주 사용하는 값의 입력 지원

워치페이스 XML에서 투명도를 지정할 때, 완전 투명·중간 수준·완전 불투명에 해당하는 0, 128, 255를 입력 후보에서 쉽게 선택할 수 있도록 하고자 했습니다. Preferences 접미사는 이처럼 XML 작성에 자주 사용하는 값을 IDE가 제안하도록 하기 위한 정의에 사용했습니다. XML을 직접 작성하는 개발자의 편의를 위한 일종의 sugar였습니다.

이를 위해 colorAttributes.xsd에서는 0부터 255까지의 정수를 허용하는 unsignedCharacterType을 기반으로 선호 값 세 개를 _colorValuePreferences에 나열했습니다.

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

_colorValuePreferences 자체는 세 값으로 제한되지만, 실제 alpha 속성은 이를 원래의 unsignedCharacterType과 조합한 타입을 사용합니다. 따라서 선호 목록에 없는 alpha="64"도 유효하고, 공통 타입의 범위를 벗어난 alpha="256"은 허용되지 않습니다.

이렇게 값의 허용 범위를 유지하면서 자주 쓰는 입력 후보를 스키마에 표현했습니다. 후보를 제안하는 구체적인 동작은 IDE의 스키마 지원에 따라 달라질 수 있습니다. 이름의 _는 내부 보조 정의임을, Preferences는 입력 지원 목적을 표시합니다.

시리즈 목차


코드 출처: 공개 WFF XSD 버전 1, Copyright 2023 Samsung Electronics Co., Ltd, Apache License 2.0. 파일 구조는 일부 경로만 표시했으며, 코드 발췌는 설명에 필요한 정의만 남겼습니다.

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