diff --git a/source/schema/begin_run_event.json b/source/schema/begin_run_event.json
new file mode 100644
index 0000000..cc5783a
--- /dev/null
+++ b/source/schema/begin_run_event.json
@@ -0,0 +1,50 @@
+{
+    "properties": {
+        "beamline_config": {
+            "type": ["object", "string"],
+            "description": "Meta-data regrading how the beamline is configured.  Maybe UID into another collection"
+        },
+        "project": {
+            "type": "string",
+            "description": "Name of project that this run is part of"
+        },
+        "sample": {
+            "type": ["object", "string"],
+            "description": "Information about the sample, may be a UID to another collection"
+        },
+        "beamline_id": {
+            "type": "string",
+            "description": "The beamline ID"
+        },
+        "scan_id": {
+            "type": "integer",
+            "description": "Scan ID number, not globally unique"
+        },
+        "time": {
+            "type": "number",
+            "description": "Time the run started.  Unix epoch time"
+        },
+        "uid": {
+            "type": "string",
+            "description": "Globally unique ID for tihs run"
+        },
+        "group": {
+            "type": ["string", "integer"],
+            "description": "Unix group to associate this data with"
+        },
+        "owner": {
+            "type": ["string", "integer"],
+            "description": "Unix owner to associate this data with"
+        }
+    },
+    "required": [
+        "uid",
+        "time",
+        "group",
+        "owner",
+        "beamline_config",
+        "beamline_id"
+     ],
+    "type": "object",
+    "description": "Document created at the start of run.  Provides a seach target and later documents link to it"
+}
diff --git a/source/schema/end_run_event.json b/source/schema/end_run_event.json
new file mode 100644
index 0000000..9a259ef
--- /dev/null
+++ b/source/schema/end_run_event.json
@@ -0,0 +1,35 @@
+
+{
+    "properties": {
+        "begin_run_event": {
+            "type": "string",
+            "description": "Reference back to the begin run document that this document is paired with."
+        },
+        "reason": {
+            "type": "string",
+            "description": "Long-form description of why the run ended"
+        },
+        "time": {
+            "type": "number",
+            "description": "The time the run ended. Unix epoch"
+        },
+        "completion_state": {
+            "type": "string",
+            "enum": ["success", "abort", "fail"],
+            "description": "State of the run when it ended"
+        },
+        "uid": {
+            "type": "string",
+            "description": "Globally unique ID for tihs run"
+        }
+    },
+    "required": [
+        "uid",
+        "begin_run_event",
+        "time",
+        "completion_state"
+    ],
+    "type": "object",
+    "description": "Document for the end of a run indicating the success/fail state of the run and the end time"
+
+}
diff --git a/source/schema/ev_desc_doc.json b/source/schema/ev_desc_doc.json
new file mode 100644
index 0000000..2cf9cb6
--- /dev/null
+++ b/source/schema/ev_desc_doc.json
@@ -0,0 +1,44 @@
+{
+"definitions": {
+    "data_key": {
+        "properties": {
+            "external": {
+                "pattern": "^[A-Z]+:?",
+                "type": "string"
+            },
+            "source": {
+                "pattern": "^[A-Z]+:",
+                "type": "string"
+            }
+        },
+        "required": [
+            "source"
+        ],
+        "type": "object"
+    }
+},
+"properties": {
+    "begin_run_event": {
+        "type": "string"
+    },
+    "keys": {
+        "additionalProperties": {
+            "$ref": "#/definitions/data_key"
+        },
+        "type": "object"
+    },
+    "time": {
+        "type": "number"
+    },
+    "uid": {
+        "type": "string"
+    }
+},
+"required": [
+    "uid",
+    "keys",
+    "time",
+    "begin_run_event"
+],
+"type": "object"
+}
diff --git a/source/schema/ev_desc_impl.json b/source/schema/ev_desc_impl.json
new file mode 100644
index 0000000..0d0783f
--- /dev/null
+++ b/source/schema/ev_desc_impl.json
@@ -0,0 +1,47 @@
+{
+   "definitions": {
+       "data_key": {
+           "properties": {
+               "external": {
+                   "pattern": "^[A-Z]+:?",
+                   "type": "string"
+               },
+               "source": {
+                   "pattern": "^[A-Z]+:",
+                   "type": "string"
+               }
+           },
+           "required": [
+               "source"
+           ],
+           "type": "object"
+       }
+   },
+   "properties": {
+       "begin_run_event": {
+           "type": "string"
+       },
+       "data_keys": {
+           "additionalProperties": {
+               "$ref": "#/definitions/data_key"
+           },
+           "type": "object"
+       },
+       "time": {
+           "type": "number"
+       },
+       "id": {
+           "type": "string"
+       },
+       "event_type": {
+           "type": "string"
+           }
+   },
+   "required": [
+       "id",
+       "keys",
+       "time",
+       "begin_run_event"
+   ],
+   "type": "object"
+}
diff --git a/source/schema/ev_desc_prop.json b/source/schema/ev_desc_prop.json
new file mode 100644
index 0000000..8cad762
--- /dev/null
+++ b/source/schema/ev_desc_prop.json
@@ -0,0 +1,75 @@
+    {
+        "definitions": {
+            "data_key": {
+                "title": "data_key",
+                "description": "Describes the objects in the data property of Event documents",
+                "properties": {
+                    "dtype": {
+                        "enum": [
+                            "string",
+                            "number",
+                            "array",
+                            "boolean",
+                            "integer"
+                        ],
+                        "type": "string",
+                        "description": "The type of the data in the event."
+                    },
+                    "external": {
+                        "pattern": "^[A-Z]+:?",
+                        "type": "string",
+                        "description": "Where the data is stored if it is stored external to the events."
+                    },
+                    "shape": {
+                        "items": {
+                            "type": "integer"
+                        },
+                        "type": ["array", "null"],
+                        "destription": "The shape of the data.  Null and empty list mean scalar data."
+                    },
+                    "source": {
+                        "pattern": "^[A-Z]+:",
+                        "type": "string",
+                        "description": "The source (ex piece of hardware) of the data."
+                    }
+                },
+                "required": [
+                    "source",
+                    "dtype",
+                    "shape"
+                ],
+                "type": "object"
+            }
+        },
+        "properties": {
+            "keys": {
+                "additionalProperties": {
+                    "$ref": "#/definitions/data_key"
+                },
+                "type": "object",
+                "description": "The describes the data to be in the event Documents",
+                "title": "keys"
+            },
+            "uid": {
+                "type": "string",
+                "description": "Globally unique ID for this event descriptor.",
+                "title": "uid"
+            },
+            "begin_run_event": {
+                "type": "string",
+                "description": "Globally unique ID to the begin_run document this descriptor is associtaed with."
+            },
+            "time": {
+                "type": "number",
+                "description": "Creation time of the document as unix epoch time."
+            }
+        },
+        "required": [
+            "uid",
+            "keys",
+            "time"
+        ],
+        "type": "object",
+        "title": "event_descriptor",
+        "description": "Document to describe the data captured in the associated event documents"
+    }
diff --git a/source/schema/event.json b/source/schema/event.json
new file mode 100644
index 0000000..d98ad61
--- /dev/null
+++ b/source/schema/event.json
@@ -0,0 +1,66 @@
+{
+    "definitions": {
+        "data_field": {
+            "title": "data_field",
+            "description": "Schema for entries in the event data property",
+            "items": [
+                {
+                    "type": [
+                        "string",
+                        "number",
+                        "boolean",
+                        "integer"
+                    ],
+                    "description": "The measured value or UID to look up external data",
+                    "title": "value"
+
+                },
+                {
+                    "type": "number",
+                    "description": "The hardware time stamp of this measurement. [s] from unix epoch",
+                    "title": "timestamp"
+                }
+
+            ],
+            "type": "array",
+            "additionalItems": false,
+            "minItems": 2
+        }
+    },
+    "properties": {
+        "data": {
+            "additionalProperties": {
+                "$ref": "#/definitions/data_field"
+            },
+            "type": "object",
+            "description": "The actual measument data"
+        },
+        "descriptor": {
+            "type": "string",
+            "description": "UID to point back to Descriptor for this event stream"
+        },
+        "seq_num": {
+            "type": "integer",
+            "description": "Sequence number to identify the location of this Event in the Event stream"
+        },
+        "time": {
+            "type": "number",
+            "description": "The event time.  This maybe different than the timestamps on each of the data entries"
+        },
+        "uid": {
+            "type": "string",
+            "description": "Globally unique identifier for this Event"
+        }
+    },
+    "required": [
+        "uid",
+        "data",
+        "time",
+        "descriptor",
+        "seq_num"
+    ],
+    "additionalProperties": false,
+    "type": "object",
+    "title": "event",
+    "description": "Document to record a quanta of collected data"
+}
diff --git a/source/schema/filestore-format.rst b/source/schema/filestore-format.rst
new file mode 100644
index 0000000..90b55cc
--- /dev/null
+++ b/source/schema/filestore-format.rst
@@ -0,0 +1,94 @@
+.. _filestore-format:
+
+****************************
+Format of File Store Entries
+****************************
+
+Introduction
+============
+
+The fileStore is for abstracting access to the contents of
+data stored in files.  It is important to make the distinction between
+*files* and *datasets*, as a single *file* can contain more than one *dataset*.
+There are two core collections, ``FileBase``
+which stores information about the *files* (where the file physically is,
+what format it is) and  ``FileEventLink`` which stores which file and how
+to extract a single *dataset* from that file.   Thus, by storing a single
+uuid, MetadataStore can keep track of non-scalar data in external storage.
+By only linking to ``FileStore`` through a *dataset* ID the grouping of
+data by file is de-coupled from any other logical grouping (by run or by
+detector).
+
+Associated with the database there needs to be a set of ``Handler`` classes
+which deal with opening files and extracting the *dataset* from the file.  There
+should also be a set of symmetric classes which handle file/dataset creation
+and the generation/insertion of the relevant documents.
+
+There will be one or more secondary (derived) collections which store meta-data
+like file size, data shape/type ect.
+
+
+Collections
+===========
+
+FileBase
+--------
+
+The ``FileBase`` collection store the bare minimum required to locate and
+open a file.  The documents have the following structure ::
+
+  FileBase : {
+      spec: <string>,
+      file_path: <string>,
+      custom: <dict>
+      }
+
+Which mean:
+
+ - ``spec`` : a string identifier to control the dispatch to the correct
+      ``Handler`` class.  By doing dispatch this way multiple types of files (or
+      even different views into the same file) can be stored in the same database.
+
+ - ``file_path`` : path to where the file exists on the physical disk.
+
+ - ``custom`` : dictionary of arguments which are passed to the ``Handler`` along
+   with the ``file_path`` when the file is opened.
+
+
+There is not intended to be any reference to ``FileBase`` documents on in the
+analysis client code, but DAQ will need to both create ``FileBase`` entries and
+keep track of them to create ``FileEntryLink`` documents.
+
+
+FileEntryLink
+-------------
+The ``FileEntryLink`` collections holds the information required to extract a single
+data set from a *file*.  The documents have the following structure ::
+
+  FileEntryLink : {
+      file_base : <FileBase reference>,
+      event_id : <unique id>,
+      link_parameters : <dict>,
+  }
+
+which mean :
+
+   - ``file_base`` : a link back to what file the *dataset* is in.
+   - ``event_id`` : a globally unique identifier for the dataset.  This string is
+     exposed to ``metadataStore``
+   - ``link_parameters`` : a dictionary of kwargs to pass to the ``Handler`` instance
+
+Handlers
+========
+
+The handler classes are what hold all of the data retrieval logic together.  The API on
+``Handlers`` is such that, given an ``event_id`` ::
+
+
+  fel_doc = get_event_link_document(event_id)
+  fb_doc = get_file_base_doc(fel_doc)
+  # use the spec value to look up what handler to use
+  h_class = handler_dispatch(fb_doc.spec)
+  # use the file_path and custom values to create a handler
+  h = h_class(fb_doc.file_path, **fb_doc.custom)
+  dataset = h(**fel_doc.link_parameters)
diff --git a/source/schema/mds.fig b/source/schema/mds.fig
new file mode 100644
index 0000000..245fde4
--- /dev/null
+++ b/source/schema/mds.fig
@@ -0,0 +1,87 @@
+#FIG 3.2  Produced by xfig version 3.2.5c
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+6 6750 3690 7560 3960
+2 2 0 1 0 7 50 -1 20 0.000 0 0 -1 0 0 5
+	 6750 3690 7560 3690 7560 3960 6750 3960 6750 3690
+4 1 0 50 -1 0 12 0.0000 4 150 795 7154 3900 File Base\001
+-6
+6 5269 2565 6214 2835
+2 2 0 1 0 7 50 -1 20 0.000 0 0 -1 0 0 5
+	 5269 2565 6214 2565 6214 2835 5269 2835 5269 2565
+4 1 0 50 -1 0 12 0.0000 4 150 915 5741 2775 Snowflake\001
+-6
+6 4320 2565 5130 2835
+2 2 0 1 0 7 50 -1 20 0.000 0 0 -1 0 0 5
+	 4320 2565 5130 2565 5130 2835 4320 2835 4320 2565
+4 1 0 50 -1 0 12 0.0000 4 195 645 4724 2752 Sample\001
+-6
+6 3420 3195 4950 3420
+2 2 0 1 0 7 50 -1 20 0.000 0 0 -1 0 0 5
+	 3420 3195 4950 3195 4950 3420 3420 3420 3420 3195
+4 1 0 50 -1 0 12 0.0000 4 195 1425 4184 3360 Beamline Config\001
+-6
+6 4612 3600 6097 3825
+2 2 0 1 0 7 50 -1 20 0.000 0 0 -1 0 0 5
+	 4612 3600 6097 3600 6097 3825 4612 3825 4612 3600
+4 1 0 50 -1 0 12 0.0000 4 195 1440 5355 3765 Begin Run Event\001
+-6
+6 3015 4140 4455 4365
+2 2 0 1 0 7 50 -1 20 0.000 0 0 -1 0 0 5
+	 3015 4140 4455 4140 4455 4365 3015 4365 3015 4140
+4 1 0 50 -1 0 12 0.0000 4 150 1290 3735 4327 End Run Event\001
+-6
+6 4620 4140 6180 4365
+2 2 0 1 0 7 50 -1 20 0.000 0 0 -1 0 0 5
+	 4646 4140 6153 4140 6153 4365 4646 4365 4646 4140
+4 1 0 50 -1 0 12 0.0000 4 195 1560 5400 4305 Event Descriptors\001
+-6
+6 5490 4725 6075 4950
+2 2 0 1 0 7 50 -1 20 0.000 0 0 -1 0 0 5
+	 5490 4725 6075 4725 6075 4950 5490 4950 5490 4725
+4 1 0 50 -1 0 12 0.0000 4 150 510 5782 4912 Event\001
+-6
+6 6570 4275 7875 4500
+2 2 0 1 0 7 50 -1 20 0.000 0 0 -1 0 0 5
+	 6592 4275 7852 4275 7852 4500 6592 4500 6592 4275
+4 1 0 50 -1 0 12 0.0000 4 150 1305 7222 4462 File Event Link\001
+-6
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	1 1 1.00 60.00 120.00
+	 7110 4275 7110 3960
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	1 1 1.00 60.00 120.00
+	 5805 4725 5805 4365
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	1 1 1.00 60.00 120.00
+	 5445 4140 5445 3825
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	1 1 1.00 60.00 120.00
+	 4095 4140 5400 3825
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	1 1 1.00 60.00 120.00
+	 5265 3600 4230 3420
+2 2 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 5
+	 6345 2250 2925 2250 2925 4455 6345 4455 6345 2250
+2 2 0 1 0 7 51 -1 18 0.000 0 0 -1 0 0 5
+	 2835 3015 6300 3015 6300 5085 2835 5085 2835 3015
+2 1 3 1 0 7 50 -1 -1 3.000 0 0 -1 1 0 2
+	1 1 1.00 60.00 120.00
+	 5265 3600 5670 2835
+2 1 3 1 0 7 50 -1 -1 3.000 0 0 -1 1 0 2
+	1 1 1.00 60.00 120.00
+	 5265 3600 4770 2835
+2 1 3 1 0 7 50 -1 -1 3.000 0 0 -1 1 0 2
+	1 1 1.00 60.00 120.00
+	 6075 4815 7110 4500
+2 2 0 1 0 7 51 -1 18 0.000 0 0 -1 0 0 5
+	 6480 3330 7920 3330 7920 4590 6480 4590 6480 3330
+4 0 0 50 -1 0 12 0.0000 4 150 645 3060 2520 Header\001
+4 0 0 50 -1 0 12 0.0000 4 150 465 2925 4905 MDS\001
+4 0 0 50 -1 0 12 0.0000 4 150 825 6525 3555 File Store\001
diff --git a/source/schema/metadatastore-format.rst b/source/schema/metadatastore-format.rst
new file mode 100644
index 0000000..44584df
--- /dev/null
+++ b/source/schema/metadatastore-format.rst
@@ -0,0 +1,415 @@
+*******************************
+Format of Metadatastore Entries
+*******************************
+
+Introduction
+============
+
+The metadatastore is based on the concept of documents which are either
+events, or descriptions of events.  An ``event`` is a quantum of data
+stored in the metadata store and represents an *action* at a given time. For
+example: "*measurement of 8 scaler chanels*", "*trigger detectors*" or
+"*start run*".
+
+Expanding the notion of **events**, these can also be used for derived data.
+For example, an event could be the result of a data analysis or reduction
+routine which was run at a certain time.
+
+The document schemas in this document are written using ``jsonschema``.  The
+full spec http://json-schema.org/ is basically un-readable.  A more readable
+introduction https://spacetelescope.github.io/understanding-json-schema/index.html.
+
+
+.. todo::
+    Expand this section
+
+
+
+
+Time
+====
+
+One of the cornerstones of this data acquisition and analysis method is the use
+of *time* as the method by which data can be aligned and correlated. A single
+``event`` should have happened at a certain quantum of time with the
+determination of what a time *quantum* is left to the details of the
+experiment. Time however, can be horrendously messy. Throughout this
+section we use two terms, ``timestamp`` and ``time``. These mean
+
+
+time
+    The date/time as found by the client when an ``event`` is
+    created.  This could be a date-time format as determined by the underlying
+    storage method (for example a database).
+
+timestamp
+   A (usually *float*) representation of the hardware time when a
+   certain value was obtained. Wherever possible this should be read from
+   hardware. For example, this could be the *EPICS* timestamp from when the
+   record processed which provides the value.
+
+
+We use the literal ``<time>`` to indicate a client side date/time and
+``<timestamp>`` to represent the numerical timestamp.
+
+.. todo::
+    Add dictionary of reserved keys such as ``timestamp``, ``id``
+    Expand for data collection, using event model
+
+
+Documents
+=========
+
+.. xfig:: mds.fig
+
+
+Events view of the world
+========================
+
+Events are the smallest quantum of data stored in the metadatastore. They group
+values which are associated with temporally bundled data. The definition of
+"temporally identical" is determined by the DAQ system. For example, the 32
+channels in a scaler can be considered to be temporally identical because they
+are hardware synchronized. Inclusion of a CCD image (with a reference to the
+file store) can be included if this event is triggered at the same time, either
+by software or hardware.  Each ``event`` contains the data values and a client
+side timestamp of when the even was created. The same logic is applied to
+``trigger events``. These are grouped with temporally identical triggers (again
+determined by the DAQ philosophy).
+
+
+
+Event Descriptor Document
+=========================
+.. highlight:: json
+
+Schema
+++++++
+
+.. schema_diff::
+
+    // Proposed
+    ev_desc_prop.json
+    --
+    // as documented
+    ev_desc_doc.json
+    --
+
+    // As currently (1c2246d) implemented
+    ev_desc_impl.json
+
+
+Definitions
++++++++++++
+
+data_key
+~~~~~~~~
+{"source": "NAMESPACE:NAME", "external": "NAMESPACE:NAME"}
+
+source
+  The reference to the physical piece of hardware that produced this data
+
+external, optional
+  The reference to the location where the data is being stored.
+  If this key is not present, then the data is stored inside the data
+  field of the corresponding ``Event`` document.
+  If this key is present, then the ``value`` field of the ``data``
+  dictionary inside the ``Event`` document is interpreted as a unique
+  key that can be used to retrieve corresponding data from the
+  service described by the value of the ``external`` key
+
+The values of both =source= and =external= are (=namespace=, =name=) pairs.
+The name is obligatory for source and optional for external
+
+NAMESPACE
+   Things like ``PV`` or ``FileStore``.
+NAME
+   Thing in the name space.
+
+
+
+Example
++++++++
+
+Event descriptors are used to describe an array of events which can form an
+event stream of a collection of events. For example a run forms
+event_descriptors at run start to define the data collected. For the example
+above ``event`` is described by the ``event_descriptor``
+
+.. ipython:: python
+
+  import json
+  import jsonschema
+  ev_desc = {
+      "uid": "f05338e0-ed07-4e15-8d7b-06a60dcebaff",
+      "keys": {
+          "chan1": {"source": "PV:XF:23ID1-ES{Sclr:1}.S1", "dtype": "number", "shape": None},
+          "chan2": {"source": "PV:XF:23ID1-ES{Sclr:1}.S2", "dtype": "number", "shape": None},
+          "chan3": {"source": "PV:XF:23ID1-ES{Sclr:1}.S3", "dtype": "number", "shape": None},
+          "chan4": {"source": "PV:XF:23ID1-ES{Sclr:1}.S4", "dtype": "number", "shape": None},
+          "chan5": {"source": "PV:XF:23ID1-ES{Sclr:1}.S5", "dtype": "number", "shape": None},
+          "chan6": {"source": "PV:XF:23ID1-ES{Sclr:1}.S6", "dtype": "number", "shape": None},
+          "chan7": {"source": "PV:XF:23ID1-ES{Sclr:1}.S7", "dtype": "number", "shape": None},
+          "chan8": {"source": "PV:XF:23ID1-ES{Sclr:1}.S8", "dtype": "number", "shape": None},
+          "pimte": {"source": "CCD:name_of_detector", "external": "FILESTORE",
+                    "dtype": "array", "shape": [1254, 2014]}
+      },
+      "begin_run_event": "2dc386b5-cfee-4906-98e9-1a8322581a92",
+      "time": 1422940263.7583334,
+  }
+  with open('source/arch/ev_desc_prop.json') as fin:
+      schema_prop = json.load(fin)
+
+  jsonschema.validate(ev_desc, schema_prop) is None
+
+Note that ``validate`` returns ``None`` for documents that pass and raises
+exceptions for those that do not.
+
+Discussion points
++++++++++++++++++
+
+- Should ``begin_run_event`` be a mandatory?
+
+
+Event Documents
+===============
+
+Schema
+++++++
+.. schema_diff::
+  // As documented
+  event.json
+  --
+
+  // As implemented
+
+  {
+      "definitions": {
+          "data": {
+              "properties": {
+                  "timestamp": {
+                      "type": "number"
+                  },
+                  "value": {
+                      "type": [
+                          "string",
+                          "number"
+                      ]
+                  }
+              },
+              "required": [
+                  "value",
+                  "timestamp"
+              ],
+              "type": "object"
+          }
+      },
+      "properties": {
+          "data": {
+              "additionalProperties": {
+                  "$ref": "#/definitions/data"
+              },
+              "type": "object"
+          },
+          "descriptor": {
+              "type": "string"
+          },
+          "seq_no": {
+              "type": "number"
+          },
+          "time": {
+              "type": "number"
+          },
+          "time_as_datetime": {
+              "type": "string"
+          }
+      },
+      "required": [
+          "data",
+          "time",
+          "descriptor",
+	  "seq_no"
+      ],
+      "type": "object"
+  }
+
+
+The field ``seq_num`` is used to order the events in the order in which they were
+created.
+
+Example
++++++++
+
+Measure events contain the data measured at a certain instance in time or
+explicit point in a sequence. For example::
+
+    {
+        "uid": "4609e51f-cf38-4c2a-a6ea-483edc461e43",
+        "seq_num": 42,
+        "descriptor": "f05338e0-ed07-4e15-8d7b-06a60dcebaff",
+        "data": {
+            "chan1": [3.14, 1422940467.3101866],
+            "chan2": [3.14, 1422940467.3101866],
+            "chan3": [3.14, 1422940467.3101866],
+            "chan4": [3.14, 1422940467.3101866],
+            "chan5": [3.14, 1422940467.3101866],
+            "chan6": [3.14, 1422940467.3101866],
+            "chan7": [3.14, 1422940467.3101866],
+            "chan8": [3.14, 1422940467.3101866],
+            "pimte": ["8cad7f02-c3e1-4e76-a823-94a2a7d23f6b",
+                      "timestamp": 1422940481.8930786]
+        },
+        "time": 1422940508.3491018,
+    }
+
+Where the keys ``uid``, ``ev_desc``, ``time`` and ``timestamp`` refer to
+the unique id, a link to the event descriptor the time and the EPICS timestamp
+respectively.
+
+
+Start Run Events
+================
+
+
+Schema
+++++++
+.. schema_diff::
+
+  // As documented
+  begin_run_event.json
+  --
+
+  // As implemented
+
+  {
+        "properties": {
+          "beamline_config": {
+              "type": "object"
+          },
+          "beamline_id": {
+              "type": "string"
+          },
+          "custom": {
+              "type": "object"
+          },
+          "owner": {
+              "type": "string"
+          },
+          "scan_id": {
+              "type": "string"
+          },
+          "time": {
+              "type": "number"
+          },
+          "time_as_datetime": {
+              "type": "string"
+          }
+      },
+      "required": [
+         "time",
+         "owner",
+         "beamline_id"
+      ],
+      "type": "object"
+  }
+
+
+Example
++++++++
+
+The beginning of a data collection run creates an event which contains
+sufficient metadata and information to describe the data collection. For
+example, this is where beamline config information is located. The start run
+event also serves as a searchable entity which links all data associated by an
+event. For example::
+
+    {
+        "uid": "2dc386b5-cfee-4906-98e9-1a8322581a92",
+        "scan_id": "ascan_52",
+        "beamline_id": "CSX",
+        "sample": {
+            "uid": "0a785292-05c5-4c1b-bd9a-f2dd5b0580c8",
+            "id": 9,
+            "description": "A small piece of cheese"
+        },
+        "project": "Cheese_shop",
+        "beamline_config": {
+            "diffractometer": {
+                "geometry": "swiss",
+                "xtal_lattice": {
+                    "a": 1.1,
+                    "b": 2.2,
+                    "c": 3.3,
+                    "alpha": 4.4,
+                    "beta": 5.5,
+                    "gamma": 6.6
+                },
+                "UB": [1, 2, 3, 4]
+            }
+        },
+        "time": 1422940625.2198992,
+        "owner": "jcleese",
+        "group": "monty"
+
+
+    }
+
+
+
+End Run Events
+==============
+
+Schema
+++++++
+
+.. schema_diff::
+
+  // As Documented
+  end_run_event.json
+  --
+  // As implemented
+
+
+  {
+      "properties": {
+          "begin_run_event": {
+              "type": "string"
+          },
+          "custom": {
+              "type": "object"
+          },
+          "reason": {
+              "type": "string"
+          },
+          "time": {
+              "type": "number"
+          },
+          "time_as_datetime": {
+              "type": "string"
+          }
+      },
+      "required": [
+          "begin_run_event",
+          "time"
+      ],
+      "type": "object"
+  }
+
+
+Example
++++++++
+
+
+With the corresponding end run event as::
+
+    {
+        "uid": "60bac4c7-e2d3-4c4b-a553-3790a8add866",
+        "begin_run_event": "2dc386b5-cfee-4906-98e9-1a8322581a92",
+        "reason": "This shop does not contain any cheese",
+        "completion_state": "fail",
+        "time": 1422940679.72617,
+    }
+
+The field ``reason`` can be used to describe why a run ended e.g. was it aborted or
+was there an exception during data collection. The field ``begin_run_event`` is a
+pointer to the start document.
diff --git a/source/schema/over_view.fig b/source/schema/over_view.fig
new file mode 100644
index 0000000..d6bce02
--- /dev/null
+++ b/source/schema/over_view.fig
@@ -0,0 +1,160 @@
+#FIG 3.2  Produced by xfig version 3.2.5c
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+6 3780 450 5310 810
+2 2 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 5
+	 3780 450 5310 450 5310 810 3780 810 3780 450
+4 1 0 50 -1 0 12 0.0000 4 195 1515 4545 682 Sample Database\001
+-6
+6 3780 900 5400 1260
+6 3802 1006 5377 1153
+4 1 0 50 -1 0 12 0.0000 4 147 1575 4589 1153 External Database\001
+-6
+6 3780 900 5400 1260
+2 2 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 5
+	 3780 900 5400 900 5400 1260 3780 1260 3780 900
+-6
+-6
+6 3780 2610 5355 2970
+2 2 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 5
+	 3780 2610 5355 2610 5355 2970 3780 2970 3780 2610
+4 1 0 50 -1 0 12 0.0000 4 150 1545 4567 2865 Channel Archiver\001
+-6
+6 1350 705 2355 1530
+6 1672 705 2032 1335
+6 1672 705 2032 1335
+6 1672 705 2032 1335
+1 3 0 1 0 7 50 -1 -1 4.000 1 0.0000 1852 795 90 90 1852 795 1942 795
+2 1 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 3
+	 1852 885 1852 1155 1762 1335
+2 1 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 2
+	 1852 1155 1942 1335
+2 1 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 2
+	 1672 975 2032 975
+-6
+-6
+-6
+4 1 0 50 -1 0 12 0.0000 4 195 1005 1852 1485 Experiment\001
+-6
+6 1492 2385 2212 2700
+2 2 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 5
+	 1492 2385 2212 2385 2212 2700 1492 2700 1492 2385
+4 1 0 50 -1 0 12 0.0000 4 150 600 1852 2617 EPICS\001
+-6
+6 1402 3060 2302 3330
+2 2 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 5
+	 1402 3060 2302 3060 2302 3330 1402 3330 1402 3060
+4 1 0 50 -1 0 12 0.0000 4 150 885 1852 3270 Hardware\001
+-6
+6 5850 1935 6930 2250
+2 2 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 5
+	 5850 1935 6930 1935 6930 2250 5850 2250 5850 1935
+4 1 0 50 -1 0 12 0.0000 4 150 1020 6390 2167 DataBroker\001
+-6
+6 5940 2520 6840 2880
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 5940 2520 6840 2520 6840 2880 5940 2880 5940 2520
+4 1 0 50 -1 0 12 0.0000 4 195 540 6390 2752 replay\001
+-6
+6 7140 615 8730 1440
+6 7755 615 8115 1245
+1 3 0 1 0 7 50 -1 -1 4.000 1 0.0000 7935 705 90 90 7935 705 8025 705
+2 1 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 3
+	 7935 795 7935 1065 7845 1245
+2 1 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 2
+	 7935 1065 8025 1245
+2 1 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 2
+	 7755 885 8115 885
+-6
+4 1 0 50 -1 0 12 0.0000 4 195 1590 7935 1395 Science Questions\001
+-6
+6 3780 1485 5355 1845
+2 2 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 5
+	 3780 1485 5355 1485 5355 1845 3780 1845 3780 1485
+4 1 0 50 -1 0 12 0.0000 4 150 1350 4567 1740 Metadata Store\001
+-6
+6 3780 2025 4770 2385
+2 2 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 5
+	 3780 2025 4770 2025 4770 2385 3780 2385 3780 2025
+4 1 0 50 -1 0 12 0.0000 4 150 825 4274 2280 File Store\001
+-6
+6 5850 3105 6930 3465
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 5850 3105 6930 3105 6930 3465 5850 3465 5850 3105
+4 1 0 50 -1 0 12 0.0000 4 195 975 6389 3337 Bubblegum\001
+-6
+6 7155 2520 8047 2880
+2 2 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 5
+	 7155 2520 8047 2520 8047 2880 7155 2880 7155 2520
+4 1 0 50 -1 0 12 0.0000 4 150 585 7597 2752 Muxer\001
+-6
+6 7073 1890 8768 2250
+2 2 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 5
+	 7110 1890 8730 1890 8730 2250 7110 2250 7110 1890
+4 1 0 50 -1 0 12 0.0000 4 195 1695 7920 2122 Workflow Manager\001
+-6
+6 8190 2520 8733 2880
+2 2 0 1 0 7 50 -1 -1 4.000 0 0 7 0 0 5
+	 8190 2520 8733 2520 8733 2880 8190 2880 8190 2520
+4 1 0 50 -1 0 11 0.0000 4 135 450 8461 2767 Nikea\001
+-6
+6 1492 1845 2212 2160
+6 1567 1905 2137 2100
+6 1567 1905 2137 2100
+4 1 0 50 -1 0 12 0.0000 4 195 570 1852 2055 Ophyd\001
+-6
+-6
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 1492 1845 2212 1845 2212 2160 1492 2160 1492 1845
+-6
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 2205 2025 3150 2025 3150 1665 3780 1665
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 5355 1665 5670 1665 5670 2205 5850 2205
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 4770 2205 5580 2205 5850 2205
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 5355 2790 5670 2790 5670 2205 5850 2205
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 5310 630 5715 630 5715 1980 5850 1980
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 5400 1080 5715 1080 5715 1980 5850 1980
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 6930 2070 7110 2070
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 7650 2250 7650 2520
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 8460 2250 8460 2520
+2 2 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 5
+	 7020 360 9045 360 9045 3510 7020 3510 7020 360
+2 2 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 5
+	 1170 360 3555 360 3555 3510 1170 3510 1170 360
+2 2 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 5
+	 3690 360 5490 360 5490 3510 3690 3510 3690 360
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 2250 2025 3150 2025 3150 2205 3780 2205
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 4
+	 2250 2025 3150 2025 3150 2790 3780 2790
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 1845 1845 1845 1530
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 1852 2160 1852 2385
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 1852 2700 1852 3060
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 6840 2700 7155 2700
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 6390 2520 6390 2250
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 6390 3105 6390 2880
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 7920 1485 7920 1890
+4 0 0 50 -1 0 12 0.0000 4 150 870 1170 270 Collection\001
+4 0 0 50 -1 0 12 0.0000 4 195 1215 7020 270 Data Analysis\001
+4 0 0 50 -1 0 12 0.0000 4 195 1590 3690 270 Raw Data Storage\001
diff --git a/source/schema/overview.rst b/source/schema/overview.rst
new file mode 100644
index 0000000..eda3b6a
--- /dev/null
+++ b/source/schema/overview.rst
@@ -0,0 +1,8 @@
+********
+Overview
+********
+
+System Diagram
+==============
+
+.. xfig:: over_view.fig
diff --git a/source/sphinxext/jsonschema_diff.py b/source/sphinxext/jsonschema_diff.py
index 7385f91..699ea84 100644
--- a/source/sphinxext/jsonschema_diff.py
+++ b/source/sphinxext/jsonschema_diff.py
@@ -40,7 +40,6 @@
 from sphinx.util.compat import Directive
 from sphinx.util.nodes import set_source_info
 import difflib
-import jsonschema
 import jinja2
 
 
@@ -100,7 +99,7 @@ def pprint_json(jsdoc):
 
     """
     return json.dumps(jsdoc, sort_keys=True, indent=4,
-               separators=(',', ': '))
+                      separators=(',', ': '))
 
 
 class _baseSchemaDirective(Directive):
@@ -113,18 +112,26 @@ def split_content(self, input_string):
         part = []
         comment = []
 
+        opts = self.options
+
         def add_part():
             content = '\n'.join(part)
             if len(part) == 1:
                 try:
-                    rst_file = self.state_machine.document.attributes['source']
-                    test_path = os.path.join(os.path.dirname(rst_file),
-                                              content)
-                    with open(test_path, 'r') as fin:
-                        content = '\n'.join(fin)
-                except FileNotFoundError:
-                    pass
-            try:
+                    import importlib
+                    mod = importlib.import_module(opts['schema_module'])
+                    json_content = getattr(mod, opts['schema_dict'])[content]
+                except:
+                    try:
+                        rst_file = self.state_machine.document.attributes['source']
+                        test_path = os.path.join(os.path.dirname(rst_file),
+                                                 content)
+                        with open(test_path, 'r') as fin:
+                            content = '\n'.join(fin)
+                        json_content = json.loads(content)
+                    except FileNotFoundError:
+                        pass
+            else:
                 json_content = json.loads(content)
             except ValueError:
                 if should_pass:
@@ -162,6 +169,8 @@ class SchemaDiffDirective(_baseSchemaDirective):
     def run(self):
         result = []
 
+        opts = self.options
+
         parts = self.split_content(self.content)
         for part in parts:
             if len(part.comment):
@@ -282,6 +291,8 @@ def depart_diff_node_latex(self, node):
 def setup(app):
     app.add_directive('schema_diff', SchemaDiffDirective)
 
+    app.add_config_value('schema_module', 'event_model', True)
+    app.add_config_value('schema_dict', 'schemas', True)
     app.add_node(jsonschema_node,
                  html=(visit_jsonschema_node_html,
                        depart_jsonschema_node_html),