Merge pull request #36 from kylef/kylef/rfc-0002

Implementation of RFC0002

README.md

@@ -6,8 +6,7 @@ Refract is a recursive data structure for expressing complex structures, relatio
 
 - [Full Specification](refract-spec.md)
 - [Data Structure Namespace](namespaces/data-structure-namespace.md)
-- [Resource Namespace](namespaces/resource-namespace.md)
-- [API Namespace](namespaces/api-namespace.md)
+- [API Description Namespace](namespaces/api-description-namespace.md)
 
 ## Version
 

namespaces/resource-namespace.md → namespaces/api-description-namespace.md

@@ -1,11 +1,11 @@
-# Resource Namespace
+# API Description Namespace
 
 This document extends [Refract][] [Data Structure Namespace][] to define REST Resource data structure elements.
 
 ## Content
 
 <!-- TOC depth:3 withLinks:1 updateOnSave:0 -->
-- [Resource Namespace](#resource-namespace)
+- [API Description Namespace](#api-description-namespace)
     - [Content](#content)
     - [About this Document](#about-this-document)
     - [Supporting Data Types](#supporting-data-types)
@@ -17,6 +17,8 @@ This document extends [Refract][] [Data Structure Namespace][] to define REST Re
     - [Resource Elements](#resource-elements)
         - [Resource (Element)](#resource-element)
         - [Transition (Element)](#transition-element)
+        - [Category (Element)](#category-element)
+        - [Copy (Element)](#copy-element)
     - [Protocol-specific Elements](#protocol-specific-elements)
         - [HTTP Transaction (Element)](#http-transaction-element)
         - [HTTP Headers (Array Type)](#http-headers-array-type)
@@ -76,15 +78,15 @@ Arbitrary data asset.
             - messageBody - Asset is an example of message-body
             - messageBodySchema - Asset is an schema for message-body
 - `attributes` (object)
-    - `contentType` (string) - Optional media type of the asset
+    - `contentType` (string) - Optional media type of the asset. When this is unset, the content type SHOULD be inherited from the `Content-Type` header of a parent HTTP Message Payload
     - `href` (Href) - Link to the asset
 - `content` (string) - A textual representation of the asset
 
-## Resource Elements
+## API Description Elements
 
 ### Resource (Element)
 
-The Resource representation with its available transitions and attributes.
+The Resource representation with its available transitions and its data.
 
 #### Properties
 
@@ -162,18 +164,19 @@ Note: At the moment only the HTTP protocol is supported.
         If not set, the parent `resource` element `href` attribute SHOULD be
         used to resolve the target URI of the transition.
 
-    - `parameters` (Href Variables) - Input parameters.
+    - `hrefVariables` (Href Variables) - Input parameters.
 
         Definition of any input URI path segments or URI query parameters for this transition.
 
-        If `href` and `parameters` attributes aren't set, the parent `resource`
+        If `href` and `hrefVariables` attributes aren't set, the parent `resource`
         element `hrefVariables` SHOULD be used to resolve the transition input
         parameters.
 
-    - `attributes` (Data Structure) - Input attributes.
+    - `data` (Data Structure) - Input attributes.
 
         Definition of any input message-body attribute for this transition.
 
+    - `contentTypes` (array[String]) - A collection of content types that MAY be used for the transition.
 - `content` (array[HTTP Transaction]) - Array of transaction examples.
 
     Transaction examples are protocol-specific examples of REST transaction
@@ -195,6 +198,143 @@ Note: At the moment only the HTTP protocol is supported.
 }
 ```
 
+### Category (Element)
+
+Grouping element – a set of elements forming a logical unit of an API such as
+group of related resources or data structures.
+
+A category element MAY include additional classification of the category.
+The classification MAY hint what is the content or semantics of the category.
+The classification MAY be extended and MAY contain more than one classes.
+
+For example a `category` element may be classified both as `resourceGroup` and
+`dataStructures` to denote it includes both resource and data structures. It
+may also include the `transitions` classification to denote it includes
+transitions.
+
+#### Properties
+
+- `element`: category (string, fixed)
+- `meta`
+    - `class` (array, fixed)
+        - (enum[string])
+            - api - Category is a API top-level group.
+            - resourceGroup - Category is a set of resource.
+            - dataStructures - Category is a set of data structures.
+            - scenario - Reserved. Category is set of steps.
+            - transitions - Category is a group of transitions.
+- `attributes`
+    - `meta` (array[Member Element]) - Arbitrary metadata
+
+        Note the "class" of the Member Element can be used to distinguish the
+        source of metadata as follows:
+
+        - Class `user` - User-specific metadata. Metadata written in the source.
+        - Class `adapter` - Serialization-specific metadata. Metadata provided by adapter.
+
+- `content` (array[Element])
+
+#### Example
+
+```json
+{
+    "element": "category",
+    "meta": {
+        "class": [
+            "api"
+        ],
+        "title": "Polls API"
+    },
+    "attributes": {
+        "meta": [
+            {
+              "element": "member",
+              "meta": {
+                  "class": ["user"]
+              },
+              "content": {
+                  "key": {
+                      "element": "string",
+                      "content": "HOST",
+                  },
+                  "value": {
+                      "element": "string",
+                      "content": "http://polls.apiblueprint.org/"
+                  }
+              }
+            }
+        ]
+    },
+    "content": [
+        {
+            "element": "category",
+            "meta": {
+                "class": [
+                    "resourceGroup"
+                ],
+                "title": "Question",
+                "description": "Resources related to questions in the API."
+            },
+            "content": []
+        }
+    ]
+}
+```
+
+### Copy (Element)
+
+Copy element represents a copy text. A textual information in API description.
+Its content is a string and it MAY include information about the media type
+of the copy's content.
+
+If an element contains a Copy element, the element's `description` metadata
+MAY include the Copy element's content.
+
+The Copy element MAY appear as a content of any element defined in the base
+namespaces.
+
+#### Properties
+
+- `element`: copy (string, fixed)
+- `attributes` (object)
+    - `contentType`: *text/plain* (string) - Optional media type of the content.
+- `content` (string)
+
+#### Example
+
+Given an API description with following layout:
+
+- Group
+    - Copy "Lorem Ipsum"
+    - Resource "A"
+    - Resource "B"
+    - Copy "Dolor Sit Amet"
+
+```json
+{
+    "element": "category",
+    "meta": {
+        "description": "Lorem Ipsum\nDolor Sit Amet"
+    },
+    "content": [
+        {
+            "element": "copy",
+            "content": "Lorem Ipsum"
+        },
+        {
+            "element": "resource"
+        },
+        {
+            "element": "resource"
+        },
+        {
+            "element": "copy",
+            "content": "Dolor Sit Amet"
+        }
+    ]
+}
+```
+
 ## Protocol-specific Elements
 
 ### HTTP Transaction (Element)
@@ -315,8 +455,8 @@ HTTP request message.
 
 - `element`: httpRequest (string, fixed)
 - `attributes`
-    - `method` (string) - HTTP request method.
-    - `href` (Href) - A concrete URI for the request.
+    - `method` (string) - HTTP request method. The method value SHOULD be inherited from a parent transition if it is unset.
+    - `href` (Href) - A concrete URI for the request. The href SHOULD be inherited from a parent transition by expanding the href and hrefVariables if unset.
 
 ### HTTP Response Message (HTTP Message Payload)