Validation checklist and examples

Validate RBlang output and use known-good patterns when writing knowledge maps.

Best practices

Always define elements in this order:

1. Concepts

2. Relationships

3. Concept instances for string concepts

4. Relationship instances and rules

Keep naming consistent:

• Concepts in title case, such as Person or Product Category

• Relationships in lowercase, such as has age or purchased product

• Natural English names throughout

Keep the graph connected. Every concept should appear in at least one relationship.

Validation checklist

Use this checklist before you save or share generated RBlang.

1. All concepts are defined before use.

2. Only string, number, date, and truth are used.

3. All relationship names are unique.

4. Concept and relationship names read naturally.

5. No concept instances exist for number, date, or truth concepts.

6. Concepts use the right level of abstraction.

7. Every referenced concept exists.

8. Every referenced concept instance exists.

9. Relationships are defined before facts and rules use them.

10. Relationship subjects always reference string concepts.

11. Primitive object values are used directly where needed.

12. Rule variables stay consistent throughout the rule.

13. Object values match the relationship object type.

14. String literals in expressions use single quotes.

15. Assignment uses the value attribute.

16. Missing facts are tested with countRelationshipInstances().

17. Rules work for the general case.

18. Expressions use supported syntax only.

19. Each required query has a matching relationship.

20. Every concept is connected to the graph.

Example: age-based eligibility

<?xml version="1.0" encoding="utf-8"?>
<rbl:kb xmlns:rbl="http://rbl.io/schema/RBLang">
    <concept name="Person" type="string"/>
    <concept name="Age" type="number"/>
    <concept name="Is Eligible" type="truth"/>

    <rel name="has age" subject="Person" object="Age"/>
    <rel name="is eligible" subject="Person" object="Is Eligible"/>

    <concinst name="John" type="Person"/>
    <relinst type="has age" subject="John" object="25"/>

    <relinst type="is eligible" object="true" cf="100" name="Eligible if 18+">
        <condition rel="has age" subject="%S" object="%AGE"/>
        <condition expression="%AGE is greater than or equal to 18"/>
    </relinst>
</rbl:kb>

Example: list aggregation with a missing fact check

<concept name="Student" type="string"/>
<concept name="Score" type="number"/>
<concept name="Average" type="number"/>
<concept name="Has Data" type="truth"/>

<rel name="has score" subject="Student" object="Score" plural="true"/>
<rel name="has average" subject="Student" object="Average"/>
<rel name="has complete data" subject="Student" object="Has Data"/>

<relinst type="has average" cf="100" name="Calculate average">
    <condition expression="countRelationshipInstances(%S, 'has score', *)" value="%COUNT"/>
    <condition expression="%COUNT is greater than 0"/>
    <condition expression="sumObjects(%S, 'has score', *)" value="%SUM"/>
    <condition expression="%SUM / %COUNT" value="%O"/>
</relinst>

<relinst type="has complete data" object="false" cf="100" name="No scores recorded">
    <condition expression="countRelationshipInstances(%S, 'has score', *) is equal to 0"/>
</relinst>

Authoring pattern for LLMs

When generating RBlang, prefer this flow:

1. Declare all concepts.

2. Declare all relationships.

3. Add string concept instances only.

4. Add facts.

5. Add rules last.

This reduces cross-reference errors and makes validation simpler.