Entity Definitions

Thalo allows you to define custom entity types that match how you think and organize knowledge. This guide covers how to define and use entities.

What Are Entities?

Entities are structured types for different kinds of knowledge. Common examples include:

Opinions - Your stances on topics
Journals - Personal thoughts and reflections
References - External resources (books, articles, videos)
Lore - Facts and insights about subjects

But you can define any entity type that fits your needs!

Defining an Entity

Entity definitions use the define-entity directive:

{timestamp} define-entity {name} "Description" [^link-id] [#tags...]
  # Metadata
  {field-name}: {type} ; "Optional description"
  {optional-field}?: {type} ; "Optional field"

  # Sections
  {SectionName} ; "Required section"
  {OptionalSection}? ; "Optional section"

Example: Opinion Entity

2026-01-07T11:40Z define-entity opinion "Formed stances on topics"
  # Metadata
  confidence: "high" | "medium" | "low"
  supersedes?: link ; "Reference to previous stance"
  related?: link[] ; "Related entries"

  # Sections
  Claim ; "Core opinion in 1-2 sentences"
  Reasoning ; "Bullet points supporting the claim"
  Caveats? ; "Edge cases, limitations, exceptions"

Example: Reference Entity

2026-01-07T11:40Z define-entity reference "External resources or local files"
  # Metadata
  url?: string ; "Full URL to external resource"
  file?: string ; "Path to local file"
  ref-type: "article" | "video" | "tweet" | "paper" | "book" | "other"
  author?: string | link ; "Creator/author name"
  published?: datetime ; "Publication date"
  status?: "unread" | "read" | "processed" = "unread"

  # Sections
  Summary? ; "Brief summary of the content"
  Key Takeaways? ; "Bullet points of main insights"
  Related? ; "Links to related entries"

Metadata Types

Metadata fields support several types:

string - Text values
link - Reference to another entry (^entry-id)
link[] - Array of links
datetime - ISO 8601 date/time
date - Date only
date-range - Date range (2020 ~ 2021)
Union types - "option1" | "option2" | "option3"
Optional - Add ? after field name

Type Examples

# String
author: string

# Optional string
author?: string

# Enum (union of string literals)
confidence: "high" | "medium" | "low"

# Link
subject: link

# Array of links
related: link[]

# Date
published: datetime

# Date range
date: date-range

# Union of types
author: string | link

Sections

Sections define the content structure of entries:

Required sections - Must be present: SectionName ; "Description"
Optional sections - May be omitted: SectionName? ; "Description"

Example

2026-01-07T11:40Z define-entity journal "Personal thoughts and reflections"
  # Metadata
  subject: string | link
  type: string
  mood?: string

  # Sections
  Entry ; "The journal entry content (required)"
  Reflection? ; "Additional reflection (optional)"

Using Entities

Once defined, create entries using the entity type:

2026-01-08T14:30Z create opinion "TypeScript enums should be avoided" ^ts-enums #typescript
  confidence: "high"
  related: ^clean-code

  # Claim
  TypeScript enums should be replaced with `as const` objects.

  # Reasoning
  - Enums generate runtime code
  - `as const` provides the same type safety with zero overhead

  # Caveats
  - Const enums can be useful for performance-critical paths
  - Existing codebases may have valid reasons to keep enums

Altering Entities

Modify existing entity definitions with alter-entity:

2026-01-10T10:00Z alter-entity opinion "Formed stances on topics"
  # Metadata
  source?: link ; "Source that influenced this opinion"

  # Sections
  Examples? ; "Concrete examples of this opinion"

Default Values

Set default values for optional metadata fields:

2026-01-07T11:40Z define-entity reference "External resources"
  # Metadata
  status?: "unread" | "read" | "processed" = "unread"

If status is omitted when creating a reference, it defaults to "unread".

Self-Reference Entity

Create a special entity for self-references:

2026-01-07T11:40Z define-entity me "Entity to allow for self-references" ^self
  # Sections
  Bio ; "Need at least one section"

Then use ^self in entries:

2026-01-08T14:30Z create journal "Daily reflection"
  subject: ^self
  type: "reflection"

Validation

The thalo check command validates:

All required metadata fields are present
Field types match the schema
Required sections are present
Link references exist
Enum values are valid

Best Practices

Start with defaults: Use thalo init to get starter entity definitions
Keep schemas simple: Add complexity as you need it
Document fields: Use descriptions to explain field purposes
Version your schemas: Use timestamps to track schema evolution
Link related entities: Reference other entity types when appropriate

Next Steps

Learn about syntax basics
Explore CLI commands
See examples

Entity Definitions

On this page