model3.js

/* OpenSpending Model File, v3 (proposed)

This aims to incorporate features as per: 
https://github.com/okfn/openspending/issues?labels=feature.model3&sort=created&direction=desc&state=open&page=1

*/

var model_proposal_fl2 = {
  "dataset": {
    /* Basic dataset metadata, largely unchanged. */
    "schema_version": 3,
    "name": "greece",
    "label": "The Full Truth About The Economic Situation of Greece (abridged)",
    "description": "This data has been collected by my homeboy Sarkoz, .... ",

    /* Re #215: dataset natures for filtering: 
    * Regarding the terminology, "natures" are used in Eclipse for tag-typing:
    * http://www.eclipse.org/articles/Article-Builders/builders.html#2
    * */
    "natures": ["government", "spending"],
    /* Other options: party, funding, grants, budget */

    /* Re #58 (implied): ISO 3166-1 country code. 
    * Allows for extensions such as "EU" (European Union). Sub-national granularity
    * is not considered in this draft.
    */
    "country": "GR",

    /* Re #58: ISO 639-1 content language */
    "language": "EL",

    /* Re #258: default time */
    "default_time": "2011",
    /* TODO: does this imply granularity or do we make that explicit? */

    /* Fallback re #252: currencies. 
    * The specification of a year of valuation is optional and will be passed into
    * monetary transformations if needed. 
    */
    "currency": "EUR:2011"

    /* Re #253 (unique_keys): not the absence of unique_keys here. */
  },
  /* Re #208: Split of mapping and model core definition. */
  "dimensions": {
    /* Not using 'model' as a name as it also applies to the whole. */

    "amount": {
      /* Q: do we still require default schema name "amount"? I'd say yes. */

      /* New type (supported since 0.10): */
      "type": "measure",

      /* implied (do we even need it?): */
      "datatype": "decimal", /* not 'float' */

      "label": "Amount granted.",
      "description": "...",

      /* Re #252: currencies; explicit definition for this dimension. */
      "currency": "EUR:2011"

      /* Q: how does this imply the creation of normalized measures?
      *
      * Option 1: there is automatically a normalized shadow dimension, e.g.
      *   "amount.norm", which has currency USD:2000 and can be queried
      *   independently.
      *
      * Option 2: user can explicitly define a second measure of any name and
      *   specify a conversion to take place.
      *
      * Option 3: a conversion factor is stored in dataset metadata and 
      *   conversion is performed on all output at query time.
      */
    },

    "time": {
      /* Q: do we still require default schema name "time"? I'd say yes. */

      /* New type (supported since 0.10): */
      "type": "date",

      /* Q: do we want to support date format strings? */
      "datatype": "date",

      "label": "Date of grant", 
      "description": "...",
    },

    "transaction_id": {
      "type": "attribute", /* replaces: 'value' */

      /* One of: string, float, decimal, integer, date ? */
      "datatype": "string",

      "label": "Transaction ID", 
      "description": "...",

      /* Replacement for unique_keys: */
      "key": true,

      /* Make this a column in browser views (currently this is always 
      * 'to', 'from' - and, implicitly, 'amount' and 'time').
      */
      "browser_column": true
    },

    "beneficiary": {
      /* Could be any value: */
      "type": "compound",

      "label": "Beneficiary of the Funds",
      "description": "...",

      "attributes": {
        /* Using dictionary instead of "name" key: */
        "name": {
          "datatype": "id",
          "default_value": "undefined",

          /* There can be many of those: */
          "key": true
        },
        "label": {
          "datatype": "string",
          "default_value": "(Undefined)",
        }
      },

      /* Include as facet in browser: */
      "facet": true,

      "browser_column": true
    },

    /* And, a classification. Exciting absence of "taxonomy". */
    "cofog1": {
      "type": "compound", 
      "label": "COFOG-1", 
      "description": "...",
      
      "attributes": {
        "name": {"datatype": "id"},
        "label": {"datatype": "string"}
      },

      "facet": true
    },

    "cofog2": {
      "type": "compound", 
      "label": "COFOG-2", 
      "description": "...",

      /* Re #207: This one specifies the dimension, but we also need 
      * an attribute to specify the name of the dimension name. 
      */
      "parent": "cofog1",
      
      "attributes": {
        "name": {"datatype": "id", "key": true},
        "label": {"datatype": "string"},
        "parent": {"datatype": "id"}
      },
      
    }

    /* Q: do we really still need constant values? Don't see a use case
    * any longer with bunkered datasets.
    */
    
    /* Note that we're not requiring "to" and "from" any longer. */
  },

  "mapping": {
    /* Given that source references are also stored within OS, this can 
    * also easily be associated with a source, rather than the whole dataset.
    */
  
    /* for attribute dimensions, dates and measures: */
    "amount": "AMOUNT",
    "time": "DAY",
    "transaction_id": "TX",
    
    /* for compound dimensions, use a dictionary instead: */
    "beneficiary": {
      "name": "BENEFICIARY",
      "label": "BENEFICIARY"
    },

    "cofog1": {
      "name": "COFOG1_ID",
      "label": "COFOG1_NAME"
    },

    "cofog2": {
      "name": "COFOG2_ID",
      "label": "COFOG2_NAME",
      /* parent member selector: */
      "parent": "COFOG1_ID"
    }
  },

  "views": [
    /* There are now 'only' two types of views: those that apply to datasets
    * and those which apply to dimensions.
    */

    /* Dataset: */
    {
      "name": "default",
      "label": "By Beneficiary",
      "dimension": "dataset",
      "dilldown": "beneficiary",
      "cuts": {}
    },

    /* Dataset for bubbletree (multiple drilldowns): */
    {
      "name": "cofog",
      "label": "By Function",
      "dimension": "dataset",
      "dilldown": ["cofog1", "cofog2"],
      "cuts": {}
    },

    /* Dimension: */
    {
      "name": "default",
      "label": "By Function",
      "dimension": "beneficiary",
      "dilldown": "cofog1",
      "cuts": {}
    }
  ]
}