Get Dataset Schema

Describe the dimensions, metrics and temporal behaviour of one dataset before querying it

GET /v1/datasets/{key}/schema

Get Dataset Schema

JavaScript

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/datasets/{key}/schema', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

200

{
  "key": "<string>",
  "label_key": "<string>",
  "kind": "<string>",
  "dimensions": {
    "key": "<string>",
    "label_key": "<string>",
    "field_type": "<string>",
    "group": "<string>",
    "i18n_namespace": {},
    "relation_label": {},
    "via": {}
  },
  "metrics": {
    "key": "<string>",
    "label_key": "<string>",
    "agg": "<string>",
    "decimals": 123,
    "suffix": {},
    "grouping_hint_key": {},
    "row_level": true
  },
  "default_metrics": {},
  "window_required": true,
  "time_axis_default": {},
  "data_version": {}
}

Return what a dataset can be grouped by and what it can measure. Query datasets accepts only the dimension and metric keys listed here, so this is the contract to build a query against rather than guessing field names.

The same native key can return different dimensions for different organizations: the schema is extended with the custom columns your organization defined on that entity. Fetch it per organization; do not cache one organization’s schema and reuse it for another.

On emissions, those custom columns come from every table an emission row comes from, prefixed by that source so two sources never share a key: custom_consumption_<key> (vehicle consumptions), custom_invoice_<key>, custom_waste_<key>, custom_purchase_<key>, custom_business_travel_<key>, custom_hotel_stay_<key>, custom_wastewater_<key>, custom_commuting_<key>, plus custom_vehicles_<key> and custom_facilities_<key>. They are always dimensions — an emission row is a day-by-gas slice of its source, so a number from the source (or from the record a relation points at) is never summed.

When your organization links a source that has no facility of its own to a facility with a relation column (a vehicle consumption’s “Facility”, a business trip’s “Sede”), facility on emissions becomes the facility each row belongs to: its own facility when it has one, otherwise the one the relation assigns. The facility’s other columns (country, facilities__*, custom_facilities_*) follow it. The most specific source wins for each row: its own facility first, then a relation on the row’s source (a consumption’s “Facility”, which is where the vehicle was that day), then one on its vehicle, which only fills the consumptions that say nothing. So adding a relation, or leaving a new one empty, never moves a row away from the facility it had. If two facility columns on the same record point at different facilities, neither is used for that record (its vehicle’s relation, if any, still applies). Without such a relation, facility keeps its meaning.

Request

Headers

x-api-key · string · required

Your API key for authentication

Example: sk_live_1234567890abcdef

x-organization-id · string · required

Your organization UUID

Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

key · string · required

Dataset key from List Available Datasets — a catalogue key, or elastic:<uuid> for a custom dataset

Example: own_workforce_remuneration

Query Parameters

framework · string

Narrow the dataset to a reporting taxonomy. It only affects datasets with framework-specific dimensions — notably emissions — and is a no-op elsewhere.

Response

key · string

Echo of the dataset key

label_key · string

i18n key for native datasets; the user’s literal name for custom ones

kind · string

kpi, activity, master, custom or custom_kpi

dimensions · array[object]

Show dimension

key · string

What to send in the query’s dimensions

label_key · string

i18n key for the dimension name

field_type · string

string, number, date, …

group · string

Which entity the dimension comes from, for grouping in a picker

i18n_namespace · string | null

When set, the dimension’s values are translation keys in this namespace — gender and accident_context are the workforce examples. Translate the values, not just the label.

relation_label · string | null

Set when the dimension is borrowed through a relation column

via · string | null

The relation column it was borrowed through. Advisory — the query accepts every listed dimension regardless.

metrics · array[object]

Show metric

key · string

What to send in the query’s metrics

label_key · string

i18n key for the metric name

agg · string

How the value is aggregated across rows.

Read it together with row_level. When row_level is false the metric’s expression is already an aggregate — a count, a ratio, a wage gap — and agg carries its default sum without being applied. That is why remuneration_avg and wage_gap both report "agg": "sum" in the example below: the field describes the engine’s aggregation step, not the metric’s meaning, and for these two there is no such step.

decimals · integer

Suggested precision for display

suffix · string | null

Unit to render after the value — h, %, t CO₂e

grouping_hint_key · string | null

Dimension the metric is most meaningful grouped by

row_level · boolean

false when the metric is already an aggregate — a count, a ratio, a gap. A row-mode formula over such a metric is rejected with 400.

default_metrics · array[string]

Metrics to preselect when nothing is chosen

window_required · boolean

true for native KPI and activity datasets: the query’s start/end window is mandatory and drives proration. false for master and custom datasets, where the window is optional or ignored.

time_axis_default · string | null

The dimension that seeds the period axis

data_version · integer | null

Custom datasets only: incremented on every write, so it works as a cache key. Null for native datasets.

Every dataset with a date column also exposes a synthetic period dimension that is not part of its stored fields. It is how you group by month, quarter or year.

Reading the workforce schemas

own_workforce_remuneration is the one worth knowing in detail. Its time axis is annual — one row per employee per fiscal year — and its wage_gap metric has three traps worth repeating from Query datasets:

• it is an FTE-weighted mean, not a simple average of salaries;
• the sign is positive when men earn more, since it is computed as (avg_M − avg_F) / avg_M × 100;
• it returns null, not 0, for any group that lacks at least one man and one woman. Null is “not computable here”, and it is not summable or averageable across groups — ask the server for subtotals instead of aggregating the numbers yourself.

It also carries fewer dimensions than own_workforce_contracts: organization, country, nationality, gender, job category, age and period, with no contract type, workday type, disability or labour-agreement split.

Example

cURL

curl -X GET "https://api.dcycle.io/v1/datasets/own_workforce_remuneration/schema" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

Successful Response

{
  "key": "own_workforce_remuneration",
  "label_key": "datasets.own_workforce_remuneration.label",
  "kind": "activity",
  "dimensions": [
    { "key": "organization", "label_key": "datasets.dim.organization", "field_type": "string", "group": "own_workforce_remuneration", "i18n_namespace": null },
    { "key": "gender", "label_key": "datasets.dim.gender", "field_type": "string", "group": "own_workforce_remuneration", "i18n_namespace": "customDashboard.pivotTable.values.gender" },
    { "key": "job_category", "label_key": "datasets.dim.job_category", "field_type": "string", "group": "own_workforce_remuneration", "i18n_namespace": null },
    { "key": "age", "label_key": "datasets.dim.age", "field_type": "number", "group": "own_workforce_remuneration", "i18n_namespace": null },
    { "key": "period", "label_key": "datasets.dim.period", "field_type": "date", "group": "own_workforce_remuneration", "i18n_namespace": null }
  ],
  "metrics": [
    { "key": "remuneration_avg", "label_key": "datasets.own_workforce_remuneration.metric.remuneration_avg", "agg": "sum", "decimals": 2, "suffix": null, "row_level": false },
    { "key": "wage_gap", "label_key": "datasets.own_workforce_remuneration.metric.wage_gap", "agg": "sum", "decimals": 2, "suffix": "%", "row_level": false }
  ],
  "default_metrics": ["remuneration_avg"],
  "window_required": true,
  "time_axis_default": "year",
  "data_version": null
}

Common Errors

401 Unauthorized

Cause: the key is invalid, or it does not belong to the organization in x-organization-id — the two are looked up as a pair. A request carrying no credentials at all answers AUTH_REQUIRED instead.

{
  "detail": "Invalid API key for organization",
  "code": "INVALID_API_KEY"
}

404 Not Found

Cause: unknown key, or a custom dataset belonging to another organization.

{
  "detail": "Unknown dataset 'own_workforce_salaries'."
}

Related Endpoints

List available datasets

Where the key comes from

Query datasets

Run the aggregation

Organization hierarchy capability

organization_hierarchy_supported indicates whether the dataset can return recalculated holding rows when organization is the first dimension and nest_organization_by_hierarchy is enabled. Consumers should show the hierarchy control only when this capability is true. The default is false for older servers and unsupported dataset definitions.