Skip to content

Add title_template support for schema-driven title computation #824

Description

@malibio

Summary

Extend the title field system (introduced in #821) to support schema-defined title templates. This enables custom entity types to have computed, searchable titles based on their properties.

Background

Issue #821 added an indexed title field for @mention search, computed as strip_markdown(content) for root nodes and task nodes. This works well for content-based nodes but doesn't support custom schemas where the title should be derived from structured properties.

For example, a "Customer" schema with fields first_name, last_name, and email should have a title like "John Doe (john@example.com)" computed from those properties.

Proposed Design

Schema Definition

Add an optional title_template field to schema properties:

{
  "id": "customer",
  "node_type": "schema",
  "content": "Customer",
  "properties": {
    "fields": [
      { "name": "first_name", "field_type": "string" },
      { "name": "last_name", "field_type": "string" },
      { "name": "email", "field_type": "string" }
    ],
    "title_template": "{first_name} {last_name} ({email})"
  }
}

Title Computation Logic

Priority order (first match wins):

  1. If node's schema has title_template → interpolate from properties
  2. If node is task type → strip_markdown(content)
  3. If node is root (no parent) and not date/schemastrip_markdown(content)
  4. Otherwise → None (no title)

Interpolation Rules

  • {field_name} → replaced with properties.field_name value
  • Missing/null fields → empty string (no special handling)
  • Non-string values → converted to string (numbers, booleans, dates)

When Title is Recomputed

  • On node create
  • On node update (when content OR properties change)

Content Display for Templated Entities

For custom entities with a title_template:

  • The computed title becomes the display "content" (read-only)
  • Users edit properties via a form interface
  • The content field may be hidden or shown as the computed title

Use Cases

  1. Customer entity: "{first_name} {last_name} ({email})" → "John Doe (john@example.com)"
  2. Invoice entity: "Invoice #{invoice_number} - {customer_name}" → "Invoice Skill preflight: agent must detect whether the nodespace CLI is installed and the daemon is healthy #1234 - Acme Corp"
  3. Project entity: "{project_name} [{status}]" → "Website Redesign [In Progress]"

Implementation Notes

Acceptance Criteria

  • Add title_template field to SchemaField/SchemaNode model
  • Implement template interpolation function (simple {field} replacement)
  • Update title computation in NodeService to check schema for template
  • Recompute title when properties change (not just content)
  • Add validation for title_template syntax in schema creation
  • Update core schema definitions if any should use templates
  • Add unit tests for template interpolation
  • Add integration tests for schema-based title computation

Future Considerations (Out of Scope)

  • Bidirectional parsing (content → properties extraction) - entity resolution use case
  • Form UI that mirrors template structure with Enter-key navigation
  • Conditional/optional field handling in templates

Related

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions