Skip to content

Data Model and IDs

Jump to bottom
Salvador Banderas Rovira edited this page Mar 15, 2026 · 4 revisions

GitPKM treats CSV files as relational tables and Markdown files as narrative/knowledge pages.

For strict implementation rules, see Schema Contract.

Core Rule

Stable IDs are the bridge between CSV, Markdown, and scripts.

Examples:

person_alex
org_learning_hub
prog_career_mentorship

ID Guidance

  • Use descriptive, human-readable IDs.
  • Avoid numeric-only primary IDs in source files.
  • Do not change IDs after creation unless required for a migration.

Regex contract:

^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$

Table Roles

  • Entity tables: people.csv, organizations.csv, programs.csv
  • Relationship tables: participations.csv, releases.csv

Dataset names are treated literally by the tooling.

Examples:

  • new person "Alex" writes to person.csv
  • new people "Alex" writes to people.csv

The system does not auto-singularize or auto-pluralize dataset names.

That same exact-name rule applies to:

  • note type values
  • inferred foreign-key column names
  • default relationship IDs in the CLI

Example Many-to-Many

id,person_id,program_id,role
part_alex_mentee,person_alex,prog_career_mentorship,mentee
part_taylor_mentor,person_taylor,prog_career_mentorship,mentor

Use direct foreign keys on entity tables for simple one-to-one and one-to-many relationships.

Use relationship tables when the relation itself needs structure.

Typical cases:

  • many-to-many relationships
  • relationship metadata such as role, dates, status, source, or confidence
  • relations that need their own stable ID and history
  • relations involving more than two entities

Optional Display Columns

To improve GitHub web readability, include helper columns like:

  • title_id + title_name
  • platform_id + platform_name

IDs remain the source of truth.

Markdown Mapping

Each entity may have a note with matching frontmatter:

---
id: person_alex
type: people
---

Link Format

Use relative Markdown links by ID label:

[person_alex](../people/person_alex.md)
[prog_career_mentorship](../programs/prog_career_mentorship.md)

Write inline links as [id](relative/path/to/id.md).

Clone this wiki locally