pycadf documentation

add basic documentation on CADF spec.

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

16 files changed, 837 insertions, 0 deletions

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