6.2 Datapoints
Datapoints are the fundamental execution units in OLIVE. They define what external interaction should happen and how it should be executed, without prescribing when or in which sequence this execution takes place.
This separation allows datapoints to be reused across connectors and workflows.
Conceptually, a datapoint represents a single, well-defined operation, such as:
- Calling a REST endpoint
- Executing a cloud function
- Triggering an AI prompt
- Performing a semantic search
Datapoints are passive definitions. They become active only when they are invoked by the OLIVE Data-Orchestrator, either directly or as part of a connector execution.
See also the definition in the data metamodel: DataPoint
Syntax and Structure
Every datapoint is defined as a JSON configuration with a stable outer structure and a specialized inner definition.
A datapoint definition consists of two conceptual layers:
- Metadata layer
Used for identification, versioning, and discoverability. - Execution layer
Defines the technical behavior of the datapoint.
A minimal structure looks as follows:
{
"id": "example-datapoint",
"type": "datapoint",
"version": "0.0.1",
"datapoint": {
"type": "http"
}
}
The outer attributes (id, name, tags, version) are managed by the OLIVE repository and tooling.
The inner datapoint object defines the executable logic and is specialized by its type.
Field reference
Outer attributes — the same on every connectable element:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Unique identifier. Registering an element with an existing id overwrites it |
type | string | yes | "datapoint" |
version | string | yes | Informational only; does not affect identity |
name | string | — | Technical name, shown in the connectivity editor |
displayName | string | — | Name shown in user-facing, non-technical contexts |
description | string | — | What the element does |
tags | string[] | — | For search and grouping, and for selecting an export set |
deprecated | boolean | — | Default false |
owner | string | — | Person responsible for the element |
input | object | — | Input DataHandler — schema and input transformer |
output | object | — | Output DataHandler — schema and output transformer |
templateID, originalID, mmVersion | string | — | Set by the platform during template instantiation. Do not set these by hand |
datapoint — the execution layer, common to every datapoint type:
| Field | Type | Required | Description |
|---|---|---|---|
type | string | yes | The technical type: http, transform, cloudfunction, manualtask, mock, or an extension type such as prompt, agent, mcpserver |
<type> | object | — | The type-specific configuration, under a key matching type — http for an HTTP datapoint, transform for a transform datapoint, and so on |
parameters | object | string | number | boolean | — | Default values passed to the datapoint. Merged with the incoming input, which wins on a key collision |
auth | string | object | — | An auth entry id, a placeholder resolving to one, or an inline auth object |
async | boolean | — | Whether the datapoint resolves later rather than returning immediately. Default false; manualtask is asynchronous by default. See Long Running & Asynchronous Datapoints |
auth sits on datapoint, not inside the type-specific blockIt is resolved as datapoint.auth. Placing it inside datapoint.http, or at the root of the element
beside id and type, leaves the request unauthenticated — the property is simply not read there, and
nothing reports an error. Only datapoints can carry auth; connectors and workflows cannot.
input and output — both are a DataHandler:
| Field | Type | Description |
|---|---|---|
schema | string | object | Either the id of a schema element in the repository, or a schema configuration: { "type": "json" | "xml", "schema": { … } }. A url may be given instead of inline content. Not enforced at runtime |
transformer | object | { "type": "jsonata", "transform": "${ … }" }. type defaults to jsonata, which is the only supported engine. See Transforming Connectivity Input & Output Data |
HTTP Datapoints
HTTP is a concrete specialization of the abstract Datapoint concept.
An HTTP datapoint represents exactly one HTTP request.
It defines all information required to execute this request, including:
- Target URL
- HTTP method
- Optional headers and parameters
- Optional authentication reference
Because HTTP datapoints specialize Datapoint, they can:
- Be executed directly via the OLIVE Data-Orchestrator
- Be orchestrated inside connectors
Example: HTTP Datapoint
The following example shows an HTTP datapoint.
{
"id": "base-dp-call-http-post-params",
"type": "datapoint",
"version": "0.0.1",
"name": "base-dp-call-http-post-params",
"displayName": "base-dp-call-http-post-params",
"tags": [
"simple-example",
"example",
"scenario-example-base",
"scenario-example-base-datapoints"
],
"description": "Example HTTP datapoint that executes a POST request to a URL provided via input. It declares datapoint parameters and forwards the provided input values into the request payload for the target endpoint.",
"deprecated": false,
"datapoint": {
"type": "http",
"http": {
"url": "${input.urlPost}",
"method": "POST",
"headers": {
"Content-Type": "application/json"
}
},
"parameters": "${input.params}"
}
}
Example: HTTP Datapoint with Authentication
The following example shows an HTTP datapoint that performs a GET request against a protected endpoint.
{
"id": "base-dp-call-http-get-auth",
"type": "datapoint",
"version": "0.0.1",
"name": "base-dp-call-http-get-auth",
"displayName": "base-dp-call-http-get-auth",
"tags": [
"simple-example",
"example",
"scenario-example-base",
"scenario-example-base-datapoints"
],
"description": "Simple example datapoint that performs an HTTP GET request to a user-supplied URL. Intended for demonstrating basic connectivity and validating HTTP request execution.",
"datapoint": {
"type": "http",
"http": {
"url": "${input.urlGet}",
"method": "GET"
},
"auth": "${input.authID}"
}
}
Explanation:
datapoint.type
Declares this datapoint as an HTTP datapoint.datapoint.httpblock
Defines the concrete HTTP request that will be executed.datapoint.auth
References an authentication object that is resolved at execution time.datapoint.parameters
Endpoints expect input data, so the required payload must be defined using datapoint parameters. Without declared parameters, no input is passed.
The mechanics of dynamic value resolution ${input} and placeholder syntax are described in detail in the Placeholder Resolution documentation and are not covered in this chapter: Placeholder Resolutions - Connectable Elements
Http request body
If a http datapoint should be sent with a body, there are multiple options:
- Define a body directly in the http datapoint
- Define
parameterson the datapoint — they are used as the body if no other body is set - Call the datapoint with input parameters
- If no other body is set they are used as body instead
- If no other body is set but parameters are defined, then the input parameters are merged with the datapoint parameters
Example with body:
{
"id": "base-dp-call-http-post-body",
"type": "datapoint",
"version": "0.0.1",
"name": "base-dp-call-http-post-body",
"displayName": "base-dp-call-http-post-body",
"tags": [
"simple-example",
"example",
"scenario-example-base",
"scenario-example-base-datapoints"
],
"description": "Generic example datapoint that performs an HTTP POST request to a user-specified URL with a JSON request body.",
"deprecated": false,
"datapoint": {
"type": "http",
"http": {
"url": "${input.urlPost}",
"method": "POST",
"headers": {
"Content-Type": "application/json"
},
"body": "${input.body}"
}
}
}
The http block
| Field | Type | Description |
|---|---|---|
url | string | Target URL. Placeholders are allowed, subject to the per-position character rules in Security in Connectivity Engineering |
method | string | GET, POST, PUT, PATCH, DELETE, … |
headers | object | Request headers. Header names cannot be produced by a placeholder |
query | object | Query parameters |
body | object | string | Request body. When set, it is used as-is and is not merged with the incoming parameters |
redirect | string | What to do with a redirect response. Passed to the HTTP client, so the values are follow (the default), error and manual |
allowErrorStatus | boolean | Default false. By default a response with status 400 or above makes the datapoint fail; set this to true when an error status is a valid result you want to inspect |
There is no auth inside this block — see the note under Field reference above.
Transform Datapoints
Transform is a concrete specialization of the abstract Datapoint concept.
A Transform datapoint defines a lightweight, declarative transformation step that is executed inside the OLIVE runtime. It is used to modify, reshape, or derive data from the incoming input without invoking an external system.
Transform datapoints are typically used to:
- Post-process the output of another datapoint
- Prepare or normalize input data before passing it to the next datapoint in a connector
- Restructure payloads using a declarative expression language
Because Transform datapoints specialize Datapoint, they can:
- Be executed directly via the OLIVE Data-Orchestrator
- Be orchestrated inside connectors and workflows
Example: Transform Datapoint
The following example shows a Transform datapoint that maps two input parameters into a new object structure.
{
"id": "base-dp-transformer-jsonata",
"type": "datapoint",
"version": "0.0.1",
"name": "base-dp-transformer-jsonata",
"displayName": "base-dp-transformer-jsonata",
"tags": [
"simple-example",
"example",
"scenario-example-base",
"scenario-example-base-datapoints"
],
"description": "Example Transform datapoint that uses a JSONata expression to map multiple input parameters into a new structured output object. Demonstrates how input values can be reshaped and prepared for consumption by subsequent datapoints in a workflow or connector.",
"datapoint": {
"type": "transform",
"transform": "${ {\"firstParam\": input.param, \"secondParam\": input.param2} }"
}
}
Explanation:
datapoint.type
Declares this datapoint as a Transform datapoint.datapoint.transform
Defines the transformation expression. The expression is evaluated using Jsonata and applied to the input payload.input.param,input.param2
Refer to values provided at execution time, either directly via the Data-Orchestrator or as output from a previous datapoint in a connector.
The result of the transformation is returned as the datapoint output and can be consumed by subsequent datapoints. The mechanics of dynamic value resolution ${input} and placeholder syntax are described in detail in the Placeholder Resolution documentation and are not covered in this chapter: Placeholder Resolutions - Connectable Elements
For details on the Jsonata expression syntax, see: Using JSONata
Authentication and Datapoints
Datapoints do not store credentials directly.
Instead, authentication is modeled as a separate concept and referenced from the datapoint. For more information on authentication and secret management: Authentication and Secrets Management
This design provides:
- Separation of concerns
- Centralized credential management
- Reusability across multiple datapoints
- Improved security by avoiding embedded secrets
An HTTP datapoint may reference an Auth object, but the datapoint itself remains independent of the concrete authentication details.
In an unauthenticated development deployment, OLIVE's public APIs (file-storage-service, session-memory, data-orchestrator, repository) accept a request without credentials, so a bare HTTP datapoint works. In an authenticated deployment the same datapoint is rejected with 401.
If your datapoint calls an OLIVE service, add an auth reference of type oidc before the solution goes into productive use: Calling OLIVE's own APIs from connectivity.
Registering Datapoints in OLIVE
Datapoints must be created and registered in the OLIVE connectivity editor before they can be used.
Registration makes the datapoint:
- Addressable by its
id - Discoverable in the OLIVE Connectivity Editor
- Available for execution via the Data-Orchestrator
- Reusable in connectors
Registration is declarative. No execution happens at this stage.
Executing Datapoints
Datapoints are executed only when they are explicitly invoked.
Typical execution paths include:
- Direct execution via the OLIVE Data-Orchestrator: Service APIs – Version 1
- Execution as part of a connector
- Invocation by a tool like Bruno
Example execution request, using an API tool like Bruno:
{
"id": "base_dp_call-http-get-auth",
"input": {
"authID": "base_a_bearer-api-key"
}
}
At runtime, OLIVE:
- Resolves all required references
- Applies authentication
- Executes the HTTP request
- Returns the result to the caller
Key Takeaways
- Datapoints are reusable, passive definitions of executable operations
- HTTP datapoints represent a single, concrete HTTP request
- Authentication is referenced, not embedded
- Datapoints must be registered before use
- Execution happens only when datapoints are explicitly invoked
- Dynamic value resolution is handled separately and documented elsewhere
This approach keeps OLIVE connectivity definitions modular, secure, and easy to maintain across different scenarios and environments.
Restriction: JSON return values
In the current version of OLIVE it is not possible to have a datapoint return a JSON object with the property name "result" on root level.
Not working:
{
"result": "my-result-text"
}
Working:
{
"someproperty": {
"moreproperties": {
"result": "my-result-text"
}
}
}
Related
- Security in Connectivity Engineering — which destinations a datapoint may call, and the rules placeholders must follow in 1.3