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

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

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

- [finding-things](finding-things.md): querying by aspect, slot and form
- [the-building-blocks](the-building-blocks.md)
- [the-three-doors](the-three-doors.md): why these skills need the modeller door
- [a-memory-you-can-shape](a-memory-you-can-shape.md)