Collections

A collection defines a named set of records of a specific actor type and declares where that collection is expected to exist.

It binds:

• a data shape (actor)
• to a named collection (collection)
• with existence expectations (location)

A collection does not define structure. The actor does that.

Syntax

collection <CollectionName> {
  of { <ActorName> }

  expects {
    in { <LocationName> }
    in { <LocationName> }
  }
}

Structure

of { <ActorName> } (required)

Declares the actor type for items in the collection.

• Must reference an actor declared in the same scene
• Exactly one of block is required
• The referenced actor defines the shape and identity of each item

Example:

collection Tools {
  of { Tool }
}

expects { ... } (optional)

Declares where the collection must exist.

Inside expects, one or more in { <LocationName> } blocks may be declared.

• Each in must reference a declared location
• Duplicate locations are not allowed
• expects may be omitted if no existence requirements are needed

Example:

collection Tools {
  of { Tool }

  expects {
    in { DataFiles }
  }
}

Validation rules

The compiler enforces:

• collection names must be unique within a scene
• of must appear exactly once
• The referenced actor must exist
• All referenced locations must exist
• Unknown child blocks are errors
• Unknown blocks inside expects are errors

Invalid example:

collection Tools {
  of { UnknownActor }
}

Error:

Collection 'Tools' references unknown actor 'UnknownActor'

Relationship to actor

An actor defines:

• fields
• constraints
• identity

A collection defines:

• grouping
• existence expectations

Example:

actor Tool {
  shape {
    id   { integer }
    name { string }
  }

  identity { id }
}

collection Tools {
  of { Tool }
}

Relationship to location

A location names a target environment.

A collection declares that it must exist in one or more locations.

Example:

location DataFiles {
  kind { 'directory' }
}

collection Tools {
  of { Tool }

  expects {
    in { DataFiles }
  }
}

The scene declares intent. The edge configuration supplies the concrete wiring. The attestation verifies that the collection exists as declared.

Minimal example

The following example demonstrates how the…

• Tool — an actor, which defines the shape of a record
• Tools — a collection, which groups records of type Tool
• DataFiles — a location, where the collection is expected to exist

scene SimpleScene {
  location DataFiles {
    kind { 'directory' }
  }

  actor Tool {
    shape {
      id   { integer }
      name { string }
    }

    identity { id }
  }

  collection Tools {
    of { Tool }

    expects {
      in { DataFiles }
    }
  }
}