fix yaml syntax, update README for conformance/

conformance/README

@@ -1,8 +1,11 @@
 This directory contains files with a .crit extension
 
-These .crit files are in yaml format.
+These .crit files are in yaml format:
+ * 'text' is the content that appears in checklist and guidance pages
+ * 'level' is a keyword as defined in IETF RFC 2119 (but lower case preffered)
+ * 'parent' is the path-like label of the information node that provides context for the criteria. File extensions are dropped, (e.g. html, rst. or md), spaces and  underscores are equivalent, and case insensitive.
 
-Their names are unimportant, but have been chosen to make it easy to find the one you want to edit. This is a bit of a problem.
+File name of .crit files are ignored, but have been chosen to make it easy to find the one you want to edit. This is a bit of a problem, but exists to support inferior markdown workflows (rst worklows will generate random filenames, because .crit files will be generated from admonition type directives, and application workflows will have primary key identifiers).
 
 Their content has been coppied from text in the apiguide. The intention is that they could be generated from adminitions (in rst) or kept separately in .crit files (for markdown), or in a app's datastore.
 

conformance/api_survey.crit

@@ -1,5 +1,5 @@
 Criteria:
   text: "less than 20% of feedback rates the API as hard to use."
-  level: should
-  parent: principles/empathy
+  level: "should"
+  parent: "principles/empathy"
 

conformance/divergance_rationale.crit

@@ -1,5 +1,5 @@
 Criteria:
   text: "Any divergence from the standards specified in this guide must include a rationale."
-  level: must
-  parent: principles/special circumstances
+  level: "must"
+  parent: "principles/special circumstances"
 

conformance/new_api_conformance.crit

@@ -1,5 +1,5 @@
 Criteria:
   text: "All new or refreshed API development must conform to the standards in this guide."
-  level: must
-  parent: principles/standards
+  level: "must"
+  parent: "principles/standards"
 

conformance/publish_and_support.crit

@@ -1,5 +1,5 @@
 Criteria:
   text: "All APIs are published, documented, and supported."
-  level: must
-  parent: principles/documentation
+  level: "must"
+  parent: "principles/documentation"
 

conformance/publish_sla.crit

@@ -1,5 +1,5 @@
 Criteria:
   text: "All APIs must have a published SLA and should behave accordingly."
-  level: must
-  parent: principles/availability
+  level: "must"
+  parent: "principles/availability"
 

conformance/retail_wholesale_parity.crit

@@ -1,5 +1,5 @@
 Criteria:
   text: "Any function that is available via a retail UI must also be available as a wholesale API."
-  level: must
-  parent: principles/functionality
+  level: "must"
+  parent: "principles/functionality"
 

conformance/security_controls.crit

@@ -1,5 +1,5 @@
 Criteria:
   text: "All APIs must specify their assurance level and must apply the relevant controls."
-  level: must
-  parent: principles/security
+  level: "must"
+  parent: "principles/security"
 

conformance/single_implementation.crit

@@ -1,5 +1,5 @@
 Criteria:
   text: "There should be only one API function for one business outcome (e.g. change an address)."
-  level: should
-  parent: principles/granularity
+  level: "should"
+  parent: "principles/granularity"
 

conformance/unexpected_behavior.crit

@@ -1,5 +1,5 @@
 Criteria:
   text: "No unexpected behaviour from any API in production release."
-  level: should
-  parent: principles/errors
+  level: "should"
+  parent: "principles/errors"
 

conformance/use_standards.crit

@@ -1,5 +1,5 @@
 Criteria:
   text: "Where an established and widely used information standard exists then it should be used."
-  level: should
-  parent: principles/community
+  level: "should"
+  parent: "principles/community"