ready for review

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.

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"