From 34af4dd794c682d1f672b1b3fb97671a9ddb3bd6 Mon Sep 17 00:00:00 2001
From: James Nash <cirrus@twiddles.com>
Date: Sat, 8 Jan 2022 00:41:50 +0000
Subject: [PATCH] wip: started data-model section

---
 technical-reports/format/data-model.md       | 19 +++++++++++++++++++
 technical-reports/format/data-model.svg      |  3 +++
 technical-reports/format/index.html          |  5 +++++
 technical-reports/format/parse-serialize.svg |  3 +++
 4 files changed, 30 insertions(+)
 create mode 100644 technical-reports/format/data-model.md
 create mode 100644 technical-reports/format/data-model.svg
 create mode 100644 technical-reports/format/parse-serialize.svg

diff --git a/technical-reports/format/data-model.md b/technical-reports/format/data-model.md
new file mode 100644
index 0000000..6fdeb84
--- /dev/null
+++ b/technical-reports/format/data-model.md
@@ -0,0 +1,19 @@
+# Data model
+
+There are 2 kinds of entities that this spec defines: Groups and design tokens. Together, they form a tree data structure. The root node is always a group. Group nodes can contain child nodes which are either other groups or design tokens. Design tokens nodes cannot have children and are therefore always leaf nodes.
+
+<figure>
+
+![Diagram depicting an example tree structure made of group and design token nodes](./data-model.svg)
+
+  <figcaption>Visual representation of an example tree structure consisting of group and design token nodes</figcaption>
+</figure>
+
+The file format defined by this specification is a serialisation of that data structure.
+
+<figure>
+
+![Diagram of a file on one side and a group and desing token tree on the other. An arrow pointing from the file to the data structure is labelled "parse". Another arrow pointing in the opposite direction is labelled "serialize".](./parse-serialize.svg)
+
+  <figcaption>Illustration of the relationship between a design token file and the corresponding data model</figcaption>
+</figure>
diff --git a/technical-reports/format/data-model.svg b/technical-reports/format/data-model.svg
new file mode 100644
index 0000000..e2f5a31
--- /dev/null
+++ b/technical-reports/format/data-model.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="473px" height="322px" viewBox="-0.5 -0.5 473 322"><defs/><g><rect x="221" y="21" width="80" height="40" fill="#dae8fc" stroke="#6c8ebf" stroke-width="2" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 41px; margin-left: 222px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 16px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; font-weight: bold; white-space: normal; overflow-wrap: normal;">Group</div></div></div></foreignObject><text x="261" y="46" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="16px" text-anchor="middle" font-weight="bold">Group</text></switch></g><rect x="71" y="141" width="80" height="40" fill="#dae8fc" stroke="#6c8ebf" stroke-width="2" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 161px; margin-left: 72px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 16px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; font-weight: bold; white-space: normal; overflow-wrap: normal;">Group</div></div></div></foreignObject><text x="111" y="166" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="16px" text-anchor="middle" font-weight="bold">Group</text></switch></g><path d="M 261 61 L 261 101 L 111 101 L 111 141" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><rect x="271" y="141" width="80" height="40" rx="6" ry="6" fill="#ffe6cc" stroke="#d79b00" stroke-width="2" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 161px; margin-left: 272px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 16px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; font-weight: bold; white-space: normal; overflow-wrap: normal;">Token</div></div></div></foreignObject><text x="311" y="166" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="16px" text-anchor="middle" font-weight="bold">Token</text></switch></g><path d="M 261 61 L 261 101 L 311 101 L 311 141" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><path d="M 211 141 L 211 101 L 261 101 L 261 61" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><rect x="171" y="141" width="80" height="40" rx="6" ry="6" fill="#ffe6cc" stroke="#d79b00" stroke-width="2" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 161px; margin-left: 172px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 16px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; font-weight: bold; white-space: normal; overflow-wrap: normal;">Token</div></div></div></foreignObject><text x="211" y="166" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="16px" text-anchor="middle" font-weight="bold">Token</text></switch></g><path d="M 411 141 L 411 101 L 261 101 L 261 61" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><rect x="371" y="141" width="80" height="40" rx="6" ry="6" fill="#ffe6cc" stroke="#d79b00" stroke-width="2" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 161px; margin-left: 372px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 16px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; font-weight: bold; white-space: normal; overflow-wrap: normal;">Token</div></div></div></foreignObject><text x="411" y="166" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="16px" text-anchor="middle" font-weight="bold">Token</text></switch></g><rect x="21" y="261" width="80" height="40" rx="6" ry="6" fill="#ffe6cc" stroke="#d79b00" stroke-width="2" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 281px; margin-left: 22px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 16px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; font-weight: bold; white-space: normal; overflow-wrap: normal;">Token</div></div></div></foreignObject><text x="61" y="286" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="16px" text-anchor="middle" font-weight="bold">Token</text></switch></g><path d="M 111 181 L 111 221 L 61 221 L 61 261" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><path d="M 161 261 L 161 221 L 111 221 L 111 181" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><rect x="121" y="261" width="80" height="40" rx="6" ry="6" fill="#ffe6cc" stroke="#d79b00" stroke-width="2" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 281px; margin-left: 122px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 16px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; font-weight: bold; white-space: normal; overflow-wrap: normal;">Token</div></div></div></foreignObject><text x="161" y="286" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="16px" text-anchor="middle" font-weight="bold">Token</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://www.diagrams.net/doc/faq/svg-export-text-problems" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Text is not SVG - cannot display</text></a></switch></svg>
\ No newline at end of file
diff --git a/technical-reports/format/index.html b/technical-reports/format/index.html
index f07f502..e537c6c 100644
--- a/technical-reports/format/index.html
+++ b/technical-reports/format/index.html
@@ -145,6 +145,11 @@ <h1>Introduction</h1>
       data-include-format="markdown"
     ></section>
 
+    <section
+      data-include="./data-model.md"
+      data-include-format="markdown"
+    ></section>
+
     <section
       data-include="./design-token.md"
       data-include-format="markdown"
diff --git a/technical-reports/format/parse-serialize.svg b/technical-reports/format/parse-serialize.svg
new file mode 100644
index 0000000..a17ec54
--- /dev/null
+++ b/technical-reports/format/parse-serialize.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="663px" height="262px" viewBox="-0.5 -0.5 663 262"><defs/><g><path d="M 21 21 L 111 21 L 141 51 L 141 191 L 21 191 L 21 21 Z" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><path d="M 111 21 L 111 51 L 141 51 Z" fill-opacity="0.05" fill="#000000" stroke="none" pointer-events="none"/><path d="M 111 21 L 111 51 L 141 51" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe center; width: 137px; height: 1px; padding-top: 26px; margin-left: 5px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 16px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;"><div style="font-size: 12px" align="left"><font style="font-size: 12px">{</font></div><div style="font-size: 12px" align="left"><font style="font-size: 12px">  "group-1": {</font></div><div style="font-size: 12px" align="left"><font style="font-size: 12px">    "token-1": {</font></div><div style="font-size: 12px" align="left"><font style="font-size: 12px">      "value": 123</font></div><div style="font-size: 12px" align="left"><font style="font-size: 12px">    },</font></div><div style="font-size: 12px" align="left"><font style="font-size: 12px">    "token-2": {</font></div><div style="font-size: 12px" align="left"><font style="font-size: 12px">      "value": 321</font></div><div style="font-size: 12px" align="left"><font style="font-size: 12px">   }</font></div><div style="font-size: 12px" align="left"><font style="font-size: 12px">   ...</font></div><div style="font-size: 12px" align="left"><font style="font-size: 12px">}<br /></font></div><font style="font-size: 12px"><br /></font></div></div></div></foreignObject><text x="74" y="42" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="16px" text-anchor="middle">{...</text></switch></g><rect x="501" y="21" width="40" height="30" fill="#dae8fc" stroke="#6c8ebf" stroke-width="2" pointer-events="none"/><rect x="421" y="91" width="40" height="30" fill="#dae8fc" stroke="#6c8ebf" stroke-width="2" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 106px; margin-left: 422px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 16px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; font-weight: bold; white-space: normal; overflow-wrap: normal;"><div><br /></div></div></div></div></foreignObject><text x="441" y="111" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="16px" text-anchor="middle" font-weight="bold">&#xa;</text></switch></g><path d="M 521 51 L 521 71 L 441 71 L 441 91" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><rect x="541" y="91" width="40" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#d79b00" stroke-width="2" pointer-events="none"/><path d="M 521 51 L 521 71 L 561 71 L 561 91" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><path d="M 501 91 L 501 71 L 521 71 L 521 51" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><rect x="481" y="91" width="40" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#d79b00" stroke-width="2" pointer-events="none"/><path d="M 621 91 L 621 71 L 521 71 L 521 51" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><rect x="601" y="91" width="40" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#d79b00" stroke-width="2" pointer-events="none"/><rect x="391" y="161" width="40" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#d79b00" stroke-width="2" pointer-events="none"/><path d="M 441 121 L 441 141 L 411 141 L 411 161" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><path d="M 471 161 L 471 141 L 441 141 L 441 121" fill="none" stroke="rgb(0, 0, 0)" stroke-width="2" stroke-miterlimit="10" pointer-events="none"/><rect x="451" y="161" width="40" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#d79b00" stroke-width="2" pointer-events="none"/><path d="M 370 119.91 L 370 130.91 L 192 130.91 L 192 141.91 L 172 125.41 L 192 108.91 L 192 119.91 Z" fill="#000000" stroke="none" pointer-events="none"/><path d="M 172 91.5 L 172 80.5 L 350 80.5 L 350 69.5 L 370 86 L 350 102.5 L 350 91.5 Z" fill="#000000" stroke="none" pointer-events="none"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 198px; height: 1px; padding-top: 61px; margin-left: 172px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 24px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Parse</div></div></div></foreignObject><text x="271" y="68" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="24px" text-anchor="middle">Parse</text></switch></g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 198px; height: 1px; padding-top: 151px; margin-left: 172px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 24px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Serialize</div></div></div></foreignObject><text x="271" y="158" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="24px" text-anchor="middle">Serialize</text></switch></g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 226px; margin-left: 22px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 24px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">File</div></div></div></foreignObject><text x="81" y="233" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="24px" text-anchor="middle">File</text></switch></g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 248px; height: 1px; padding-top: 226px; margin-left: 392px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 24px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Data model</div></div></div></foreignObject><text x="516" y="233" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="24px" text-anchor="middle">Data model</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://www.diagrams.net/doc/faq/svg-export-text-problems" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Text is not SVG - cannot display</text></a></switch></svg>
\ No newline at end of file