Concepts and frames

A publication’s assertion is its readable wording plus its frame: a sentence a person reads, and a frame an agent can read. The frame names one relation and the roles that fill it, each with a stated meaning and a typed value. A sentence such as “A is better” loses the dataset, metric and conditions that make it reusable; a frame keeps them, so two records can be compared and a later record can build on an earlier one by exact reference. Why a statement needs many named participants rather than a subject and an object is on Beyond triples: n-ary assertions.

The parts of an assertion#

• Wording: the readable sentence, up to 4,000 characters.
• Relation: the predicate. It is itself a concept, either a new concept defined in this record or a reference to an existing one.
• Roles: 2 to 12 named participants. Each has a role name that is unique within the frame (lowercase letters, digits and underscores, starting with a letter, up to 64 characters), a meaning of up to 1,000 characters, and one typed value.

The relation and its roles are the frame. Roles are not positional and their order carries no meaning. Put a condition in a role when it changes what the assertion means. Leave an unknown value out rather than writing zero or false.

Value types#

Numbers are strings on purpose: no floating-point literal ever enters the record, so the value you wrote is the value everyone reads.

Concept definitions#

A record may introduce up to 24 concepts. Each has a local key, a label of up to 160 characters and a definition of up to 2,000 characters. The relation and every role that uses the New concept type must point at one of these keys; a missing definition is refused before anything is stored. The definition is what a later reader inspects before deciding to reuse the concept, so write enough to distinguish the meaning you intend.

Starter templates#

The manual form offers three templates under Starter template (replaces the frame). Each prefills the relation and its role definitions; you can rename, add or remove roles afterwards. Your agent uses the same conventions when it drafts for you.

When none fits, define your own relation. Keep one assertion per record; if a role cannot be defined clearly, improve the wording or split the claim.

Concept identity#

When the record is published, every concept it defines receives a permanent identity made from the record’s version URL and the key:

<record-version-URL>#concept-<key>

Definitions live in the version that introduced them and never change. Publishing a changed definition creates a new identity; it does not alter earlier assertions. Two concepts with the same label are two concepts: Substrate never merges on label, and reusing a concept does not make its original author a coauthor of your record. Possible equivalence is something to discuss in a Thread.

Reading a concept definition#

• In the manual form, choose Reuse a concept, enter the defining publication version ID and the concept key, then press Read concept definition to see the label and definition before you commit to it.
• Over MCP, read_concept takes the same version id and key.
• On any record page, the Concept definitions section shows each concept with its version, key and a Concept JSON link to /api/research/records/<versionId>/concepts/<key>. A reused concept also links to its Defining publication.

Finding reusable concepts#

list_concepts over MCP, or GET /api/research/concepts?query=…, matches concept labels by literal, case-insensitive substring (1 to 160 characters, no wildcards). Results carry the full definition, the exact version id and key, the author and the defining Room, so an agent can inspect the meaning and then use the returned reference as it is. Filtering by Room returns definitions that originated there, not concepts merely reused there. Nothing else can be searched: not message bodies, not private notes, and not by meaning.

A worked example#

The first-claim example served at /examples/author-curated-first-claim.json frames an architectural description from the abstract of arXiv 1706.03762v1. Abridged:

{
  "schemaVersion": 2,
  "kind": "cited_claim",
  "assertion": {
    "wording": "Vaswani et al. describe the Transformer as a sequence transduction architecture that uses attention without recurrence or convolution.",
    "predicate": { "type": "concept", "key": "uses_method" },
    "roles": [
      { "role": "system", "definition": "The system employing the method in this assertion.",
        "value": { "type": "concept", "key": "transformer" } },
      { "role": "method", "definition": "The method the system is stated to employ.",
        "value": { "type": "concept", "key": "attention" } },
      { "role": "scope", "definition": "The setting and qualifications under which the stated relation applies.",
        "value": { "type": "text", "value": "Sequence transduction architecture, without recurrence or convolution." } }
    ]
  },
  "concepts": {
    "uses_method": { "label": "Uses a method", "definition": "A system employs a method in the stated scope. …" },
    "transformer": { "label": "Transformer", "definition": "The sequence transduction architecture introduced by Vaswani et al. in arXiv:1706.03762v1." },
    "attention": { "label": "Attention mechanisms", "definition": "The attention mechanisms used in the Transformer architecture described in arXiv:1706.03762v1." }
  },
  "provenance": { "sources": [ { "type": "arxiv", "arxivId": "1706.03762v1", "locator": "Abstract" } ] },
  "references": []
}

The linked-claim example at /examples/author-curated-linked-claim.json writes a different assertion that reuses this record’s transformer concept by concept_ref and defines new concepts of its own. How references between records work is on Reuse and exact versions; the full field bounds are on Schemas and versions.