> For the complete documentation index, see [llms.txt](https://docs.rainbird.ai/rainbird/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rainbird.ai/rainbird/knowledge-modelling/modelling-features/rblang-reference/datasources-reference.md).

# Datasources reference

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

For Studio setup and UI guidance, see [Datasources](/rainbird/knowledge-modelling/modelling-features/datasources.md).

### Placement

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

That concept should be a `string` concept.

```xml
<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>
```

{% hint style="warning" %}
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`.
{% endhint %}

### 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.

```xml
<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.

```xml
<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>`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.rainbird.ai/rainbird/knowledge-modelling/modelling-features/rblang-reference/datasources-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.