Skip to content

Support derived record keys from record fields #66

@trakhimenok

Description

@trakhimenok

Problem

Collection definitions currently support record_file.name: "{key}.md", so the filename stem becomes the record key. However, there is no formal way to define that the key should be derived from fields inside the record, nor to validate that the filename matches those fields.

This leaves important conventions as documentation-only. For example, in trakhimenok/project-hub we want each Markdown agent log record key to be generated from frontmatter fields:

{timestamp}-{agent}-{category}-{project}

Example file path:

agent-logs/$records/2026-05-30T08-12-43-copilot-cli-implementation-project-hub.md

Corresponding frontmatter:

timestamp: 2026-05-30T08:12:43+01:00
agent: Copilot CLI
category: implementation
project: project-hub

Today this can only be expressed as comments/README guidance. inGitDB does not appear to enforce the relationship between the key and the record fields.

Why this matters

This is important for user experience because users should not need to manually keep filenames and record contents in sync. If the key convention is part of the collection schema, tooling can:

  • generate correct filenames during insert
  • validate existing records reliably
  • report clear errors when a file is misplaced or renamed incorrectly
  • make Git diffs and folder layouts predictable
  • prevent broken conventions in CI/GitHub Actions

Desired capability

Add a formal collection-level way to define derived record keys. Sketch:

record_key:
  fields:
    - timestamp
    - agent
    - category
    - project
  format: "{timestamp}-{agent}-{category}-{project}"
  transforms:
    timestamp:
      type: datetime
      format: "2006-01-02T15-04-05"
    agent:
      slugify: true
    category:
      slugify: true
    project:
      slugify: true

The exact schema can differ, but it should be machine-readable and validated.

Expected behavior

Given a collection with derived record keys:

  1. insert should be able to generate the record key/path from record fields.
  2. validate --only records should parse records and verify the key/path matches the configured derived key.
  3. select should expose the key consistently, ideally alongside the record fields.
  4. Validation errors should include the record path, expected key, actual key, and field(s) used to derive it.

Related findings

Existing related specs cover nearby concepts, but not this exact feature:

  • ingitdb/spec/features/markdown-records/README.md covers Markdown frontmatter/body records.
  • ingitdb-cli/spec/features/cli/insert/README.md covers --key/$id consistency during insert.
  • ingitdb-cli/spec/features/record-format/list-of-records/README.md covers list-record key resolution via primary_key, $id, or id.

This issue is specifically about single record files whose filename/key is derived from record fields.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    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