diff --git a/README.md b/README.md
index 5b2c0bfb..67e88f85 100644
--- a/README.md
+++ b/README.md
@@ -5,26 +5,36 @@ A python REST orchestrator to translate a YAML host topology to a provisioned se
 
 ### Design Consumer ###
 
+aka smelter
+
 Pluggable service to ingest a inventory/design specification, convert it to a standard
 internal representaion, and persist it to the Design State API. Initial implementation
 is the consumer of AIC YAML schema.
 
 ### Design State API ###
 
+aka tarot
+
 API for querying and updating the current design specification and persisted orchestration status.
 CRUD support of CIs that are not bootstrap-related, but can be used by other automation.
 
 ### Control API ###
 
+aka cockpit
+
 User-approachable API for initiating orchestration actions or accessing other internal
 APIs
 
 ### Infrastructure Orchestrator ###
 
+aka alchemist
+
 Handle validation of complete design, ordering and managing downstream API calls for hardware
 provisioning/bootstrapping
 
-### Server Driver ###
+### Server Driver ### 
+
+aka maasdriver
 
 Pluggable provisioner for server bootstrapping. Initial implementation is MaaS client.
 
@@ -34,5 +44,7 @@ Pluggable provisioner for network provisioning. Initial implementation is Noop.
 
 ### Introspection API ###
 
+aka jabberwocky
+
 API for bootstrapping nodes to load self data. Possibly pluggable as this is basically an
 authenticated bridge to the Design State API
\ No newline at end of file
diff --git a/examples/bootstrap_hwdefinition.yaml b/examples/bootstrap_hwdefinition.yaml
index b457f2ce..54c69ac1 100644
--- a/examples/bootstrap_hwdefinition.yaml
+++ b/examples/bootstrap_hwdefinition.yaml
@@ -17,6 +17,13 @@
 # bootstrap_hwdefinition.yaml - Definitions of server hardware layout
 #
 #############################################################################
+# version the schema in this file so consumers can rationally parse it
+apiVersion: v1
+kind: hardware_profile
+metadata:
+  date: 17-FEB-2017
+  name: Sample hardware definition
+  author: Scott Hussey
 hardware_definition:
   # Name of the hardware type. This name will be used in bootstrap.yaml to refer back
 - name: HPGen8v3
diff --git a/examples/bootstrap_seed.yaml b/examples/bootstrap_seed.yaml
index 649a8331..23f6a1f8 100644
--- a/examples/bootstrap_seed.yaml
+++ b/examples/bootstrap_seed.yaml
@@ -17,6 +17,13 @@
 # bootstrap_seed.yaml - Site server design definition for physical layer
 #
 ####################
+# version the schema in this file so consumers can rationally parse it
+apiVersion: v1
+kind: site_design
+metadata:
+  date: 17-FEB-2017
+  name: Sample site design
+  author: Scott Hussey
 site_name: sitename
 network:
   # Describe layer 1 attributes. Primary key is 'name'. These settings will