173 lines
5.0 KiB
Markdown
173 lines
5.0 KiB
Markdown
# 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
|
||
<?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.
|