Open Human Model
This is the canonical, merged-to-main version. Drill into a branch or PR (left pane or chips above) to see proposed changes.
1. Why this RFC exists
The Open Human Model (OHM) is the schema that lets a contributor describe themselves to the rest of the system in a way that other tools — RFCs, applications, the meta-repo's directory — can read uniformly.
2. Scope
This RFC defines the on-disk shape of an OHM record, its required and optional fields, the versioning policy, and the migration path from the prior ad-hoc profile.yaml.
3. Schema
An OHM record is a YAML document with a frontmatter block of canonical fields and an open free-form body. The canonical fields are…
4. Versioning
OHM follows semantic versioning at the document level. Major bumps may break consumers; minor bumps add fields…
1. Why this RFC exists
§1 ¶1The Open Human Model (OHM) is the schema that lets a contributor describe themselves to the rest of the system in a way that other tools — RFCs, applications, the meta-repo's directory — can read uniformly.
§1 ¶2Today, every consumer reaches into the ad-hoc profile.yaml and projects its own subset of fields. The result is silent drift: two consumers can read the same file and disagree about what a contributor's handle even is.
2. Scope
§2 ¶1This RFC defines the on-disk shape of an OHM record, its required and optional fields, the versioning policy, and the migration path from the prior ad-hoc profile.yaml.
§2 ¶2It does not define an API for reading OHM records, nor a publishing protocol — those are independent concerns and will be specified in their own RFCs.
3. Schema
§3 ¶1An OHM record is a YAML document with a frontmatter block of canonical fields and an open free-form body. The frontmatter is what consumers parse; the body is for the contributor to write in.
name, handle, pronouns, and bio.display_name, handle, pronouns, bio, and established_at.display_name rename clarifies that this field is the human-facing label, distinct from the immutable handle.established_at is the date the contributor first claimed this OHM, expressed as ISO-8601. Subsequent edits do not bump it.§3 ¶4Each field has a normative type in §3.1 (string, ISO-8601 date, list of strings, etc.) and a non-normative example in §3.2. Consumers MUST validate the type and SHOULD treat any extra field they don't recognize as opaque.
§3 ¶5The free-form body is plain Markdown. It is intended for the contributor's own narrative — bio, working hours, time-zone notes, whatever they want collaborators to know. Consumers that don't render Markdown should pass the body through unchanged.
4. Versioning
§4 ¶2The current version is v1. The version is encoded as a single integer prefix (v1, v2, …) at the top of the file rather than embedded in the schema URI, so that consumers can read it without parsing.
.ohm/migrations/<from>-><to>.py. The bot runs them on graduation.§4 ¶4A version bump is a commit to this RFC's repo. The commit message MUST start with v<n>: and the body MUST summarize the changes in human-readable terms. Tooling depends on this format.
5. Migration from profile.yaml
profile.yaml and emits a v1 OHM record, preserving unknown fields under a legacy: key.§5 ¶2The tool runs once per contributor, idempotently. Re-running it on an account that's already migrated is a no-op: the tool reads the existing v1 record, validates it, and exits.
§5 ¶3Failure modes are noisy by design. A malformed legacy file aborts the migration with a clear error pointing at the offending line; nothing is half-migrated.
§5 ¶4For accounts that never had a profile.yaml, the tool seeds a minimal v1 record with only the handle field populated from the Gitea login.
3. Schema
An OHM record is a YAML document with a frontmatter block of canonical
fields and an open free-form body. The canonical fields are
namedisplay_name1,
handle, pronouns, and bio, and established_at.
The display_name rename clarifies that this field is the human-facing label, distinct from the immutable handle.
A record's established_at is the date the contributor first claimed this OHM, expressed as ISO-8601. Subsequent edits do not bump it.
4. Versioning
OHM follows semantic versioning at the document level. Major bumps may break consumers; minor bumps add fields without breaking; patch bumps are clarifications. 2 — 1 pending proposal in this paragraph
Migration scripts live alongside the RFC. 3 — 1 pending proposal
5. Migration from profile.yaml
The migration tool reads the legacy profile.yaml and emits
a v1 OHM record, preserving unknown fields under a legacy:
key.
1. Why this RFC exists
§1 ¶1The Open Human Model (OHM) is the schema that lets a contributor describe themselves to the rest of the system in a way that other tools can read uniformly.
2. Scope
§2 ¶1This RFC defines the on-disk shape of an OHM record, its required and optional fields, the versioning policy, and the migration path from the prior ad-hoc profile.yaml.
3. Schema
§3 ¶1An OHM record is a YAML document with a frontmatter block of canonical fields and an open free-form body. The canonical fields are display_name, handle, pronouns, bio, and established_at.
4. Versioning
§4 ¶1OHM follows semantic versioning at the document level. Major bumps may break consumers; minor bumps add optional fields; patch bumps are clarifications.
profile.yaml happens once per contributor, on first sign-in after this RFC ships.legacy: key.§5a ¶2The tool runs once per contributor, idempotently. Re-running it on an account that's already migrated is a no-op.
§5a ¶3Failure modes are noisy by design. A malformed legacy file aborts the migration with a clear error pointing at the offending line; nothing is half-migrated.
6. Open questions
§6 ¶1Should the migration tool be runnable offline, or only at first sign-in? Leaving as future work.