Add human-readable specification document

README.md

@@ -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

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