> 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/concepts-relationships-and-instances.md).

# Concepts, relationships, and instances

### Concepts

Concepts define the entities and values in your knowledge map.

```xml
<concept name="Person" type="string"/>
<concept name="Age" type="number"/>
<concept name="Birth Date" type="date"/>
<concept name="Is Active" type="truth"/>
```

RBlang supports exactly four data types:

* `string`
* `number`
* `date`
* `truth`

{% hint style="warning" %}
Only `string` concepts can be used as relationship subjects.
{% endhint %}

Use concept names for classes of data. Do not use specific values as concept names.

* Good: `Product Count`
* Bad: `Two`

#### Datasources on concepts

Datasources are optional child elements of a concept.

Use them when Rainbird needs to call an external API for that concept.

In practice, the concept acts as the request subject.

This is advanced functionality. Use the concept definition as the anchor point, then configure the request and mappings in [Datasources](/rainbird/knowledge-modelling/modelling-features/datasources.md).

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

Key points:

* A datasource is nested inside the concept definition.
* The concept should be a `string` concept that can act as a relationship subject.
* `{{%S}}` inserts the current datasource subject into the request.
* `<input>` fetches extra values needed to build the request.
* `<action>` maps API response values onto relationships that share the same subject.

### Relationships

Relationships connect two concepts.

```xml
<rel name="works in" subject="Person" object="Department" allowCF="false" allowUnknown="true" group="Person" canAdd="none"/>
```

Relationship attributes:

* `name` — required and unique across the whole knowledge map
* `subject` — required and must reference a `string` concept
* `object` — required and can reference any concept type
* `plural` — optional, defaults to `false`
* `askable` — optional, used when Rainbird can ask a user for the value
* `allowCF` — optional, defaults to `true`, lets a user provide a certainty factor when answering
* `allowUnknown` — optional, defaults to `false`, lets a user skip the question
* `canAdd` — optional, controls whether a user can add instances not already in the knowledge map. Supported values are `subject`, `object`, `all`, and `none`
* `group` — optional, groups questions from relationships that share the same subject. Use commas to assign more than one group. Ensure a group contains two or more relationships.

{% hint style="warning" %}
Never create two relationships with the same `name`.
{% endhint %}

Use `plural="true"` when a subject can have more than one object.

```xml
<rel name="purchased product" subject="Person" object="Product" plural="true"/>
```

#### Askable relationships

The `askable` attribute controls whether Rainbird can ask for facts on the relationship, and what form that question can take.

Supported values:

* `none` — do not ask questions for this relationship
* `secondFormObject` — ask for the object value only
* `secondFormSubject` — ask for the subject value only
* `all` — allow both subject and object questions, including first-form confirmation questions

#### Askable values explained

**`none`**

Use `none` when the relationship should never prompt a user.

This is useful when the fact must come from stored data, rules, imports, or an external datasource.

```xml
<rel name="has age" subject="Person" object="Age" askable="none"/>
```

**`secondFormObject`**

Use `secondFormObject` when you know the subject and want Rainbird to ask for the object.

This is the most common pattern.

```xml
<rel name="prefers category" subject="Person" object="Category" plural="true" askable="secondFormObject">
    <secondFormObject>What product categories does %S prefer?</secondFormObject>
</rel>
```

This asks about the missing object for a known subject.

**`secondFormSubject`**

Use `secondFormSubject` when you know the object and want Rainbird to ask for the subject.

```xml
<rel name="has licence type" subject="Driver" object="Licence Type" askable="secondFormSubject">
    <secondFormSubject>Who has the licence type %O?</secondFormSubject>
</rel>
```

This asks for the missing subject for a known object.

**`all`**

Use `all` when Rainbird can ask in any supported form.

This includes:

* second-form object questions
* second-form subject questions
* first-form confirmation questions that check whether a fact is true

```xml
<rel name="works in" subject="Person" object="Department" askable="all">
    <firstForm>Does %S work in the %O department?</firstForm>
    <secondFormObject>Which department does %S work in?</secondFormObject>
    <secondFormSubject>Who works in the %O department?</secondFormSubject>
  </rel>
```

{% hint style="info" %}
Use `none` when user questioning is not allowed. Use `secondFormObject` or `secondFormSubject` when only one direction makes sense. Use `all` only when both directions and direct fact confirmation are valid for the same relationship.
{% endhint %}

#### Question text

When setting question text use `%S` as the subject placeholder or `%O` as the object placeholder in relevant question text.

```xml
<rel name="works in" subject="Person" object="Department" askable="all">
    <firstForm>Does %S work in the %O department?</firstForm>
    <secondFormObject>Which department does %S work in?</secondFormObject>
    <secondFormSubject>Who works in the %O department?</secondFormSubject>
  </rel>
```

### Concept instances

Concept instances create named instances for `string` concepts.

```xml
<concinst name="John Smith" type="Person"/>
<concinst name="Laptop" type="Product"/>
```

Concept instances can also include metadata about the instance.

```xml
<concinst name="HR" type="Department">
    <meta type="md">Human Resources</meta>
</concinst>
```

{% hint style="warning" %}
Do not create concept instances for `number`, `date`, or `truth` concepts.
{% endhint %}

These are invalid:

```xml
<concinst name="25" type="Age"/>
<concinst name="true" type="Is Active"/>
```

### Relationship instances

Use relationship instances for facts.

```xml
<relinst type="has age" subject="John Smith" object="25"/>
<relinst type="has birth date" subject="John Smith" object="1999-03-15"/>
<relinst type="is active" subject="John Smith" object="true"/>
<relinst type="purchased product" subject="John Smith" object="Laptop"/>
```

Use primitive values directly for `number`, `date`, and `truth` objects.

### Validity checks

Before you save, confirm that:

1. Every concept exists before a relationship uses it.
2. Every relationship exists before a fact or rule uses it.
3. Every subject concept is `string`.
4. Every instance type is a `string` concept.
5. Every datasource action maps only to relationships that share the datasource subject.


---

# 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/concepts-relationships-and-instances.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.