Core records

draft v0.117 records, each with a field table. Types are TypeScript-flavored and JSON-compatible.

Sister pages: fronting, optional modules.

records on this page

Producer
Capabilities
SourceRef
Privacy
Warning
System
Member
Birthday
ProxyTag
Group
GroupMembership
TaxonomyTerm
TaxonomyAssignment
CustomFieldDefinition
CustomFieldValue
Note
Asset

string JSON string

number JSON number

boolean JSON true/false

null JSON null

UUID file-local id (UUIDv4/v7/ULID)

ISO8601 UTC timestamp string

Date YYYY-MM-DD

HexColor #RRGGBB

T | null nullable value

T[] array of T

Record<K, V> open object map

"a" | "b" string enum (listed inline)

Envelope helpers

Producer metadata, capabilities declaration, source references, privacy, and warnings — these can appear at the file level or on individual records.

Producer

Identifies the app that wrote the export. Sits at the top of the envelope.

Field	Type	Required	Notes
app	string	yes	Display name of the producing app, e.g. `"Prism"`, `"Sheaf"`.
app_version	string	no	Producing app's release version.
exporter_version	string	no	Version of the OpenPlural exporter implementation, if separate from the app.
app_id	string	no	Short canonical app ID — see registered IDs in spec hub.

{
  "app": "Prism",
  "app_version": "3.4.0",
  "exporter_version": "0.1.0",
  "app_id": "prism"
}

Capabilities

Declares which OpenPlural modules this file populates. Lets importers know what to expect without scanning every array.

Field	Type	Required	Notes
modules	string[]	yes	Subset of: `"systems"`, `"members"`, `"groups"`, `"taxonomy"`, `"custom_fields"`, `"front_periods"`, `"front_events"`, `"front_comments"`, `"notes"`, `"assets"`, `"chat"`, `"boards"`, `"relationships"`, `"polls"`, `"reminders"`, `"habits"`, `"proxy"`, `"sharing"`, `"safety"`.

SourceRef

Records the original app's identifier for a converted record. Multiple refs allowed when a record has been round-tripped between apps.

Field	Type	Required	Notes
app	string	yes	Registered app ID, e.g. `"prism"`, `"sheaf"`, `"simply_plural"`, `"pluralkit"`.
collection	string	yes	Source-app collection/table name, e.g. `"members"`, `"fronts"`.
id	string	yes	Source-app primary key value (string-coerced).
uuid	string \| null	no	Some apps (e.g. PluralKit) expose a separate stable UUID alongside their public ID.

"source_refs": [
  { "app": "sheaf", "collection": "members", "id": "0193..." },
  { "app": "pluralkit", "collection": "members", "id": "abcde", "uuid": "5b2..." }
]

Privacy

A conservative common privacy descriptor plus the original source detail preserved for round-trips.

Field	Type	Required	Notes
visibility	"public" \| "friends" \| "private" \| "trusted" \| "unknown"	no	Conservative bucket. Importers without matching levels must round to the next-strictest. Sheaf maps from `system.privacy` directly.
source	Record<string, unknown>	no	Raw source-app privacy data — buckets, per-relation rules, scopes. Lossless preservation.

Warning

Documents loss, degradation, or skipped records. Used both in the envelope's warnings array and in importer results.

Field	Type	Required	Notes
level	"info" \| "warning" \| "error"	yes	Severity. `"error"` means data was lost; `"warning"` means data was degraded or partially preserved.
code	string	yes	Machine-readable code, e.g. `"module_not_supported"`, `"field_truncated"`, `"asset_uri_only"`.
record_type	string \| null	no	The OpenPlural record type or path the warning relates to.
record_id	UUID \| null	no	Specific record's `id` if applicable.
message	string	yes	Human-readable explanation.
count	number \| null	no	If the warning aggregates multiple records.

Systems & members

The two records every app has. Member fields overlap heavily across apps; system-level fields vary more.

System

A plurality system's profile and nesting metadata. Multiple systems may appear in one file (Lighthouse, Ampersand, and some user setups support nested systems).

Field	Type	Required	Notes
id	UUID	yes	File-local. References target for `system_id` on other records.
name	string	yes	System name. Sheaf: `system.name`. Prism: from `systemSettings.systemName`.
display_name	string \| null	no	Optional alternate display form.
description	string \| null	no	Markdown allowed.
tag	string \| null	no	System tag/suffix. Sheaf: `system.tag`. PluralKit: `system.tag`.
color	HexColor \| null	no	Accent color.
avatar_asset_id	UUID \| null	no	References an entry in `assets[]`.
banner_asset_id	UUID \| null	no	References an entry in `assets[]`.
parent_system_id	UUID \| null	no	For nested systems (Lighthouse subsystems, Ampersand nested systems).
archived	boolean	no	Defaults to `false`.
privacy	Privacy	no	See Privacy.
settings	Record<string, unknown>	no	App-agnostic system settings; app-specific settings belong in `extensions`.
source_refs	SourceRef[]	no	See SourceRef.
extensions	Record<string, unknown>	no	App-namespaced raw data preservation.

{
  "id": "sys_01HV4Z...",
  "name": "Example System",
  "display_name": null,
  "description": "Markdown or plain text",
  "tag": "| ex",
  "color": "#66ccff",
  "avatar_asset_id": "asset_avatar",
  "banner_asset_id": null,
  "parent_system_id": null,
  "archived": false,
  "privacy": { "visibility": "private", "source": {} },
  "settings": {},
  "source_refs": [{ "app": "sheaf", "collection": "system", "id": "u_..." }],
  "extensions": {
    "sheaf": { "date_format": "ymd", "replace_fronts_default": true }
  }
}

Member

A member, alter, headmate, custom front, or equivalent profile record. Role-like data lives in taxonomy, not on this record.

Field	Type	Required	Notes
id	UUID	yes	File-local.
system_id	UUID	yes	References `systems[].id`.
name	string \| null	no	Sheaf: `members[].name` (decrypted in export). Optional because some apps (Octocon) allow nameless alters and synthesize a display label. Importers without name handling should derive a display string from `display_name`, `pronouns`, or a fallback.
display_name	string \| null	no	Sheaf: `members[].display_name`. Prism: `headmates[].displayName`.
pronouns	string \| null	no	Free text — no enum because every app uses free text.
description	string \| null	no	Bio. Markdown allowed if `extensions.openplural.markdown_fields` says so.
age	string \| null	no	Free text (some apps store ranges, "ageless", etc.).
birthday	Birthday \| null	no	See Birthday.
color	HexColor \| null	no
avatar_asset_id	UUID \| null	no	References `assets[]`. Prism: `headmates[].profilePhotoData` becomes an Asset.
banner_asset_id	UUID \| null	no
proxy_tags	ProxyTag[]	no	See ProxyTag. PluralKit primary source.
is_custom_front	boolean	no	Defaults to `false`. Used for Simply Plural and Ampersand custom fronts.
archived	boolean	no	Defaults to `false`.
created_at	ISO8601 \| null	no	Sheaf: `members[].created_at`. Prism: `headmates[].createdAt`.
sort_order	number \| null	no	Lower = earlier in the list. Prism: `displayOrder`.
privacy	Privacy	no
source_refs	SourceRef[]	no
extensions	Record<string, unknown>	no

{
  "id": "mem_01HV4Z...",
  "system_id": "sys_01HV4Z...",
  "name": "Alex",
  "display_name": "Alex",
  "pronouns": "they/them",
  "description": "Bio",
  "age": null,
  "birthday": { "value": "2001-04-29", "precision": "day", "year_visible": true },
  "color": "#88ccaa",
  "avatar_asset_id": "asset_avatar",
  "banner_asset_id": null,
  "proxy_tags": [{ "prefix": "a:", "suffix": null }],
  "is_custom_front": false,
  "archived": false,
  "created_at": "2026-04-29T18:00:00Z",
  "sort_order": 0,
  "privacy": { "visibility": "private", "source": {} },
  "source_refs": [{ "app": "sheaf", "collection": "members", "id": "0193..." }],
  "extensions": {}
}

Birthday

Birthdays vary by precision: full date, month-day only, year-only, or with year hidden. Sub-record on Member.

Field	Type	Required	Notes
value	string	yes	Date in `YYYY-MM-DD`, `--MM-DD`, `YYYY`, or `YYYY-MM` form depending on `precision`.
precision	"day" \| "month" \| "year" \| "month_day"	yes	Granularity actually known.
year_visible	boolean	no	If `false`, importers should hide the year in UI even though it's stored. Defaults to `true`.

ProxyTag

PluralKit-style proxy tag. Sub-record on Member.

Field	Type	Required	Notes
prefix	string \| null	no	Match prefix, e.g. `"a:"`.
suffix	string \| null	no	Match suffix.

Organization

Groups when you want hierarchy or folders. Taxonomy when you want flat labels — roles, tags, sources, relationship categories.

Group

Hierarchical member organization. Sheaf groups, Prism member groups, Simply Plural groups, PluralKit (flat) groups all map here.

Field	Type	Required	Notes
id	UUID	yes
system_id	UUID	yes
name	string	yes
description	string \| null	no
color	HexColor \| null	no
emoji	string \| null	no	Single emoji. Prism: `memberGroups.emoji`.
parent_group_id	UUID \| null	no	Sheaf: `groups[].parent_id`. Prism: `memberGroups.parentGroupId`. PluralKit groups are flat — leave null.
sort_order	number \| null	no
source_refs	SourceRef[]	no
extensions	Record<string, unknown>	no

Sheaf mapping: Sheaf inlines member_ids on each group. Map those into GroupMembership records — one per member_id — instead of duplicating onto the group.

GroupMembership

Normalized many-to-many edge between groups and members.

Field	Type	Required	Notes
id	UUID	yes
group_id	UUID	yes	References `groups[].id`.
member_id	UUID	yes	References `members[].id`.
sort_order	number \| null	no	Position within the group.
source_refs	SourceRef[]	no

TaxonomyTerm

Reusable label of a given kind — a role, tag, source, relationship, etc. Created once, attached many times via assignments.

Field	Type	Required	Notes
id	UUID	yes
system_id	UUID	yes
kind	string	yes	See enum below.
name	string	yes
description	string \| null	no
color	HexColor \| null	no
parent_term_id	UUID \| null	no	For nested taxonomies (e.g. tag categories).
source_refs	SourceRef[]	no
extensions	Record<string, unknown>	no

Sheaf mapping: Sheaf tags[] become kind: "tag" terms. Sheaf inlines member_ids per tag — those become TaxonomyAssignment records with subject_type: "member".

TaxonomyAssignment

Attaches a term to a subject record (member, note, asset, etc.).

Field	Type	Required	Notes
id	UUID	yes
term_id	UUID	yes	References `taxonomy_terms[].id`.
subject_type	"member" \| "note" \| "asset" \| "front_period" \| "custom"	yes	Importers must skip assignments whose `subject_type` they don't support and emit a warning.
subject_id	UUID	yes
scope	"profile" \| "appearance" \| "session" \| "custom" \| null	no	Optional context — e.g. a role applies to a member's profile, vs. just a particular front.
source_refs	SourceRef[]	no
extensions	Record<string, unknown>	no

Custom fields

Splitting definitions from values lets importers type-check before assigning, and lets one definition cover any number of subjects.

CustomFieldDefinition

A custom field's name, type, and metadata. Sheaf, Prism, Simply Plural, Ampersand all expose this concept.

Field	Type	Required	Notes
id	UUID	yes
system_id	UUID	yes
name	string	yes	Display name.
field_type	string	yes	See enum below.
options	string[] \| Record<string, unknown> \| null	no	For `select`/`multiselect`. Sheaf stores `options` as JSONB `dict \| None`, so OpenPlural accepts either a string array or an object/record verbatim.
supports_markdown	boolean	no	Hint to importers for `text`/`markdown` rendering.
date_precision	"day" \| "month" \| "year" \| "month_day" \| null	no	For `date`/`date_range` types. Prism: `customFields.datePrecision`.
sort_order	number \| null	no	Sheaf: `custom_fields[].order`.
privacy	Privacy	no	Sheaf: `custom_fields[].privacy`.
source_refs	SourceRef[]	no
extensions	Record<string, unknown>	no

Recommended field_type values

"text" | "markdown" | "number" | "boolean" | "color" | "date" | "date_range" | "timestamp" | "month" | "year" | "month_year" | "month_day" | "select" | "multiselect" | "json"

CustomFieldValue

A single value for one definition + one subject. Sheaf nests these inside the definition; OpenPlural keeps them in a sibling array for normalization.

Field	Type	Required	Notes
id	UUID	yes
field_id	UUID	yes	References `custom_fields[].id`.
subject_type	"member" \| "system"	yes	For v0.1, only members and the system itself. Future expansion possible.
subject_id	UUID	yes
value	unknown	yes	Type matches the field's `field_type`. For `multiselect` use a string array; for `date_range` use `{ start, end }`; for `json` use the original payload.
source_refs	SourceRef[]	no
extensions	Record<string, unknown>	no

Content

Two records do all the work for free-form text and media: Note for journals and member notes, Asset for anything binary.

Note

Member notes, journal entries, communal journal entries, and dated entries. Maps cleanly from Prism notes, Simply Plural notes, Plural Star journals, Lighthouse journals, Sheaf journals, Ampersand journal posts.

Field	Type	Required	Notes
id	UUID	yes
system_id	UUID	yes
member_id	UUID \| null	no	Primary subject member for per-member entries. Null for system-wide entries; communal or multi-member journals may need a future explicit subject-members field.
title	string \| null	no
body	string	yes	Markdown unless flagged otherwise.
created_at	ISO8601	yes
updated_at	ISO8601 \| null	no
entry_date	Date \| null	no	For journal-style day entries (Plural Star, Lighthouse).
author_member_ids	UUID[]	no	Co-authored entries (Sheaf journal frozen-author snapshots, Ampersand multi-author).
color	HexColor \| null	no	Prism: `notes.color`.
visibility	"private" \| "system" \| "friends" \| "trusted" \| "public" \| null	no
pinned	boolean	no
content_warning	string \| null	no
attachment_asset_ids	UUID[]	no	Inline images/files via Asset.
source_refs	SourceRef[]	no
extensions	Record<string, unknown>	no

Open design question: Note currently collapses member notes, per-member journals, and communal journals into one record, with member_id meaning the primary subject member and author_member_ids meaning who wrote it. That's enough for Sheaf's current journal export, but apps like Lighthouse and Octocon suggest a possible future additive field such as subject_member_ids if multi-member journal scoping needs to become first-class. Splitting journals into a wholly separate core record looks less attractive than making note subject-scoping more explicit.

Asset

An image, file, or media blob. Records reference assets by ID instead of embedding bytes inline. Either inline data_base64/data_uri or external uri.

Field	Type	Required	Notes
id	UUID	yes
kind	"avatar" \| "banner" \| "image" \| "audio" \| "video" \| "file" \| "thumbnail" \| "unknown"	yes
mime_type	string \| null	no
file_name	string \| null	no
uri	string \| null	no	External URL. Importers should treat as fragile.
data_base64	string \| null	no	Base64-encoded payload (no data URI prefix).
data_uri	string \| null	no	Full `data:<mime>;base64,<...>`.
size_bytes	number \| null	no
sha256	string \| null	no	Hex digest. Recommended for dedupe.
width	number \| null	no	Pixels.
height	number \| null	no	Pixels.
duration_ms	number \| null	no	For audio/video.
source_refs	SourceRef[]	no
extensions	Record<string, unknown>	no	E.g. Prism's `blurhash`, `waveform`, encryption metadata.

An asset must populate at least one of uri, data_base64, or data_uri. Files with only uri should emit a "warning" with code "asset_uri_only" on export so importers know the asset isn't self-contained.

Continue to fronting for front periods, events, comments, and assignments — or optional modules for chat, polls, and the importer contract.