docs/src/concepts/entities.md

Entities

Entities are the fundamental business objects in your workspace, like people, organizations, or projects. Each entity has a unique ID, a type, and a collection of fields.

Defining entities

In the DSL, you define an entity with its type and ID, followed by its fields in a block:

person john_doe {
    name = "John Doe"
    email = "john@doe.com"
}

In Rust, this corresponds to an Entity struct:

let person = Entity::new(EntityId::new("john_doe"), EntityType::new("person"))
    .with_field(FieldId::new("name"), "John Doe")
    .with_field(FieldId::new("email"), "john@doe.com");

Entity structure

Every entity has:

• Type: What kind of entity this is (e.g., person, organization, task)
• ID: A unique identifier within its type (e.g., john_doe)
• Fields: Key-value pairs containing the entity's data

Composite entity identifier

When Firm works with entities, it assigns each one a composite identifier of its type and ID. This means you can have several entities with the same ID, as long as they have different types.

For example, you could have:

• person.hello - A person named Hello
• organization.hello - An organization called Hello

When referencing entities, Firm uses the format type.id:

• person.john_doe
• organization.megacorp
• task.design_homepage