Datasources reference

Define datasource elements, inputs, request bodies, headers, and response mappings in RBlang.

Use datasources when a concept needs facts from an external API.

For Studio setup and UI guidance, see Datasources.

Placement

Define a datasource as a child of the concept that acts as the request subject.

That concept should be a string concept.

<concept name="Vehicle" type="string">
    <datasource
        hostname="https://uk1.ukvehicledata.co.uk"
        path="/api/datapackage/VehicleAndMotHistory?v=2&api_nullitems=1&auth_apikey=[YOUR_API_KEY]&key_VRM={{%S}}"
        method="GET"
        name="Uk Vehicle Data">
        <action map="has make=/Response/DataItems/ClassificationDetails/Dvla/Make"/>
        <action map="has model=/Response/DataItems/ClassificationDetails/Dvla/Model"/>
        <action map="has final result=/Response/DataItems/ClassificationDetails/Dvla/{{%CHOICE}}"/>
        <input rel="owns" subject="%PERSON" object="%S"/>
        <input rel="has choice" subject="%PERSON" object="%CHOICE"/>
        <headers>
            <header key="Key" value="Value"/>
        </headers>
        <![CDATA[CDATA_HERE]]>
    </datasource>
</concept>

Attach the datasource to the concept that represents the request subject, not the concept you want to populate.

For example, to fetch a credit score for a person, attach the datasource to Person and map the response onto has credit score.

Datasource element

The <datasource> element defines the request.

Supported attributes include:

• name — optional label for the datasource

• hostname — base URL for the API

• path — endpoint path and query string

• method — HTTP method, supports GET or POST

Variables in requests

Use {{...}} to inject runtime values into the path, headers, or request body.

{{%S}} resolves to the datasource subject.

Use named inputs when the request needs more values than the subject alone provides.

Input elements

Use <input> when the request needs additional values from the knowledge map.

Each input binds a value that the datasource can reuse in the request.

Those values can then be referenced as variables such as {{%CHOICE}}.

In the example:

• <input rel="owns" subject="%PERSON" object="%S"/> resolves the person who owns the vehicle

• <input rel="has choice" subject="%PERSON" object="%CHOICE"/> resolves an extra value named %CHOICE

Action mappings

Use <action> to map values from the API response into facts.

The map attribute uses this form:

relationship name=/response/path

The response path uses XPath syntax.

<action map="has make=/Response/DataItems/ClassificationDetails/Dvla/Make"/>

In the example:

• has make maps the vehicle make

• has model maps the vehicle model

• has final result maps a dynamic field selected with {{%CHOICE}}

Each action should map to a relationship that shares the datasource subject.

Headers

Use <headers> when the request needs API keys, content type, or other request metadata.

Header values can also use variables.

<headers>
    <header key="Key" value="Value"/>
</headers>

CDATA request bodies

Use CDATA when the request needs a raw body.

This is most useful for POST requests or APIs that expect XML payloads.

The body can also include datasource variables.

Validation checks

Before you save, confirm that:

1. The datasource is attached to a string concept that acts as the request subject.

2. Every datasource action maps only to relationships that share the datasource subject.

3. Every variable used in the request resolves from %S or a defined <input>.