Merge pull request #25 from refractproject/zdne/add-variables-examples

smizell · smizell · commit c5280bb2dc2c · 2015-05-27T16:27:12.000+02:00
Add variables examples
diff --git a/namespaces/mson-namespace.md b/namespaces/mson-namespace.md
@@ -1,35 +1,37 @@
 # MSON Namespace
 
-This document extends [Refract][] Specification with new element types necessary to build [MSON][] DOM.
+This document extends [Refract][] Specification with new element types necessary to build [MSON][] Refract.
 
 ## Content
 
 <!-- TOC depth:3 withLinks:1 updateOnSave:0 -->
 - [MSON Namespace](#mson-namespace)
-    - [Content](#content)
-    - [About this Document](#about-this-document)
-    - [Expanded Element](#expanded-element)
-    - [Base Element](#base-element)
-        - [Type comparison](#type-comparison)
-- [MSON DOM Elements](#mson-dom-elements)
-    - [MSON Element (Element)](#mson-element-element)
-        - [Properties](#properties)
-    - [Boolean Type (Boolean Element)](#boolean-type-boolean-element)
-    - [String Type (String Element)](#string-type-string-element)
-    - [Number Type (Number Element)](#number-type-number-element)
-    - [Array Type (Array Element)](#array-type-array-element)
-    - [Object Type (Object Element)](#object-type-object-element)
-    - [Enum Type (MSON Element)](#enum-type-mson-element)
-        - [Properties](#properties)
-        - [Examples](#examples)
-    - [Examples](#examples)
-        - [Anonymous Object Type](#anonymous-object-type)
-        - [Type Attributes](#type-attributes)
-        - [Default Value](#default-value)
-        - [One Of](#one-of)
-        - [Mixin](#mixin)
-        - [Named Type](#named-type)
-
+	- [Content](#content)
+	- [About this Document](#about-this-document)
+	- [Expanded Element](#expanded-element)
+	- [Base Element](#base-element)
+		- [Type comparison](#type-comparison)
+- [MSON Refract Elements](#mson-refract-elements)
+	- [MSON Element (Element)](#mson-element-element)
+		- [Properties](#properties)
+	- [Boolean Type (Boolean Element)](#boolean-type-boolean-element)
+	- [String Type (String Element)](#string-type-string-element)
+	- [Number Type (Number Element)](#number-type-number-element)
+	- [Array Type (Array Element)](#array-type-array-element)
+	- [Object Type (Object Element)](#object-type-object-element)
+	- [Enum Type (MSON Element)](#enum-type-mson-element)
+		- [Properties](#properties)
+		- [Examples](#examples)
+	- [Examples](#examples)
+		- [Anonymous Object Type](#anonymous-object-type)
+		- [Type Attributes](#type-attributes)
+		- [Default Value](#default-value)
+		- [One Of](#one-of)
+		- [Mixin](#mixin)
+		- [Named Type](#named-type)
+		- [Variable Value](#variable-value)
+		- [Variable Property Name](#variable-property-name)
+		- [Variable Type Name](#variable-type-name)
 <!-- /TOC -->
 
 ## About this Document
@@ -46,15 +48,15 @@ MSON is built around the idea of defining recursive data structures. To provide
 
 By default, Refract does not enforce inheritance of data, though element defintions are inherited from the defined element types. To inherit data in Refract, the `extend` element is used to merge one or more elements into a final element. In the MSON namespace, however, when the data is defined, it inherits data from the element definition. MSON itself uses inheritance this way, and the MSON Refract namespace mimics the behavior to provide simplicity and consistency across MSON representations.
 
-Often, before an MSON DOM can be processed, referenced _Named Types_ have to be resolved. Resolving references to _Named Types_ is tedious and error prone. As such an MSON processor can resolve references to produce a complete MSON DOM. That is, a DOM that does not include unresolved references to other data structures. This is referred to as _reference expansion_ or simply _expansion_.
+Often, before an MSON Refract can be processed, referenced _Named Types_ have to be resolved. Resolving references to _Named Types_ is tedious and error prone. As such an MSON processor can resolve references to produce a complete MSON Refract. That is, a Refract that does not include unresolved references to other data structures. This is referred to as _reference expansion_ or simply _expansion_.
 
 In other words, an expanded element is one that does not contain any _Identifier_ (defined below) referencing any other elements than those defined in MSON namespaces.
 
-The expanded DOM MUST, however, keep the track of what data structure was expanded and what from where.
+The expanded Refract MUST, however, keep the track of what data structure was expanded and what from where.
 
 ## Base Element
 
-In MSON, every data structure is a sub-type of another data structure, and, therefore, it is directly or indirectly derived from one of the MSON _Base Types_. This is expressed as an inheritance of elements in MSON DOM. Where the predecessor of an element is referred to as element's _Base Element_.
+In MSON, every data structure is a sub-type of another data structure, and, therefore, it is directly or indirectly derived from one of the MSON _Base Types_. This is expressed as an inheritance of elements in MSON Refract. Where the predecessor of an element is referred to as element's _Base Element_.
 
 Note: Not every MSON _Base Type_ is presented in Refract primitive types and vice versa – see the table below.
 
@@ -70,15 +72,15 @@ Note: Not every MSON _Base Type_ is presented in Refract primitive types and vic
 |     object     |  Object Element  |     object     |   Object Type  |
 |      null      |   Null Element   |        -       |        -       |
 
-# MSON DOM Elements
+# MSON Refract Elements
 
-## MSON Element (Element[*T*])
+## MSON Element (Element)
 
 Base element for every MSON element.
 
 The MSON Element adds attributes representing MSON _Type Definition_ and _Type Sections_.
 
-Note: In MSON DOM _Nested Member Types_ _Type Section_ is the `content` of the element.
+Note: In MSON Refract _Nested Member Types_ _Type Section_ is the `content` of the element.
 
 ### Properties
 
@@ -91,21 +93,23 @@ Note: In MSON DOM _Nested Member Types_ _Type Section_ is the `content` of the e
             - sample - The `content` value is a sample value.
             - default - The `content` value is a default value.
 
-    - `variable` (boolean) - The `content` value is a _Variable Value_
+    - `variable` (boolean)
+
+      The `content` value is either a _Variable Type Name_, or _Variable Property Name_.
 
-      The `content` value is either a _Variable Type Name_, _Variable Value_ or _Variable Property Name_.
+      Note, if the `content` is a _Variable Value_ the `sample` type attribute
+      should be used instead (see `typeAttributes`).
 
-    - `sample` (array[T]) - Alternative sample value for _Member Types_
+    - `sample` (array) - Alternative sample value for _Member Types_
 
 		  The type of items in `sample` array attribute MUST match the type of element's `content`.
 
-    - `default` (T) - Default value for _Member Types_
+    - `default` - Default value for _Member Types_
 
 		  The type of of `default` attribute MUST match the type of element's `content`.
 
     - `validation` - Not used, reserved for a future use
 
-- `content` (T)
 
 ## Boolean Type (Boolean Element)
 
@@ -146,7 +150,7 @@ Enumeration type. Exclusive list of possible elements. The elements in content's
     - green
 ```
 
-#### MSON DOM
+#### MSON Refract
 
 ```json
 {
@@ -182,7 +186,7 @@ Enumeration type. Exclusive list of possible elements. The elements in content's
 - id: 42
 ```
 
-#### MSON DOM
+#### MSON Refract
 
 ```json
 {
@@ -207,7 +211,7 @@ Enumeration type. Exclusive list of possible elements. The elements in content's
 - id: 42 (required, fixed)
 ```
 
-#### MSON DOM
+#### MSON Refract
 
 ```json
 {
@@ -239,7 +243,7 @@ Enumeration type. Exclusive list of possible elements. The elements in content's
     - default: 0
 ```
 
-#### MSON DOM
+#### MSON Refract
 
 ```json
 {
@@ -270,7 +274,7 @@ Enumeration type. Exclusive list of possible elements. The elements in content's
     - province
 ```
 
-#### MSON DOM
+#### MSON Refract
 
 ```json
 {
@@ -322,7 +326,7 @@ Enumeration type. Exclusive list of possible elements. The elements in content's
 - Include User
 ```
 
-#### MSON DOM
+#### MSON Refract
 
 Using the `ref` element to reference an the content of an element.
 
@@ -386,7 +390,7 @@ Description is here! Properties to follow.
 - street
 ```
 
-#### MSON DOM
+#### MSON Refract
 
 ```json
 {
@@ -409,6 +413,8 @@ Description is here! Properties to follow.
 
 ### Referencing & Expansion
 
+#### MSON
+
 ```markdown
 # User (object)
 - name
@@ -417,6 +423,8 @@ Description is here! Properties to follow.
 - id
 ```
 
+#### MSON Refract
+
 ```json
 {
     "element": "object",
@@ -451,7 +459,7 @@ Description is here! Properties to follow.
 }
 ```
 
-#### Expanded
+#### Expanded MSON Refract
 
 ```json
 {
@@ -489,6 +497,63 @@ Description is here! Properties to follow.
 }
 ```
 
+### Variable Value
+
+#### MSON
+
+```markdown
+- p: *42*
+```
+
+#### MSON Refract
+
+```json
+["object", {}, {}, [
+  ["string", {"name": "p"}, {"typeAttributes": ["sample"]}, 42]
+]]
+```
+
+### Variable Property Name
+
+#### MSON
+
+```markdown
+- *rel (Relation)*
+```
+
+#### MSON Refract
+
+```json
+["object", {}, {}, [
+  ["string",
+    {"name": ["Relation", {}, {"variable": true}, "rel" ] },
+    {},
+    null]
+]]
+```
+
+### Variable Type Name
+
+**Proposal – not yet implemented**
+
+Note this needs an introduction of a new MSON namespace element for any type - `generic`.
+
+#### MSON
+
+```markdown
+- p (array[*T*])
+```
+
+#### MSON Refract
+
+```json
+["object", {}, {}, [
+  ["array",  {"name": "p"}, {}, [
+    ["generic", {}, {}, "T"]
+  ]]
+]]
+```
+
 ---
 
 [Refract]: https://github.com/refractproject/refract-spec/blob/master/refract-spec.md
