From ea66f812cff18a0b8191d9fff25661c2e55ba84d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kat=20March=C3=A1n?= <kzm@zkat.tech>
Date: Mon, 30 Aug 2021 20:21:22 -0700
Subject: [PATCH] ready for review

---
 SCHEMA-SPEC.md          | 61 +++++++++++++++++++++++++++++++++++++++--
 examples/kdl-schema.kdl |  2 --
 2 files changed, 58 insertions(+), 5 deletions(-)

diff --git a/SCHEMA-SPEC.md b/SCHEMA-SPEC.md
index c40dc35..bee260c 100644
--- a/SCHEMA-SPEC.md
+++ b/SCHEMA-SPEC.md
@@ -6,6 +6,11 @@ constrain the allowed semantics of a KDL document. This can be used for many
 purposes: documentation for users, automated verification, or even automated
 generation of bindings!
 
+## The Formal Schema
+
+For the full KDL Schema schema itself, see
+[examples/kdl-schema.kdl](./examples/kdl-schema.kdl).
+
 ## Definition
 
 ### `document` node
@@ -51,10 +56,60 @@ another node.
 * [`children`](#children-node) - zero or more children for this node.
 
 ### `prop` node
+
+Represents a property of a node, which is a key/value pair in KDL.
+
+#### Values
+
+* `key` (optional) - String key for the property. If this value is missing, the `prop` node's attributes will apply to all properties of its parent.
+
+#### Properties
+
+* `description` (optional): An informational description of the purpose of this property.
+* `id` (optional): A globally unique identifier for this property.
+* `ref` (optional): A globally unique reference to another property's ID. If present, all properties defined in the target property will be copied to this property, replacing any conflicts.
+
+#### Children
+
+* `type` (optional): A string denoting the type of the property value.
+* `enum` (optional): A specific list of allowed values for this property. May be heterogenous as long as it agrees with the `type`, if specified.
+* `required` (optional): A boolean value indicating whether this property is required.
+
 ### `value` node
+
+Used to describe one or more values for a KDL node.
+
+#### Values
+
+None.
+
+#### Properties
+
+* `description` (optional): An informational description of the purpose of this value.
+* `id` (optional): A globally unique identifier for this value.
+* `ref` (optional): A globally unique reference to another value's ID. If present, all values defined in the target value will be copied to this value, replacing any conflicts.
+
+#### Children
+
+* `type` (optional): A string denoting the type of the value.
+* `enum` (optional): A specific list of allowed values for this value. May be heterogenous as long as it agrees with the `type`, if specified.
+* `min` (optional): Minimum number of values allowed.
+* `max` (optional): Maximum number of values allowed.
+
 ### `children` node
 
-## The Schema
+Denotes KDL node children.
 
-For the full KDL Schema schema itself, see
-[examples/kdl-schema.kdl](./examples/kdl-schema.kdl).
+#### Values
+
+None.
+
+#### Properties
+
+* `description` (optional): An informational description of the purpose of this children block.
+* `id` (optional): A globally unique identifier for this children block.
+* `ref` (optional): A globally unique reference to another children block's ID. If present, all children defined in the target children block will be copied to this children block, replacing any conflicts.
+
+#### Children
+
+* [`node`](#node-node) - zero or more child nodes.
diff --git a/examples/kdl-schema.kdl b/examples/kdl-schema.kdl
index 00acbd1..471683b 100644
--- a/examples/kdl-schema.kdl
+++ b/examples/kdl-schema.kdl
@@ -43,8 +43,6 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c
                     node "prop" description="A node property key/value pair." {
                         value description="The property key." {
                             type "string"
-                            min 1
-                            max 1
                         }
                         prop "id" description="A globally-unique ID of this property." {
                             type "string"