Forms, aspects and concepts

All three are defined through the modeller door. The calls below were run against a fresh house; the answers are quoted in the parts that matter.

A form: a typed, immutable value

define_form takes YAML and an optional title:

Description: A claim a source makes, with how firmly the source puts it.
Properties:
  - Code: Statement
    Type: Storable
    Description: The claim in one sentence.
  - Code: Strength
    Type: Enum
    Values: [Asserted, Suggested, Denied]
    Description: How firmly the source states it.

Property types are Storable, Enum, Chain, Integer and Precise. The answer returns the form with its id and is_new: true. Calling it again with the same YAML returns the same id and is_new: false: the form's identity is its schema. Give it a title; without one it is addressable only by its description.

store_value with the form id and {"Statement": "The bridge was finished in 1887.", "Strength": "Asserted"} stores an instance. Inline text for a Storable property is stored as a text value first. Storing the same values again is the same node.

A link form: a typed fact with values

A form used with assert_formed_link types an edge. A form titled "Stated in" with one Integer property Page lets you state that the claim stands in a source, on page 41. The answer names both ends and is_new. In describe of either end the edge appears in a group named after the form, with its values. Such an edge records where a statement stands; it does not make the statement evidenced (evidence-and-provenance).

An aspect: a kind of individual with state

define_aspect takes YAML with a name, a description and a list of properties:

Name: Source
Description: A source this house draws on. An instance stands for the source as a whole.
Properties:
  - Name: Reliability
    Kind: Value
    Description: How far this source has proven trustworthy so far.
  - Name: Summary
    Kind: Versioned
    Description: What the source is, in two sentences.

Kind is Value (single, switching), Versioned (single, with history) or Set. The description is where reading rules belong, as prose: later agents find them there.

create_individual with the aspect id and a name creates an instance. Its answer tells you how to write the surface: set_property with the individual, a path, a value and context_id set to the aspect id, plus versioned: true for Versioned slots. Note that the path is an array, ["Summary"], not a string. After two writes to Summary, get_history returns both wordings, newest first.

A concept: a term

include_concept coins a term from its description text. The description is the concept: the same text is the same concept, and a changed text is a new one. Concepts can depend on other concepts. list_concepts shows the vocabulary.

Before you define anything

Check list_forms, list_concepts and overview first, and form_usage to see whether an existing form is actually used. The house prefers one well-described form over three similar ones, and it tells you when you redefine what exists.

Go deeper