palette-spec/spec.md

Palette Format Specification

Version: 1.0.0
Namespace: http://markembling.info/xmlschema/colourchooser/palette/1

1. Introduction

The Palette format is a simple XML vocabulary for representing colour palettes. A palette is a collection of named colour entries, each carrying component values for red, green, blue, and opacity.

The format is intentionally minimal. It is designed to be straightforward to produce and consume, and to serve as a portable interchange format between colour-related applications and tools.

2. Conformance

The key words in this document are to be interpreted as follows:

• Must — an absolute requirement of the specification.
• Must not — an absolute prohibition.
• Should — recommended but not required; there may be valid reasons to deviate.
• May — optional; permitted but not required.

A conformant document is an XML document that satisfies all requirements in this specification and validates against the accompanying XSD schema.

A conformant application correctly reads and/or produces conformant documents. A conformant consuming application must correctly process all elements defined in this specification, and should preserve unrecognised elements or content rather than treating their presence as an error. Unrecognised content may be discarded during a deserialisation/serialisation cycle but must not be treated as a fatal error.

This document is the human-readable specification for the format. In the event of any conflict between this document and the schema, this document is authoritative as to intent; the schema should be updated to reflect it.

3. Namespace

The XML namespace for this format is:

http://markembling.info/xmlschema/colourchooser/palette/1

All elements in a conformant document must be in this namespace. The recommended practice is to declare it as the default namespace on the root element, as shown in the examples throughout this document.

The trailing 1 in the namespace URI identifies the major version of the format. The namespace will change only if a future version introduces breaking changes; backwards-compatible additions do not result in a new namespace.

4. Format Overview

A Palette document contains a single root palette element enclosing zero or more colour elements. Each colour element represents a single named colour entry with red, green, blue, and opacity component values.

<?xml version="1.0" encoding="UTF-8"?>
<palette xmlns="http://markembling.info/xmlschema/colourchooser/palette/1">
  <colour>
    <name>Leaf Green</name>
    <r>89</r>
    <g>124</g>
    <b>0</b>
    <opacity>100</opacity>
  </colour>
  <colour>
    <name>Sunset Orange</name>
    <r>242</r>
    <g>186</g>
    <b>2</b>
    <opacity>100</opacity>
  </colour>
  <colour>
    <name>Misty White</name>
    <r>246</r>
    <g>246</g>
    <b>246</b>
    <opacity>25</opacity>
  </colour>
</palette>

5. Element Reference

5.1 palette

The root element of every Palette document.

Attributes: None.

Content: Zero or more colour elements. Document order is significant and must be preserved by applications. An empty palette is valid.

5.2 colour

Represents a single named colour entry within a palette.

Attributes: None.

Content: The following child elements, each of which must appear exactly once and may appear in any order:

• name
• r
• g
• b
• opacity

5.3 name

The human-readable name of the colour entry, intended as a display label. Applications must not derive colour component values from its content.

Content: A string. Free-form text with no prescribed format, character restrictions, or length constraints beyond those of XML character data. An empty name is valid, though producers should provide a meaningful name wherever possible.

5.4 r (Red)

The red component of the colour in the RGB colour model.

Content: A non-negative integer in the range 0–255 inclusive, where 0 represents the absence of the component and 255 represents full intensity.

5.5 g (Green)

The green component of the colour in the RGB colour model.

Content: A non-negative integer in the range 0–255 inclusive. See r.

5.6 b (Blue)

The blue component of the colour in the RGB colour model.

Content: A non-negative integer in the range 0–255 inclusive. See r.

5.7 opacity

The opacity of the colour, expressed as a percentage, where 0 is fully transparent and 100 is fully opaque.

Content: A non-negative integer in the range 0–100 inclusive.

6. File Conventions

The conventional file extension for Palette documents is .ccxml (Colour Chooser XML), a reference to the first application to use this format. This extension is in established use and should be treated as the standard convention. The .xml extension is also acceptable where a format-specific extension is not appropriate or supported.

Palette documents should be encoded in UTF-8. The XML declaration is recommended but not required.