Add human-readable specification document

2026-05-27 15:16:53 +01:00
parent e5665a40ca
commit 73ffa17524
2 changed files with 184 additions and 1 deletions
@@ -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.