pycadf documentation

add basic documentation on CADF spec.

Closes-Bug: #1279951
Change-Id: Ie1703d9b5109d8275377857e5362e3b09385f647
Implements: blueprint document-pycadf

27 files changed, 1627 insertions, 0 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..5213d9a
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,182 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  wadl       to build a WADL file for api.openstack.org"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html: check-dependencies
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: check-dependencies
+check-dependencies:
+	@python -c 'import sphinxcontrib.autohttp.flask' >/dev/null 2>&1 || (echo "ERROR: Missing Sphinx dependencies. Run: pip install sphinxcontrib-httpdomain" && exit 1)
+
+wadl:
+	$(SPHINXBUILD) -b docbook $(ALLSPHINXOPTS) $(BUILDDIR)/wadl
+	@echo
+	@echo "Build finished. The WADL pages are in $(BUILDDIR)/wadl."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pyCADF.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pyCADF.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/pyCADF"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pyCADF"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
diff --git a/doc/source/_templates/.placeholder b/doc/source/_templates/.placeholder
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/source/_templates/.placeholder
diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst
new file mode 100644
index 0000000..3da71d0
--- /dev/null
+++ b/doc/source/api/index.rst
@@ -0,0 +1,8 @@
+==============
+ API Reference
+==============
+
+.. toctree::
+   :maxdepth: 1
+
+   autoindex
diff --git a/doc/source/conf.py b/doc/source/conf.py
new file mode 100644
index 0000000..1dc84b4
--- /dev/null
+++ b/doc/source/conf.py
@@ -0,0 +1,261 @@
+# -*- coding: utf-8 -*-
+#
+# pyCADF documentation build configuration file, created by
+# sphinx-quickstart on Sun Mar 16 22:32:24 2014.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# This is required for ReadTheDocs.org, but isn't a bad idea anyway.
+os.environ['DJANGO_SETTINGS_MODULE'] = 'openstack_dashboard.settings'
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.pngmath',
+    'sphinx.ext.viewcode',
+    'oslosphinx'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'pyCADF'
+copyright = u'2014, gordon chung'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+html_theme_options = {
+    "nosidebar": "false"
+}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'pyCADFdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'pyCADF.tex', u'pyCADF Documentation',
+   u'gordon chung', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'pycadf', u'pyCADF Documentation',
+     [u'gordon chung'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'pyCADF', u'pyCADF Documentation',
+   u'gordon chung', 'pyCADF', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
diff --git a/doc/source/event_concept.rst b/doc/source/event_concept.rst
new file mode 100644
index 0000000..913f174
--- /dev/null
+++ b/doc/source/event_concept.rst
@@ -0,0 +1,175 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _event_concept:
+
+=======
+ Events
+=======
+
+The principal goal of this specification is to ensure that similar auditable
+events, such as a "logon" or "critical resource update" resolve to the same
+data format with prescriptive data types, entities, and properties to
+facilitate reporting, query, federation, and aggregation.
+
+Defining Events
+===============
+
+The event model is intended to describe the interactions between resources
+that compose a cloud service. Conceptually, the event is based upon the
+perspective of a single RESOURCE called the OBSERVER that is responsible for
+observing the Actual Event and creating the (initial) CADF Event Record.
+
+.. figure:: ./images/observer_cadf.png
+   :figwidth: 100%
+   :align: center
+   :alt: Figure 1: Observer perspective of an Event
+
+At a minimum, an Event must include the following attributes to be
+CADF-compliant: eventType, observer, initiator, target, action, and outcome.
+CADF's event model is extensible so any additional attributes that may better
+help describe the event can be added to the event model as an additional
+attribute.
+
+.. note::
+
+   In some cases, the OBSERVER, INITIATOR, and TARGET could reference the same
+   resource. The precise interpretation of these components, therefore, will
+   depend somewhat on the type of event being recorded, and the specific
+   activity and resources involved.
+
+Use Case Examples
+=================
+
+1. Auditing access to a controlled resource
+
+Scenario: A cloud provider has a software component that manages identity and
+access control that we will call an "identity management service". This
+service is required, by the provider's security policy, to log all user
+activities including "logon" attempts against any servers within the
+provider's infrastructure.
+
+.. figure:: ./images/audit_event.png
+   :figwidth: 100%
+   :align: center
+   :alt: Figure 2: Conceptually mapping values of an audit event
+
+================= ========================== ==========================================================================================
+Event Attribute   Value                      Reason
+================= ========================== ==========================================================================================
+eventType         activity                   OBSERVER is required to report any user security activity
+observer.typeURI  service/security/identity  Value from the CADF Resource Taxonomy most closely describes an "Identity Manager Service"
+initiator.typeURI data/security/account/user Value from the CADF Resource Taxonomy most closely describes a "user"
+action            authenticate/logon	     Value from the CADF Action Taxonomy most closely describes a user "logon" action.
+target.typeURI    service/compute/node       Value from the CADF Resource Taxonomy most closely describes a target "server"
+outcome           success                    Any valid CADF Outcome Taxonomy value that describes result of action
+measurement       N/A                        A MEASUREMENT component is not required for "activity" type events.
+REASON            N/A                        A REASON component is not required for "activity" type events.
+================= ========================== ==========================================================================================
+
+Event serialisation (including some optional attributes for additional
+details)::
+
+   {
+    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
+    "eventTime": "2014-02-27T19:29:30.855665+0000",
+    "target": {
+       "typeURI": "service/compute/node",
+       # optional Endpoints to describe compute node
+      "addresses": [{"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", "name": "admin"},
+                     {"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", "name": "private"},
+                     {"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", "name": "public"}],
+       "id": "openstack:06747855d62547d4bfd707f75b8a1c54",
+       "name": "nova"},
+    "observer": {"id": "target"}, # shortform to show Observer Resource is the same as Target
+    # tags use to query events on
+    "tags": ["correlation_id?value=openstack:56cdde6f-6b4e-48a4-94e6-defb40522fb2"],
+    "eventType": "activity",
+    "initiator": {
+       "typeURI": "data/security/account/user",
+       "name": "admin",
+       # optional Credential to describe resource
+       "credential": {"token": "MIIQzgYJKoZIhvcNAQcCoIIQvzCCELsC xxxxxxxx zqvD9OPWZm7VQpYNK2EvrZi-mTvb5A==",
+                      "identity_status": "Confirmed"},
+       # optional Host to describe resource
+      "host": {"agent": "python-novaclient", "address": "9.26.26.250"},
+      "project_id": "openstack:e7e2bcc9c0df4f3eabcd412ae62503f6",
+      "id": "openstack:68a3f50705a54f799ce94380fc02ed8a"},
+    # optional Reason for activity event
+    "reason": {"reasonCode": "200", "reasonType": "HTTP"},
+    # list of Resources which edited event
+    "reporterchain": [{"reporterTime": "2014-02-27T19:29:31.043902+0000",
+                       "role": "modifier",
+                       "reporter": {"id": "target"}}],
+    "action": "authenticate/logon",
+    "outcome": "success",
+    "id": "openstack:0a196053-95de-48f8-9890-4527b25b5007",
+    # Event model is extensible so additional attributes may be added to describe model
+    "requestPath": "/v2/e7e2bcc9c0df4f3eabcd412ae62503f6/os-certificates"}
+
+2. Periodic monitoring resource status
+
+Scenario: A cloud provider has software monitoring agents(Ceilometer)
+installed on every server(Nova) that it makes available as an IaaS resource
+to its customers. These agents are required to provide periodic informational
+status of each server's CPU utilisation along with metric data to their
+operations management software by using the CADF Event Record format.
+
+.. figure:: ./images/monitor_event.png
+   :figwidth: 100%
+   :align: center
+   :alt: Figure 3: Conceptually mapping values of an monitor event
+
+================= ====================== ==========================================================================================
+Event Attribute   Value                  Reason
+================= ====================== ==========================================================================================
+eventType         monitor                OBSERVER is required to monitor a server's CPU utilization
+observer.typeURI  service/oss/monitoring Value from the CADF Resource Taxonomy most closely describes a "software monitoring agent"
+initiator.typeURI service/oss/monitoring OBSERVER is also the INITIATOR of this monitoring event
+action            monitor                Value from the CADF Action Taxonomy
+target.typeURI    service/compute/cpu    Value from the CADF Resource Taxonomy most closely describes a server’s "cpu"
+outcome           success                OBSERVER successfully obtained and reported a CPU utilization measurement
+measurement       80%                    MEASUREMENT component is required and the observed value is 80% CPU utilisation
+reason            N/A                    REASON component is not required for "monitor" type events.
+================= ====================== ==========================================================================================
+
+Event serialisation::
+
+   {
+    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
+    "eventTime": "2014-02-27T19:29:30.855665+0000",
+    "target": {
+       "typeURI": "service/compute/cpu",
+       "id": "openstack:06747855d62547d4bfd707f75b8a1c54",
+       "name": "instance"},
+    "observer": {"id": "initiator"},
+    "eventType": "monitor",
+    "initiator": {
+       "typeURI": "service/oss/monitoring",
+       "name": "ceilometer-pollster",
+       "id": "openstack:68a3f50705a54f799ce94380fc02ed8a"},
+    "measurement": [{
+       "result": "80",
+       "metric": {"metricId": "openstack:<metric_id>",
+                  "unit": "%",
+                  "name": "CPU utilisation metric"}
+    }]
+    "action": "monitor",
+    "outcome": "success",
+    "id": "openstack:0a196053-95de-48f8-9890-4527b25b5007"}
+
+.. note::
+
+   Additional use cases can be found in the Full CADF specification.
\ No newline at end of file
diff --git a/doc/source/images/audit_event.png b/doc/source/images/audit_event.png
new file mode 100644
index 0000000..57c99ca
--- /dev/null
+++ b/doc/source/images/audit_event.png
diff --git a/doc/source/images/middleware.png b/doc/source/images/middleware.png
new file mode 100644
index 0000000..5c2b130
--- /dev/null
+++ b/doc/source/images/middleware.png
diff --git a/doc/source/images/monitor_event.png b/doc/source/images/monitor_event.png
new file mode 100644
index 0000000..8853d31
--- /dev/null
+++ b/doc/source/images/monitor_event.png
diff --git a/doc/source/images/observer_cadf.png b/doc/source/images/observer_cadf.png
new file mode 100644
index 0000000..f79a8cf
--- /dev/null
+++ b/doc/source/images/observer_cadf.png
diff --git a/doc/source/index.rst b/doc/source/index.rst
new file mode 100644
index 0000000..a72e1a9
--- /dev/null
+++ b/doc/source/index.rst
@@ -0,0 +1,61 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+===============================
+ PyCADF developer documentation
+===============================
+
+The `CADF (Cloud Audit Data Federation Working Group)`_ is working to develop
+open standards for audit data which can be federated from cloud providers,
+with the intent to elevate customer’s trust in cloud hosted applications.
+
+Specifications and profiles produced by the CADF will help protect the
+investments of companies seeking to move their applications to cloud
+deployment models and preserve their ability to audit operational processes,
+regardless of their chosen cloud provider. The CADF develops specifications
+for audit event data and interface models and a compatible interaction model
+that will describe interactions between IT resources for cloud deployment models.
+
+pyCADF is the python implementation of the CADF specification
+
+This documentation offers information on how CADF works and how to
+contribute to the project.
+
+.. _CADF (Cloud Audit Data Federation Working Group): http://www.dmtf.org/standards/cadf
+
+Table of contents
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   api/index
+   specification/index
+   event_concept
+   middleware
+
+.. update index
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+To Do
+=====
+
+.. todolist::
diff --git a/doc/source/middleware.rst b/doc/source/middleware.rst
new file mode 100644
index 0000000..920279a
--- /dev/null
+++ b/doc/source/middleware.rst
@@ -0,0 +1,103 @@
+..
+      Copyright 2014 IBM Corp
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _middleware:
+
+=================
+ Audit middleware
+=================
+
+The pyCADF library provides an optional WSGI middleware filter which allows
+the ability to audit api requests for each component of OpenStack.
+
+The audit middleware filter utilises environment variables to build the CADF
+event.
+
+.. figure:: ./images/middleware.png
+   :figwidth: 100%
+   :align: center
+   :alt: Figure 1: Audit middleware in Nova pipeline
+
+The figure above shows the middleware in Nova's pipeline.
+
+Enabling audit middleware
+=========================
+To enable the audit middleware, the following requirements need to be
+satisfied:
+
+1. pyCADF library must be added to the requirements file of the project to be
+   audited.
+
+2. The project should utilise oslo.messaging_ notification system.
+
+.. note::
+
+   If the project utilises oslo's `old notification system`_, a compatible
+   middleware can be synced from oslo-incubator's `middleware code base`_.
+
+If the above requirements are satisfied, auditing can be enabled by editing
+the project's api-paste.ini file to include the following filter definition:
+
+::
+
+   [filter:audit]
+   paste.filter_factory = pycadf.middleware.audit:AuditMiddleware.factory
+
+or
+
+::
+
+   [filter:audit]
+   paste.filter_factory = <project>.openstack.common.middleware.audit:AuditMiddleware.factory
+
+The filter should be included after Keystone's auth_token middleware so it can
+utilise environment variables set by Keystone's middleware.  Below is an
+example using Nova's WSGI pipeline::
+
+   [composite:openstack_compute_api_v2]
+   use = call:nova.api.auth:pipeline_factory
+   noauth = faultwrap sizelimit noauth ratelimit osapi_compute_app_v2
+   keystone = faultwrap sizelimit authtoken keystonecontext ratelimit audit osapi_compute_app_v2
+   keystone_nolimit = faultwrap sizelimit authtoken keystonecontext audit osapi_compute_app_v2
+
+.. _oslo.messaging: http://www.dmtf.org/standards/cadf
+.. _old notification system: https://github.com/openstack/oslo-incubator
+.. _middleware code base: https://github.com/openstack/oslo-incubator/tree/master/openstack/common/middleware
+
+Configure audit middleware
+==========================
+To properly audit api requests, the audit middleware requires an
+api_audit_map.conf to be defined. The project's corresponding
+api_audit_map.conf file is included in the `pyCADF library`_.
+
+By default, the audit middleware filter expects the map file to be located in
+the same folder as the other conf files related to the project
+(ie.'/etc/<project>' folder). This default functionality is to be deprecated
+and so the location should be specified explicitly by adding the path to the
+'audit_map_file' option of the filter definition::
+
+   [filter:audit]
+   paste.filter_factory = pycadf.middleware.audit:AuditMiddleware.factory
+   audit_map_file = /etc/nova/api_audit_map.conf
+
+Additional options can be set::
+
+   [filter:audit]
+   paste.filter_factory = pycadf.middleware.audit:AuditMiddleware.factory
+   audit_map_file = /etc/nova/api_audit_map.conf
+   service_name = test # opt to set HTTP_X_SERVICE_NAME environ variable
+   ignore_req_list = GET,POST # opt to ignore specific requests
+
+.. _pyCADF library: https://github.com/openstack/pycadf/tree/master/etc/pycadf
diff --git a/doc/source/specification/attachments.rst b/doc/source/specification/attachments.rst
new file mode 100644
index 0000000..beba392
--- /dev/null
+++ b/doc/source/specification/attachments.rst
@@ -0,0 +1,58 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _attachments:
+
+============
+ Attachments
+============
+
+An attachment is a container for data or "content" that may follow any
+structure – from an atomic type to a complex hierarchy. However, it is
+desirable for processing and interoperability that the type – or
+structure – of the content be identified by a simple value. To this end the
+attachment also contains a "content type", i.e., a URI that identifies the
+kind of content.
+
+Attachments are intended to be used for inclusion of domain-specific,
+informative, or descriptive information.
+
+=========== ========= ======== ======================================================================================
+Property    Type      Required Description
+=========== ========= ======== ======================================================================================
+typeURI     xs:anyURI Yes      The URI that identifies the type of data contained in the "content" property.
+content     xs:any    Yes      A container that contains any type of data (as defined by the "contentType" property).
+contentType xs:string Yes      An optional name that can be used to provide an identifying name for the content.
+=========== ========= ======== ======================================================================================
+
+Serialisation
+=============
+
+json::
+
+   {
+    ...,
+    "attachments": [
+    {
+     "content": "xs:any",
+     "contentType": "xs:anyURI"
+    },
+    {
+     "content": "xs:any",
+     "contentType": "xs:anyURI"
+    }
+    ]
+   }
+
diff --git a/doc/source/specification/credentials.rst b/doc/source/specification/credentials.rst
new file mode 100644
index 0000000..0132150
--- /dev/null
+++ b/doc/source/specification/credentials.rst
@@ -0,0 +1,56 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _credentials:
+
+============
+ Credentials
+============
+
+This type provides a means to describe various credentials along with any
+information about the authority that is responsible for maintaining them.
+This is intended to be associated with a CADF Resource’s identity and reflects
+any authorizations or identity assertions the resource may use to gain access
+to other resources.
+
+========== ========= ======== ===================================================================================================
+Property   Type      Required Description
+========== ========= ======== ===================================================================================================
+type       xs:anyURI No       Type of credential. (e.g., auth. token, identity token, etc.)
+token      xs:any    Yes      The primary opaque or non-opaque identity or security token (e.g., an opaque or obfuscated user ID)
+authority  xs:anyURI No       The trusted authority (a service) that understands and can verify the credential.
+assertions cadf:Map  No       Optional list of additional assertions or attributes that belong to the credential
+========== ========= ======== ===================================================================================================
+
+Serialisation
+=============
+
+json::
+
+   {
+    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
+    "action": "authenticate",
+    ...,
+    "initiator": {
+       "id": "joe.user@tenant1.com",
+       "typeURI": "data/security/account/user",
+       ...,
+       "credential": {
+          "type": "https://mycloud.com/v2/token",
+          "token": "myuuid:1ef0-abdf-xxxx-xxxx"
+       }
+    }
+   }
+
diff --git a/doc/source/specification/endpoints.rst b/doc/source/specification/endpoints.rst
new file mode 100644
index 0000000..b64b4b6
--- /dev/null
+++ b/doc/source/specification/endpoints.rst
@@ -0,0 +1,53 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _endpoints:
+
+==========
+ Endpoints
+==========
+
+The Endpoint type is used to provide information about a resource's location
+on a network.
+
+======== ========= ======== =================================================================================
+Property Type      Required Description
+======== ========= ======== =================================================================================
+url      xs:anyURI Yes      The network address of the endpoint; for IP-based addresses
+name     xs:string No       An optional property to provide a logical name for the endpoint
+port     xs:string No       An optional property to provide the port value separate from the address property
+======== ========= ======== =================================================================================
+
+Serialisation
+=============
+
+json::
+
+   {
+    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
+    ...,
+    "target": {
+       "id": "myscheme://mydomain/resource/id/0001",
+       "name": "server_0001",
+       "addresses": [{
+           "name": "public",
+           "url": "http://mydomain/mypath/server-0001/"
+        },
+       ...
+       ],
+       ...
+    }
+   }
+
diff --git a/doc/source/specification/events.rst b/doc/source/specification/events.rst
new file mode 100644
index 0000000..9bcc311
--- /dev/null
+++ b/doc/source/specification/events.rst
@@ -0,0 +1,96 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _events:
+
+=======
+ Events
+=======
+
+The CADF Event Model applies semantics to the activities, resources,
+information, and changes within a cloud provider’s infrastructure and models
+these using the concept of an event.
+
+============= =================== ========= =============================================================================================================================================================
+Property      Type                Required  Description
+============= =================== ========= =============================================================================================================================================================
+id            cadf:Identifier     Yes       The unique identifier of the CADF Event Record
+typeURI       cadf:Path           Dependent Can be used to declare versioning of Events.
+eventType     xs:string           Yes       The classification of the type of event
+eventTime     cadf:Timestamp      Yes       The OBSERVER's best estimate as to the time the Actual Event occurred or began
+action        cadf:Path           Yes       This property represents the event's ACTION
+outcome       cadf:Path           Yes       A valid classification value from the CADF Outcome Taxonomy
+initiator     cadf:Resource       Dependent The event's INITIATOR. Required if not initiatorId
+initiatorId   cadf:Identifier     Dependent The event's INITIATOR resource by reference. Required if not initiator
+target        cadf:Resource       Dependent The event's TARGET. Required if not targetId
+targetId      cadf:Identifier     Dependent The event's TARGET by reference. Required if not target
+observer      cadf:Resource       Dependent The event's OBSERVER. Required if not observerId
+observerId    cadf:Identifier     Dependent The event's OBSERVER by reference. Required if not observer
+reason        cadf:Reason         No        Domain-specific reason code and policy data that provides an additional level of detail to the outcome value. Required if the eventType property is "control"
+severity      xs:string           No        Describes domain-relative severity assigned to the event by the OBSERVER. This property's value is non-normative
+measurements  cadf:Measurement[]  Dependent Any measurement (values) associated with the event. Required if the eventType property is "monitor"
+name          xs:string           No        A descriptive name for the event
+tags          cadf:Tag[]          No        Array of Tags that MAY be used to further qualify or categorize the CADF Event Record
+attachments   cadf:Attachment[]   No        Array of extended or domain-specific information about the event or its context
+reporterchain cadf:Reporterstep[] No        Array of Reporterstep typed data that contains information about the sequenced handling of or change to the associated CADF Event Record by any REPORTER
+============= =================== ========= =============================================================================================================================================================
+
+Serialisation
+=============
+
+json::
+
+   {
+    'typeURI': 'http://schemas.dmtf.org/cloud/audit/1.0/event',
+    'id': 'openstack:a80dc5ee-be83-48ad-ad5e-6577f2217637‘,
+    'eventType': 'activity',
+    'action': 'read',
+    'outcome': 'success',
+    'reason': {'reasonCode': '200', 'reasonType': 'HTTP'},
+    'eventTime': '2014-01-17T23:23:38.109989+0000',
+    'initiator': {
+          'id': 'openstack:95f12d248a234a969f456cd2c794f29a'
+          'typeURI': 'service/security/account/user',
+          'name': ‘admin',
+          'project_id': 'openstack:e55b158759854ea6a7852aa76632c6c1',
+          'credential': {
+                   'token': ‘MIIQBgYJKoZIhvcNAQcCoIIP9z xxxxxx KoZIhvcIP9z=‘,
+                   'identity_status': 'Confirmed'},
+          'host': {
+                   'agent': 'python-novaclient',
+                   'address': '9.26.27.109'},
+    },
+    'target': {
+         'id': 'openstack:0f126160203748a5b4923f2eb6e3b7db',
+         'typeURI': ‘service/compute/servers',
+         'name': 'nova‘
+         'addresses': [
+              {'url': 'http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1',
+               'name': 'admin'},
+              {'url': 'http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1',
+               'name': 'private'},
+              {'url': 'http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1',
+               'name': 'public'}
+          ],
+    },
+    'observer': { 'id': 'target'},
+    'reporterchain': [
+         {'reporterTime': '2014-01-17T23:23:38.154152+0000',
+          'role': 'modifier',
+          'reporter': {'id': 'target'}}
+     ],
+    'requestPath': '/v2/56600971-90f3-4370-807f-ab79339381a9/servers',
+    'tags': ['correlation_id?value=openstack:bcac04dc-e0be-4110-862c-347088a7836a']
+   }
diff --git a/doc/source/specification/geolocations.rst b/doc/source/specification/geolocations.rst
new file mode 100644
index 0000000..43211b3
--- /dev/null
+++ b/doc/source/specification/geolocations.rst
@@ -0,0 +1,88 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _geolocations:
+
+=============
+ Geolocations
+=============
+
+Geolocation information, which reveals a resource’s physical location, is
+obtained by using tracking technologies such as global positioning system
+(GPS) devices, or IP geolocation by using databases that map IP addresses to
+geographic locations. Geolocation information is widely used in
+context-sensitive content delivery, enforcing location-based access
+restrictions on services, and fraud detection and prevention.
+
+Due to the intense concerns about security and privacy, countries and regions
+introduced various legislation and regulation. To determine whether an event
+is compliant sometimes depends on the geolocation of the event. Therefore, it
+is crucial to report geolocation information unambiguously in an audit trail.
+
+=========== ========= ======== ===============================================================================================================
+Property    Type      Required Description
+=========== ========= ======== ===============================================================================================================
+id          xs:anyURI No       Optional identifier for a geolocation
+latitude    xs:string No       The latitude of a geolocation
+longitude   xs:string No       The longitude of a geolocation
+elevation   xs:double No       The elevation of a geolocation in meters
+accuracy    xs:double No       The accuracy of a geolocation in meters
+city        xs:string No       The city of a geolocation
+state       xs:string No       The state/province of a geolocation
+regionICANN xs:string No       A region (e.g., a country, a sovereign state, a dependent territory or a special area of geographical interest)
+annotations cadf:Map  No       User-defined geolocation information (e.g., building name, room number)
+=========== ========= ======== ===============================================================================================================
+
+Usage Requirements
+==================
+1. Geolocation typed data SHALL contain at least one valid property and
+   associated value.
+
+2. Geolocation typed data SHALL NOT be used to represent virtual or logical
+   locations (e.g. network zone).
+
+3. For each geolocation data instance, the properties SHALL be consistent.
+   That is, all properties SHALL consistently represent the same geographic
+   location and SHALL NOT provide conflicting value data.
+
+::
+
+   Example: ‘latitude’, ‘longitude’ and ‘region’ are all supplied as
+   properties describing the same geolocation, the 'latitude' and
+   'longitude' properties' coordinate values should resolve to the
+   same geographic location as described by the 'region'
+   property's value.
+
+4. ICANN's implementation plan states "Upper and lower case characters are
+   considered to be syntactically and semantically identical"; therefore,
+   the "regionICANN" property's values MAY be either upper or lower case.
+
+Serialisation
+=============
+
+json::
+
+   {
+    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
+    ...,
+    "target": {
+               ...,
+               "geolocation": {
+                               "latitude": "+372207.90",
+                               "longitude": "-1220210.20",
+                               "elevation": "10"
+               }
+    }
+   }
diff --git a/doc/source/specification/hosts.rst b/doc/source/specification/hosts.rst
new file mode 100644
index 0000000..f77c130
--- /dev/null
+++ b/doc/source/specification/hosts.rst
@@ -0,0 +1,54 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _hosts:
+
+======
+ Hosts
+======
+
+Most resources that are referenced in an IT or cloud infrastructure are
+conceptually "hosted on" or "hosted by" other resources. For example,
+"applications" are hosted on "web servers" or "users" may be hosted on a
+"network connected device" or a "terminal". In addition, networked resources
+are "hosted" by some device attached to some network.
+
+The host resource often provides context or location information for the
+resource it is hosting at the time the Actual Event was observed and recorded
+(e.g., an IP address, software agent, platform, etc.). Providing a means to
+record host information with a CADF Event Record is valuable for audit purposes
+because compliance policies and rules are often based on such information.
+
+======== =============== ======== ==============================================
+Property Type            Required Description
+======== =============== ======== ==============================================
+id       cadf:Identifier No       The optional identifier of the host RESOURCE
+address  xs:anyURI       No       The optional address of the host RESOURCE
+agent    xs:string       No       The optional agent (name) of the host RESOURCE
+platform xs:string       No       The optional platform of the host RESOURCE
+======== =============== ======== ==============================================
+
+Serialisation
+=============
+
+json::
+
+   {
+    "id": "myuuid:1234-5678-90abc-defg-0000",
+    "address": "10.0.2.15",
+    "agent": "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:18.0)",
+    "platform": "Linux version 3.5.0-23-generic (gcc version 4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5) ) #35~precise1-Ubuntu SMP Fri Jan 25 17:15:33 UTC 2013"
+   }
+
diff --git a/doc/source/specification/identifiers.rst b/doc/source/specification/identifiers.rst
new file mode 100644
index 0000000..55bc65d
--- /dev/null
+++ b/doc/source/specification/identifiers.rst
@@ -0,0 +1,33 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _identifiers:
+
+============
+ Identifiers
+============
+
+This specification defines an Identifier type that is based upon the Uniform
+Resource Identifier Reference (URI) as specified in RFC3986. Any value that
+represents a CADF Identifier type in this specification, its extensions, or
+profiles SHALL adhere to the requirements listed in this section:
+
+.. note::
+
+   CADF Identifier type values SHALL be created to be Universally Unique
+   Identifiers (UUIDs) so that when CADF data (e.g., CADF Event Records, Logs,
+   Reports, Resources, Metrics, etc.) are federated it will be uniquely
+   identifiable to the source (e.g., cloud provider, service, etc.) that
+   created them.
diff --git a/doc/source/specification/index.rst b/doc/source/specification/index.rst
new file mode 100644
index 0000000..56d2e06
--- /dev/null
+++ b/doc/source/specification/index.rst
@@ -0,0 +1,28 @@
+==============
+ Specification
+==============
+
+The following is a high-level description of the CADF specification. The basic
+component of the CADF spec are Events. The full CADF specification document
+can be found here_.
+
+.. _here: http://www.dmtf.org/standards/cadf
+
+.. toctree::
+   :maxdepth: 2
+
+   events
+   attachments
+   credentials
+   endpoints
+   geolocations
+   hosts
+   identifiers
+   measurements
+   paths
+   reasons
+   reportersteps
+   resources
+   tags
+   timestamps
+   taxonomy
diff --git a/doc/source/specification/measurements.rst b/doc/source/specification/measurements.rst
new file mode 100644
index 0000000..afbea8d
--- /dev/null
+++ b/doc/source/specification/measurements.rst
@@ -0,0 +1,77 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _measurements:
+
+=============
+ Measurements
+=============
+
+A component that contains statistical or measurement information for TARGET
+resources that are being monitored. The measurement should be based upon a
+defined metric (a method of measurement).
+
+============ =============== ========= =================================================================================================================
+Property     Type            Required  Description
+============ =============== ========= =================================================================================================================
+result       xs:any          Yes       The quantitative or qualitative result of a measurement from applying the associated metric
+metric       cadf:Metric     Dependent The property describes the metric used in generating the measurement result. Required if not metricId
+metricId     cadf:Identifier Dependent This property identifies a CADF Metric by reference and whose definition exists elsewhere. Required if not metric
+calculatedBy cadf:Resource   No        An optional description of the resource that calculated the measurement
+============ =============== ========= =================================================================================================================
+
+Metrics
+=======
+
+The Metric data type describes the rules and processes for measuring some
+activity or resource, resulting in the generation of some values (captured by
+the Measurement type).
+
+=========== =============== ======== ==================================================
+Property    Type            Required Description
+=========== =============== ======== ==================================================
+metricId    cadf:identifier Yes      The identifier for the metric.
+unit        xs:string       Yes      The metrics unit (e.g., "ms", "Hz", "GB", etc.)
+name        xs:string       No       A descriptive name for metric
+annotations cadf:map        No       User-defined metric information.
+=========== =============== ======== ==================================================
+
+Serialisation
+=============
+
+json::
+
+   {
+    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/log",
+    ...,
+    "metrics": [
+    {
+     "metricId": "myuuid://metric.org/1234",
+     "unit": "GB",
+     "name": "Storage Capacity in Gigabytes"
+    }],
+    ...,
+    "events": [
+    {
+     "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
+     ...,
+     "measurements": [
+     {
+      "result": "10",
+      "metricId": "myuuid://metric.org/1234"
+     }],
+     ...
+     }]
+    }
diff --git a/doc/source/specification/paths.rst b/doc/source/specification/paths.rst
new file mode 100644
index 0000000..ad9a063
--- /dev/null
+++ b/doc/source/specification/paths.rst
@@ -0,0 +1,25 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _paths:
+
+======
+ Paths
+======
+
+This clause describes how to represent values that are elements of hierarchies.
+This construct is used for example when providing values from CADF Taxonomies
+that classify components of the CADF Event Model within CADF Event Records as
+path values.
diff --git a/doc/source/specification/reasons.rst b/doc/source/specification/reasons.rst
new file mode 100644
index 0000000..aed4e20
--- /dev/null
+++ b/doc/source/specification/reasons.rst
@@ -0,0 +1,49 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _reasons:
+
+========
+ Reasons
+========
+
+A component that contains a means to provide additional details and further
+classify the top-level OUTCOME of the ACTION included in a CADF Event Record.
+
+========== ========= ======== =====================================================================================================================
+Property   Type      Required Description
+========== ========= ======== =====================================================================================================================
+reasonType xs:anyURI No       The domain URI that defines the "reasonCode" property's value
+reasonCode xs:string No       An optional detailed result code as described by the domain identified in the "reasonType" property
+policyType xs:anyURI No       The domain URI that defines the "policyId" property’s value
+policyId   xs:string No       An optional identifier that indicates which policy or algorithm was applied in order to achieve the described OUTCOME
+========== ========= ======== =====================================================================================================================
+
+Serialisation
+=============
+
+json::
+
+   {
+    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
+    ...,
+    "reason": {
+               "reasonType": "http://www.iana.org/assignments/http-status-codes/http-status-codes.xml",
+               "reasonCode": "408",
+               "policyType": "http://schemas.xmlsoap.org/ws/2002/12/policy",
+               "policyId": "http://10.0.3.4/firewall-ruleset/rule0012"
+    },
+    ...
+   }
diff --git a/doc/source/specification/reportersteps.rst b/doc/source/specification/reportersteps.rst
new file mode 100644
index 0000000..40bbf26
--- /dev/null
+++ b/doc/source/specification/reportersteps.rst
@@ -0,0 +1,60 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _reportersteps:
+
+==============
+ Reportersteps
+==============
+
+This type represents a step in the REPORTERCHAIN that captures information
+about any notable REPORTER (in addition to the OBSERVER) that modified or
+relayed the CADF Event Record and any details regarding any modification it
+performed on the CADF Event Record it is contained within.
+
+The Reporterstep data type should capture information about the resources that
+have had a role in modifying, or relaying the CADF Event Record during its
+lifecycle after having been created by the OBSERVER.
+
+============ ================= ========= ==========================================================================================================================
+Property     Type              Required  Description
+============ ================= ========= ==========================================================================================================================
+role         xs:string         Yes       The role the REPORTER performed on the CADF Event Record (e.g., an "observer", "modifier" or "relay" role)
+reporter     cadf:Resource     Dependent This property defines the resource that acted as a REPORTER on a CADF Event Record. Required if not reporterId
+reporterId   cadf:Identifier   Dependent This property identifies a resource that acted as a REPORTER on a CADF Event Record by reference. Required if not reporter
+reporterTime cadf:Timestamp    No        The time a REPORTER adds its Reporterstep entry into the REPORTERCHAIN
+attachments  cadf:Attachment[] No        An optional array of additional data containing information about the reporter or any action it performed
+============ ================= ========= ==========================================================================================================================
+
+Serialisation
+=============
+
+json::
+
+   {
+    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
+    ...,
+    "reporterchain": [
+    {
+     "role": "modifier",
+     "reporterTime": "2012-03-22T13:00:00-04:00",
+     "reporter": {
+                  "id": "myscheme://mydomain/resource/monitor/id/0002"
+     }
+    },
+    ...
+    ]
+   }
+
diff --git a/doc/source/specification/resources.rst b/doc/source/specification/resources.rst
new file mode 100644
index 0000000..9225baa
--- /dev/null
+++ b/doc/source/specification/resources.rst
@@ -0,0 +1,64 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _resources:
+
+==========
+ Resources
+==========
+
+Resources in general can be used to describe traditional IT components
+(e.g., servers, network devices, etc.), software components
+(e.g., platforms, databases, applications, etc.), operational and business
+data (e.g., accounts, users, etc.) and roles, which can be assigned to
+persons, that describe the authority to access capabilities.
+
+============= ================= ========= ===================================================================================================================================
+Property      Type              Required  Description
+============= ================= ========= ===================================================================================================================================
+id            cadf:Identifier   Yes       The identifier for the resource
+typeURI       cadf:Path         Yes       The classification (i.e., type) of the resource using the CADF Resource Taxonomy
+name          xs:string         No        The optional local name for the resource (not necessarily unique)
+domain        xs:string         No        The optional name of the domain that qualifies the name of the resource
+credential    cadf:Credential   No        The optional security credentials associated with the resource’s identity
+addresses     cadf:Endpoint[]   No        The optional descriptive addresses (including URLs) of the resource
+host          cadf:Host         No        The optional information about the (network) host of the resource
+geolocation   cadf:Geolocation  Dependent This optional property describes the geographic location of the resource using Geolocation data type. Required if not geolocationId
+geolocationId cadf:Identifier   Dependent This optional property identifies a CADF Geolocation by reference. Required if not geolocation
+attachments   cadf:Attachment[] No        An optional array of extended or domain-specific information about the resource or its contex
+============= ================= ========= ===================================================================================================================================
+
+Serialisation
+=============
+
+json::
+
+   {
+    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
+    ...,
+    "target": {
+               "id": "myscheme://mydomain/resource/id/0001",
+               "typeURI": "service/compute",
+               "name": "server_0001",
+               ...,
+               "geolocation": {
+                               "city": "Austin",
+                               "state": "TX",
+                               "regionICANN": "US"
+               }
+    }
+   }
+
+
diff --git a/doc/source/specification/tags.rst b/doc/source/specification/tags.rst
new file mode 100644
index 0000000..9a67353
--- /dev/null
+++ b/doc/source/specification/tags.rst
@@ -0,0 +1,29 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _tags:
+
+=====
+ Tags
+=====
+
+A "tag" is a label that can be added to a CADF Event Record to qualify or
+categorize an event.
+
+Tags provide a powerful mechanism for adding domain-specific identifiers and
+classifications to CADF Event Records that can be referenced by the CADF Query
+Interface. This allows customers to construct custom reports or views on the
+event data held by a provider for a specific domain of interest. A CADF Event
+Record can have multiple tags that enable cross-domain analysis.
\ No newline at end of file
diff --git a/doc/source/specification/taxonomy.rst b/doc/source/specification/taxonomy.rst
new file mode 100644
index 0000000..185ea27
--- /dev/null
+++ b/doc/source/specification/taxonomy.rst
@@ -0,0 +1,33 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _taxonomy:
+
+=========
+ Taxonomy
+=========
+
+The CADF Resource Taxonomy describes resources that are commonly used in cloud
+and enterprise infrastructures. This list was developed based on surveys of
+existing cloud architectures, deployments, and implementations. The Resource
+Taxonomy, however, is fully intended to be extensible by profiles that may
+define additional resource nodes as child nodes to the ones specified below.
+When doing so, however, vendors and cloud providers should be aware that this
+places an additional burden on the consumer to correctly comprehend the new
+node type. Therefore, vendors and providers of CADF audit data should be
+careful to provide classification values that extend the existing tree from the
+most granular node that closely matches the functions of any newly-defined
+resource types. This approach will provide consumers with a baseline
+understanding of the function of the new resource type.
\ No newline at end of file
diff --git a/doc/source/specification/timestamps.rst b/doc/source/specification/timestamps.rst
new file mode 100644
index 0000000..d5f964f
--- /dev/null
+++ b/doc/source/specification/timestamps.rst
@@ -0,0 +1,34 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _timestamps:
+
+===========
+ Timestamps
+===========
+
+The following example shows the required Lexical representation of the
+Timestamp type used in this specification; all Timestamp typed values
+SHALL be formatted accordingly:
+
+::
+
+   yyyy '-' mm '-' dd 'T' hh ':' mm ':' ss ('.' s+)('+' | '-') hh ':' mm
+
+.. note::
+
+   The UTC offset is always required (not optional) and the use of the
+   character 'Z' (or 'Zulu' time) as an abbreviation for UTC offset +00:00
+   or -00:00 is NOT permitted.
\ No newline at end of file