Complete the reference field: collection picker in schema editor + content picker in content editor

[MA2153]

Current state

The reference field type exists throughout the codebase as a recognized type, but the admin UI was never built out. The scaffolding is all there — the type is defined, the DB column type is mapped, the manifest correctly surfaces kind: "reference" for DB-backed fields — but neither the schema editor nor the content editor has the UI to make it usable.

What's missing

1. No collection picker when creating a reference field

FieldEditor (the dialog for adding fields to a collection) has type-specific configuration UI for select/multiSelect (options list), string/text (min/max length, pattern), and number/integer (min/max value). For reference, there is no step to select which collection the field points to.

FieldWidgetOptions already has collection?: string with the comment "For reference - which collection to reference", but it's never populated because the UI to collect it doesn't exist.

2. Plain text input instead of a content picker when editing content

ContentEditor's FieldRenderer has a switch (field.kind) with cases for all the common types. There is no case "reference":. It falls through to default:, which renders a plain <Input> — so editors currently see a free-text box and would have to type a raw content ID by hand.

ContentPickerModal already exists (it's wired up in MenuEditor for picking menu items) and is fully capable of browsing collections with search and pagination. It just isn't wired into ContentEditor for reference fields.

3. isReference marker missing in the static field helper

fields/reference.ts returns a plain z.string() schema with no isReference flag. The manifest handler in api/handlers/manifest.ts checks schema.isReference to detect reference fields in the static live.config.ts path — but since the flag is never set, that check never fires. Fields defined statically via reference() would get kind: "string" in the manifest instead of kind: "reference". (The DB-backed path is unaffected — it uses FIELD_TYPE_TO_KIND directly and correctly maps to "reference".)

Design questions that need answers before implementation

• Can the target collection be changed after field creation? Field slugs are immutable; it's worth deciding whether the options.collection pointer should be too.
• Should the content picker filter to published items, draft items, or all? The current ContentPickerModal shows all statuses.
• Reverse links / link-back? Should EmDash track "which items reference this item"? There's currently no indexing or query support for it.
• allowMultiple? FieldWidgetOptions already has allowMultiple?: boolean for reference fields. Should multi-reference be in scope here or deferred?

What a complete implementation would involve

1. Add a collection selector step to FieldEditor when selectedType === "reference", persisting the chosen collection to options.collection.
2. Add case "reference": to ContentEditor's FieldRenderer, opening ContentPickerModal (or a similar picker) filtered to the collection stored in field.options.collection.
3. Fix fields/reference.ts to tag the schema with isReference: true so the static manifest path works correctly.

[einfachai]

I would vote a implementation like this: Target collection should not be immutable. The content picker should show all status. Reverse links are useful but not needed in the first implementation. Multiple references should be supported in the future at least.

[MA2153]

Thank you for sharing. Some questions:

• Could you explain why the target collection should be immutable? I don't think that's even a thing.
• I think multiple references could in theory be implemented using the repeater field but worth double checking.

[einfachai]

"Could you explain why the target collection should be immutable? I don't think that's even a thing."
Since existing fields can't be assigned to other post types, I just thought they should be immutable, but after thinking about it, I think it's not a good decision, since you would need a lot of duplicated fields if you have a lot of post types that share a field with the same functionality and name. So I will edit my post and say they shouldn't be immutable, so it can be later implemented that you can assign the same field to multiple post types.

[rob-j-oliver]

Coming from this as a content editor, rather than a developer, I'd love to see something like Voxel's (WP) implementation of their Reference Field, as a future goal. https://docs.getvoxel.io/articles/post-relation-field-2/

[ascorbic]

If anyone would like to take this on, that would be great. Happy to discuss details of implementation

[MA2153]

I am happy to take on this!

[ascorbic]

Awesome!

[MA2153]

@ascorbic few interconencted questions:

• What should this look like in the database? A join table? A JSON array in the same table? Or something else?
• Should FK relationships be enforced? If we are using JSON arrays, this is not possible. The benefit is that we can warn users when they are deleting something that is being referenced.
• Should it be a two-way sync?

cc @rob-j-oliver @einfachai

[ascorbic]

I think a join table is the right way, and we'd drop the text field from the content type. Instead we'd put the position in the join table, and slot it in. This would give us backlinks too.

One thing we'd need to consider is i18n: do we automatically handle it? Does a link go to a particular locale?

Also at runtime, we should think about hwo we can best query this in a way that's efficient.

Some of the ideas from Voxel look cool. Being able to specify whether you can link to drafts, and cross-author. These are nice, but not required though.

I would say we don't enforce foreign keys in SQL, because it would be hard to model all the sorts of polymorphism this could support, as well as things like soft delete, drafts etc.

[rob-j-oliver]

Glad to see this! Backlinks and warning content editors when deleting something that is referenced (<- especially) would be great to see, save a lot of expletive moments for us editors.

I appreciate this maybe for the future, but as @ascorbic mentioned Voxel's cross-author post relation field, a very neat feature is getting the target author to approve the reference, and in the Admin UI there are four relation types - Has one, Has many, Belongs to One, Belongs to many, both options for thse fields opens a world of possibilities for us directory/marketplace/event site builders and editors.

[MA2153]

One thing we'd need to consider is i18n: do we automatically handle it? Does a link go to a particular locale?

I think we should handle it automatically. Let's consider the same example from Voxel: Events and Places

• Both of them need to be collections instead of taxonomies because they contain more than just names
  • Each event has a name, date and time, place, etc.
  • Places have names, directions, operating hours, etc.
• If an Event was created in English then translated to German, there is no reason for the editor to have to link back to the English/German version of each Place. It is an unnecessary headache.
• If they truly need different references for each translation, they should be separate entities. Translations are by definition just that.

[MA2153]

Hi @ascorbic and all. Since we are doing a join table approach with back-links, I thought of something: why not surface the relationship on both sides as fields?

For example, say you have Chapters and Lessons as collections. Each Lesson belongs to a Chapter. If you are on the Chapter side of things, it would be useful to see the lessons it contains directly, rather than putting it in a "Referenced by" side panel or something similar. Same thing if you are checking a Lesson.

We still end up with "one row per reference" in the DB, but it makes it easier for the user to navigate the relations.

Here is the full proposal: https://github.com/MA2153/emdash/blob/reference-field/docs/superpowers/specs/2026-05-10-reference-field-relations-design.md

Please let me know your thoughts :) I know it's a Sunday so no rush.

[masonjames]

Very excited about this one. It's a huge levelup for emdash. think the current proposal is in a good place, especially with the join table, automatic i18n behavior, and surfacing the relation on both sides as fields instead of hiding it away in a “referenced by” panel.

A few additions I think would make the proposal more complete without changing the core direction:

1. Add a stable relation identity

Right now the relationship is mainly understood through the two reciprocal field ids. That works technically, but I think it would help to give the relationship itself a stable identity too.

Something like:

relationKey: "lesson_chapter"

This could be generated when the pair is created and stored on both field rows without a separate relations table. It gives the relationship something human-readable for debugging, imports/exports, API docs, migrations, and future tooling.

For example, if a user creates:

Lesson.chapter
reciprocal Chapter.lessons

The pair could share relationKey = "lesson_chapter".

This should probably be editable before creation, then locked afterward, similar to slugs.

2. Add reciprocal field visibility

I like the idea that the reciprocal side is a real field. That feels much better for editors than a hidden backlink panel. But we may want some control over how visible/editable the reciprocal field is.

Possible options:

reciprocalVisibility: "editable" | "readonly" | "hidden"

Default could stay editable, matching the current proposal.

The reason is that some relationships are useful to edit from either side, while others are mainly useful for navigation.

Example:

On a Lesson, editors should probably edit the Chapter field directly.
On a Chapter, seeing the related Lessons is useful, but maybe it should be read-only or hidden depending on the site’s workflow.

This keeps the “real reciprocal field” model, but gives schema designers a way to avoid clutter or accidental edits in the admin UI.

3. Include normal field UI options for reference fields

Reference fields will often be important editorial fields, so I think they should support the same practical field-level affordances as other fields where possible.

I would consider adding:

description?: string
placeholder?: string
emptyLabel?: string
cssClass?: string
defaultValue?: string | string[]

A few examples:

• description: “Choose the venue where this event takes place.”
• placeholder: “Search places…”
• emptyLabel: “No place selected”
• cssClass: useful for admin customization and layout hooks.
• defaultValue: useful when creating content in workflows where a default relation is common.

defaultValue should still go through the same validation as a manually selected reference. For single-cardinality fields it could be one target group id; for multi-cardinality fields it could be an ordered array.

Not all of these have to be required for the first pass, but I think they are worth including in the spec so the reference field does not end up feeling more limited than other field types.

4. Make target status behavior explicit

Since the current picker shows all statuses, I think the proposal should explicitly define the behavior rather than leaving it implied.Maybe something like:

targetStatusPolicy: "published_only" | "drafts_allowed" | "all_visible"

My instinct is that the default should probably be all_visible, because that matches the current picker behavior and respects what the editor has permission to see. But the important part is making the rule visible and intentional.

Different sites will expect different behavior:

• A public marketing site may only want references to published content.
• An editorial workflow may need draft-to-draft references before anything is published.
• Internal content models may simply want all visible content.

The picker can still show status badges either way, but the field config should decide what is selectable.

The initial proposal is already excellent @MA2153. Wanted to add my 2 cents thinking about additional features editors/content managers will deeply appreciate.

[MA2153]

I am thinking the initial PR should solely focus on the database. We can figure out how to attach fields later to relations, but just to keep the scope smaller we should mirror how EmDash currently handles join tables, like the (byline/content entry) and (taxonomy term/content entry) tables.

[masonjames]

@MA2153 if you’re still up for taking the first slice, the database-only PR you described sounds like the right next step. Makes sense to keep it intentionally narrow: relation/join-table schema, forward-only migration, registry/repository plumbing, and tests around create/update/delete/i18n behavior, leaving reciprocal UI fields and richer editor affordances for follow-ups. Link it here when you open it. I'm happy to assist with review and additional code as necessary

[MA2153]

@masonjames #1367

[MA2153]

@masonjames repository (data layer) PR: #1444

[MA2153]

#1535