markembling/palette-spec
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

Add human-readable specification document

Browse Source
This commit is contained in:
Mark Embling
2026-05-27 15:16:53 +01:00
parent e5665a40ca
commit 73ffa17524
2 changed files with 184 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+12 -1
View File
@@ -1,7 +1,15 @@
# Palette Format Specification
This repository contains the specification for the Palette XML format, a simple
format for representing colour palettes.
format for representing colour palettes. The specification consists of a
human-readable document and an XSD schema.
## Contents
- [`spec.md`](spec.md) — The human-readable specification
- [`palette.xsd`](palette.xsd) — The XSD schema for document validation
## Overview
@@ -21,6 +29,7 @@ This namespace identifies version 1 of the format. A new namespace will be
introduced only if a future version of the format introduces breaking changes.
Backwards-compatible additions do not result in a new namespace.
## Versioning
This specification follows [Semantic Versioning](https://semver.org/):
@@ -36,6 +45,7 @@ element of [`palette.xsd`](palette.xsd).
Git tags correspond directly to specification versions and are prefixed with `v`
(e.g. `v1.0.0`, `v1.1.0`).
## Licence
This specification is copyright Mark Embling and is licensed under
@@ -44,6 +54,7 @@ This specification is copyright Mark Embling and is licensed under
You are free to share and adapt the specification for any purpose, provided you give
appropriate attribution and distribute any derivative specifications under the same licence.
### Implementing this Specification
Implementing this specification in software — including commercial software — is
spec.md
+172
View File
@@ -0,0 +1,172 @@
# 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.