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:
insert should be able to generate the record key/path from record fields.
validate --only records should parse records and verify the key/path matches the configured derived key.
select should expose the key consistently, ideally alongside the record fields.
- 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.
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-hubwe want each Markdown agent log record key to be generated from frontmatter fields:Example file path:
Corresponding frontmatter:
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:
insertDesired capability
Add a formal collection-level way to define derived record keys. Sketch:
The exact schema can differ, but it should be machine-readable and validated.
Expected behavior
Given a collection with derived record keys:
insertshould be able to generate the record key/path from record fields.validate --only recordsshould parse records and verify the key/path matches the configured derived key.selectshould expose the key consistently, ideally alongside the record fields.Related findings
Existing related specs cover nearby concepts, but not this exact feature:
ingitdb/spec/features/markdown-records/README.mdcovers Markdown frontmatter/body records.ingitdb-cli/spec/features/cli/insert/README.mdcovers--key/$idconsistency during insert.ingitdb-cli/spec/features/record-format/list-of-records/README.mdcovers list-record key resolution viaprimary_key,$id, orid.This issue is specifically about single record files whose filename/key is derived from record fields.