Data Item Dataset Spec

Data Item Dataset JSON API schema

This is the spec for any datasets that are stored in Shape DataItems and displayed to the user in various chart formats.

Future functionality may allow for a remote URL for a Data Item. This will load data from their API endpoint, which must conform to this spec.

The chart item payload that we expect your endpoint to respond with is:

{
  "id": "3ecb7b8a-c666-49b2-ba76-43f2b9a6fbe2",
  "type": "chart_data",
  "attributes": {
    "title": "Creative Qualities",
    "subtitle": "Your scores for 509 survey respondents",
    "datasets": [
      {
        "chart_type": "area",
        "measure": "Purpose",
        "grouped_by": "Business Unit 1",
        "timeframe": "month",
        "order": 0,
        *"description": "The degree to which there is alignment about a meaningful change that leadership and employees want to make in the world.",
        *"max_domain": 100,
        *"style": {
          "fill": "#9874AB",
        },
        *"single_value": 250,
        "data": [
          { "value": 25, "date": "01-24-2018" },
          { "value": 20, "date": "06-15-2018" },
          { "value": 30, "date": "01-10-2019" },
          { "value": 45, "date": "05-15-2019" }
        ]
      },
      {
        "chart_type": "line",
        "measure": "Looking Out",
        "grouped_by": "Business Unit 1",
        "description": "The degree to which employees get insights and inspiration from beyond the company’s walls. ",
        "order": 1,
        "timeframe": "month",
        *"max_domain": 100,
        *"style": {
          "fill": "#9A4F7A"
        },
        "data": [
          { "value": 18, "date": "02-14-2018" },
          { "value": 20, "date": "07-07-2018" },
          { "value": 25, "date": "01-25-2019" },
          { "value": 32, "date": "05-28-2019" }
        ]
      }
    ],
    "filters": [
      {
        "title": "Other Public Business Unit",
        "params": { "business_unit_id": "78" }
      },
      {
        "title": "All In Your Industry",
        "params": { "industry_id": "56" }
      },
      {
        "title": "All Organizations",
        "params": { "all": "true" }
      }
    ]
  },
  "relationships": [],
  "links": {
    "self": "https://creativedifference.ideo.com/api/v4/scores"
  }
}

Notes:

• * optional parameters
• Filters can be used independently or combined, using the params provided, appended to the self link.
• index is the indicator for which should be the primary dataset (index 0), which will define the chart's axis/labels.
• A column's icon_url for columns supports png, jpg and svg image formats.
• The root id is required to adhere to JSON:API spec, but is not used.

Future Functionality:

If your endpoint is private, you can also add an authorization header token, which will be sent as 'Authorization': "Bearer {token}" when making requests to your endpoint.

External Data Formats:

In order to render using an external data format, the cached_data value must be set along with the required dataset fields. To quickly you can run the following command in the console:

external_dataset = Dataset::External.new(order: 0, timeframe: :month, chart_type: :line, measure: 'Monthly Active Users', cached_data: [{date: "2020-07-01", value: 252}, {date: "2020-06-01", value: "351"}], cached_data_items_datasets: {order: 0}])
my_data_item = Item::DataItem.last
my_data_item.datasets << external_dataset
my_data_item.update(primary_dataset: external_dataset)

Related resources:

• Shape glossary
• Grouping variables spreadsheet