Merge pull request #34 from smashwilson/metadata-envelope

Introduce the term "metadata envelope".

Author: smashwilson

running/architecture.rst

@@ -60,16 +60,23 @@ Terminology
     Template of common markup that surrounds each presented page with navigation, brand identity,
     copyright information and anything else that's shared among some subset of each site.
 
+  metadata envelope
+  metadata envelopes
+    JSON document that contains a single page's worth of content as a rendered HTML fragment, along with
+    any additional information necessary for the presentation of that page. See :ref:`the schema section
+    <envelope-schema>` for a description of the expected structure.
+
 Components
 ----------
 
 .. glossary::
 
   preparer
-    Process responsible for converting a :term:`content repository` into a directory tree of JSON
-    documents, each of which contains one page of rendered HTML and associated metadata.
+    Process responsible for converting a :term:`content repository` into a directory tree of
+    :term:`metadata envelopes`, each of which contains one page of rendered HTML and associated
+    metadata.
 
-    If the current branch is live, the generated JSON documents are then submitted to the
+    If the current branch is live, the generated envelopes are then submitted to the
     :term:`content service` for storage and indexing. Otherwise, a local :term:`presenter` is
     invoked to complete a full build of this subtree of the final site, which is then published to
     CDN and linked on the pull request.
@@ -84,9 +91,9 @@ Components
     repository` as a source of truth for performing the association.
 
   content service
-    Service that accepts submissions and queries for the most recent page content associated with a
-    specific :term:`content ID`. Content submitted here will have its structure validated and
-    indexed.
+    Service that accepts submissions and queries for the most recent :term:`metadata envelope`
+    associated with a specific :term:`content ID`. Content submitted here will have its structure
+    validated and indexed.
 
   layout service
     Given a :term:`presented URL`, return the Handlebars template that should be used to render the
@@ -96,6 +103,40 @@ Components
 
   presenter
     Accept HTTP requests from users. Map the requested :term:`presented URL` to :term:`content ID`
-    by querying the :term:`mapping service`, then access the requested content using the
-    :term:`content service`. Inject the content into an approriate :term:`layout` and send the
+    by querying the :term:`mapping service`, then access the requested :term:`metadata envelope`
+    using the :term:`content service`. Inject the envelope into an approriate :term:`layout` and send the
     final HTML back in an HTTP response.
+
+.. _envelope-schema:
+
+Metadata Envelope Schema
+------------------------
+
+Much of the deconst system involves the manipulation of :term:`metadata envelopes`, the JSON documents
+produced by each :term:`preparer` that contain the actual content to render. To be presented properly,
+envelopes must adhere to a common schema.
+
+Here's a `JSON schema <http://json-schema.org/>`_ document that describes its expected structure:
+
+.. code-block:: json
+
+  {
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "title": "Deconst Metadata Envelope",
+    "type": "object",
+    "properties": {
+      "body": {
+        "description": "Partially rendered HTML to be injected into a selected layout.",
+        "type": "string",
+      },
+      "required": ["body"]
+    }
+  }
+
+This is an example envelope that demonstrates the full document structure in a more concrete way:
+
+.. code-block:: json
+
+  {
+    "body": "<h1>Rendered HTML</h1>"
+  }