Adds dataset spec.

diff --git a/docs/dataset-spec.yaml b/docs/dataset-spec.yaml
new file mode 100644 (file)
index 0000000..f997307
--- /dev/null
+++ b/docs/dataset-spec.yaml
@@ -0,0 +1,33 @@
+###  Kraken Dataset Spec  ###
+
+# Describes the format of dataset json/yaml files for use in the Kraken chart UI.
+# Reminder: the project transparently compiles any .yaml files requested as .json
+# at request time -- you're welcome to write them in either form.
+
+
+id     : Unique identifier for this dataset. This file should be named `{id}.{ext}`
+         and live in the data directory alongside the data file.
+name   : Human-friendly name for the dataset.
+format : Data format. Valid: csv, json. (Maybe in the future: yaml, xml, etc.)
+url    : Canonical URL for the dataset's data file: /data/
+
+# Timespan and quanta covered by this dataset
+timespan :
+    start : Start of the dataset, eg: 2012-01-01T00:00:00 or 2012-01-01 or 1325404800
+            All dates should be seconds-since-the-epoch, or ISO-8601 formatted: YYYY-MM-DDThh:mm:ss.s
+            See also: http://www.w3.org/TR/NOTE-datetime
+    end   : End of the dataset, eg: 2012-02-01T00:00:00 or 2012-02-01 or 1328083200
+    step  : Amount of time between elapsed between each row, measured in seconds, eg: 86400
+
+# Metadata about the datatypes
+columns :
+    labels : List of the column-names in order. (Future optimization: the date column could 
+             be omitted if the data is sorted and contains no gaps -- each datapoint is exactly
+             timespan.step apart, and none are missing.)
+    types  : List of the column datatype-names in order. Valid type names: date, float, int.
+
+# Defaults for charting
+chart :
+    library : Visualization library to use. Valid: dygraphs.
+    options : Dict of option-names to values.
+