Tags & Schemas

Tags in Thogits are not simple labels. Each tag is a component schema that defines typed fields. When you apply a tag to a thogit, that thogit gains the ability to store values for those fields.

Anatomy of a Tag

Field	Type	Description
`tag_id`	ULID	Unique identifier
`name`	String	Display name (must be unique across all tags)
`description`	String (optional)	What this tag represents
`fields`	Map<String, Schema>	Named fields with type definitions
`schema_version`	u64	Increments when fields change

Creating a Tag

POST /api/tags
{
  "name": "Task",
  "description": "A unit of work to be completed",
  "fields": {
    "status": {
      "type": "Select",
      "variants": [
        "Todo",
        "InProgress",
        "Done"
      ]
    },
    "priority": {
      "type": "MultiSelect",
      "variants": ["Low", "Medium", "High", "Critical"]
    },
    "due_date": "Date",
    "assignee": "Reference"
  }
}

This creates a tag with four fields: a single-select status, a multi-select priority, a date, and a reference to another thogit.

JSON Wire Format

Primitive types are plain strings. Complex types are objects:

{
  "fields": {
    "title": "String",
    "score": "Number",
    "active": "Boolean",
    "published": "Date",
    "parent": "Reference",
    "status": { "type": "Select", "variants": ["Open", "Closed"] },
    "tags": { "type": "MultiSelect", "variants": ["Frontend", "Backend", "Infra"] }
  }
}

See Field Types for a detailed reference on each type.

Schema Versioning

A tag is created with schema_version: 1.
When a tag is applied to a thogit, the TagData stores the current schema_version.
If the tag’s fields are updated (fields added, removed, or types changed), the schema_version increments.
Existing thogits retain their TagData at the old version until their values are explicitly updated.

This means you can evolve tag schemas without breaking existing data. The version number lets you detect when a thogit’s tag data was written against an older schema.

Unique Tag Names

Tag names must be unique. This enables the filter DSL to use tag names in dot-notation (e.g., Task.status) without ambiguity.

Soft Delete Behavior

When a tag is soft-deleted:

It is removed from all thogits that had it applied
The tag can be restored, but the associations are not automatically re-created
An audit log entry records the deletion

All Fields Are Nullable

Every field in a tag is nullable by default. When a tag is applied to a thogit, fields can be:

Omitted (not present in field_values)
Explicitly null ("field_name": null)
Set to a typed value (validated against the schema)

There is no concept of “required fields.” This keeps the system flexible — apply a tag and fill in fields as information becomes available.