Skip to main content

JSON formats

Every entity you read from or send to the REST API is a JSON document. These pages describe the format of each one: the fields, their types, which fields are required when you save, which are set by the platform, and an example.

This page covers the conventions that all the entities share. The other pages cover the entities, grouped by area:

PageEntities
Master data and typesObject, Type, references, links, currency pairs
TimeseriesTimeSeries, smart, event, metric and composed timeseries
CurvesCurve, contracts, smart, event and composed curves, curve dates, curve series, curve management
EventsEvent, event list
Matrices and optionsMatrix, option chains, event options
CalendarsCalendar, holiday calendar, expiry calendar
Processes and scriptsProcess, process execution, script, action, workflow, transformer, extractor, batch, task, queue, and their logs
AutomationsAutomation, automation target, automation log
Reports and dashboardsReport configuration, report, report creator, dashboard
Datasets and data qualityDataset, dataset feed, dataset delivery, correction, validation configuration, validation record, alert
Fusion AIAgent, assistant, playbook, task, run, tool, conversation, usage, feedback
Platform and securityPolicy, group, list, secret, setting, documentation, extension, index, environment, tenant, user, and the read-only logs

The id and the type​

Most entities have an _id and a _type.

FieldWhat it is
_idThe id of the entity. For most services you choose it. Some services make it for you: an object id (24 hexadecimal characters) for automations, lists, groups and tasks, a UUID for process executions and batches
_typeThe kind of entity, for example VarTimeSeries, VarCurve, VarProcess or VarScript. For master data objects it is the type of the object, for example #Object or #ForeignExchange

The platform uses _type to read the JSON, so send it whenever the entity has one. A curve sent without "_type": "VarCurve" inside an object is saved as plain properties, not as a curve.

Ids that start with # are public (shared by OpenDataDSL). All other ids are private to your company. See Sources.


Fields that start with an underscore​

Fields whose names start with _ are kept for the platform. You can read them, but most of them are set for you when you save.

FieldTypeSet byWhat it is
_idStringYou or the platformThe id
_typeStringYouThe kind of entity
_oidStringPlatformOn versioned entities: the id of the item. On the live version it is the same as _id; an older version has its own _id and keeps the item id in _oid
_versionIntegerPlatformThe version number, starting at 1
_userStringPlatformWho saved this version (an email, or system)
_timestampDateTimePlatformWhen this version was saved
_tagString[]PlatformThe tags on this version, see Versions and tags
_invocationIdStringPlatformThe id of the request that saved this version
_created, _updatedDateTimePlatformWhen some unversioned entities were created and last changed
_linksObjectYouLinks to other entities, see Links
_accessStringYouA data role used by security policies on master data
_objid, _dataid, _objtypeStringPlatformOn data (timeseries, curves, events): the object id, the data id within the object and the object type
_identityObjectYouOn data: the codes other systems use for the item, see Identities

When you save an entity, leave the version fields out, or send them back as you read them: the platform replaces them.


Identities​

Data items (timeseries, curves, matrices, options) can carry identities: the codes that other systems, such as your ETRM or a risk system, use for them. They are kept in _identity, an object with one code per identity provider. The provider names are your own choice.

"_identity": {
"ETRM": "GAS_TTF_DA",
"RISK": "TTF-DA-IDX"
}

An item with no identities has an empty _identity object.

A curve's identities belong to the curve, not to each curve date: they are kept on the curve's list of dates (NGE.POWER.DE:BASE), and added to the curve for each date when you read it. A matrix works the same way.

Setting identities​

Set and remove identities with the identity function of the Data service: a PUT to data/v1/private?_function=identity with action set to PUT. A provider set to null is removed.

{
"action": "PUT",
"data": [
{"_id": "NGE.GAS.TTF:SPOT", "ETRM": "GAS_TTF_DA", "RISK": "TTF-DA-IDX"},
{"_id": "NGE.POWER.DE:BASE", "ETRM": "PWR_DE_BASE"}
]
}

Reading identities​

To read the identities of several items at once, send action GET with the ids, and optionally the providers you want (all of them if you leave identity out):

{
"action": "GET",
"_id": ["NGE.GAS.TTF:SPOT", "NGE.POWER.DE:BASE"],
"identity": ["ETRM"]
}

The response is the request with a data list added: one entry per id, holding the codes of the providers asked for and the kind of data. A curve is listed as its list of dates (VarCurveDates), with the kind of curve in _subtype:

{
"action": "GET",
"_id": ["NGE.GAS.TTF:SPOT", "NGE.POWER.DE:BASE"],
"identity": ["ETRM"],
"data": [
{"_id": "NGE.GAS.TTF:SPOT", "ETRM": "GAS_TTF_DA", "_type": "VarTimeSeries"},
{"_id": "NGE.POWER.DE:BASE", "ETRM": "PWR_DE_BASE", "_type": "VarCurveDates", "_subtype": "VarCurve"}
]
}

Smart and event curves are listed as VarCurveDates and smart and event timeseries as VarTimeSeries, each with the kind in _subtype.

Reading data by its identity​

You can also read a data item by another system's code: put identity. and the provider name after private in the source. This reads the timeseries whose ETRM code is GAS_TTF_DA:

GET https://api.opendatadsl.com/api/data/v1/private.identity.ETRM/GAS_TTF_DA

Dates and times​

KindFormatExample
A dateyyyy-MM-dd"2026-11-18"
A date and timeISO 8601, in UTC"2026-11-18T17:30:00" or "2026-11-18T17:30:00Z"
A curve dateAn object with the date and its expiry calendar{"curveDate": "2026-11-18", "expiryCalendar": "#REOMHENG"}
A durationISO 8601 duration, see Durations"PT1H", "P14D"
A scheduleThe platform cron format, see Cron"30 18 * * 1-5 * Europe/London"

Responses write dates as strings. Some stored records are returned in MongoDB extended JSON, for example {"$date": "2026-11-18T17:30:00Z"} for a date or {"$oid": "6721f0c2a4b9e85d3c0f1a77"} for an object id. The platform accepts both forms when you send them back.


Numbers and missing values​

Numbers are JSON numbers. A missing value is sent and returned as the string "NaN" (a timeseries value, a curve contract value, a matrix cell). In some responses a missing number is null.

Data entities keep the number of decimal places given by their precision:

FieldTypeWhat it is
scaleIntegerThe number of decimal places, defaults to 6
roundingModeStringUP, DOWN, CEILING, FLOOR, HALF_UP (the default), HALF_DOWN, HALF_EVEN or UNNECESSARY
useDefaultBooleanUse the platform's default settings, defaults to true
storeBooleanStore the rounded number instead of the raw number, defaults to false
"precision": {"roundingMode": "HALF_UP", "scale": 4, "useDefault": false, "store": false}

Status​

Timeseries values, curves and contracts and events carry a status: what is known about the quality of the value. Each part is a word, optionally followed by a colon and a note.

PartValuesDefault
qualityUNCHECKED, VALID, FAILED, NICUNCHECKED
sourceNEW, CHANGED, IMPLIED, FILLED, CONVERTED, CALCULATED, SUBSTITUTEDNEW
reliabilityUNKNOWN, QUOTED, OBSERVED, UNOBSERVEDUNKNOWN
processedUNPROCESSED, STAGE1, STAGE2, WAITING, FAILED, BUILT, COMPLETEUNPROCESSED

Parts that have their default value are left out, so an unchecked value has an empty status {}.

"status": {"quality": "VALID:Tested for missing and spikes", "source": "CALCULATED"}

See Status for what each value means.


Encoded scripts​

The source code of scripts, actions, workflows, transformers and extractors is sent and returned in the script field encoded as Base64 (UTF-8). Expression and method properties of a type are encoded the same way. Decode the field to read the code, and encode it before you save.


Saving: merge or replace​

Saving an object merges what you send into the saved object, so you can send just the fields you want to change. Add the _replace=true query parameter to replace it completely. For other services, check the service page: most replace the entity with what you send.


Where next​