Concepts, relationships, and instances

Define valid data types, relationships, facts, and instances in RBlang.

Concepts

Concepts define the entities and values in your knowledge map.

<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

Only string concepts can be used as relationship subjects.

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.

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

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

Never create two relationships with the same name.

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

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

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

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

<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

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

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.

Question text

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

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

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

Concept instances can also include metadata about the instance.

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

Do not create concept instances for number, date, or truth concepts.

These are invalid:

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

Relationship instances

Use relationship instances for facts.

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