SchemaBuilder Proposal: "Type" (`slot_type`) metadata

[cmrn-rhi]

Proposal: clarify the "Type" (slot_type) field menu labels, description, & guidance

Type: enhancement / documentation / UX
Needs: team decision on label family
Related: separate from the field-creation validation bug report (#558). This issue is copy/labels only.

Problem

The Type (slot_type) column in the Field/Slot tab offers three options. There has been confusion about how to use them within the testing team so far. Two possible causes:

1. The current guidance explains three numbered contexts but never ties each one to the menu label it corresponds to, so readers can't map paragraph > dropdown option.
2. Both description and guidance lead with LinkML internals (slot_usage, attributes) before stating the plain meaning.

The three concepts (generally, not for UI implementation)

1. Schema-level shared field [PURPLE]: defined once at the schema level, can be shared by more than one table.
2. Schema field reused in a table [GREEN]: a table reuses a schema field; it may fill in attributes the schema left empty but cannot change attributes the schema already set. (LinkML: appears in the table's slot_usage.)
3. Table-only field [RED]: defined only within one table, inherits nothing from the schema. (LinkML: appears in the table's attributes.)

Example:

---

Decision 1 - Menu labels (pick one family)

Each row is a self-consistent set; reviewers can pick a row. Current wording is the first row for reference.

Family	Concept 1 (schema-level shared)	Concept 2 (reused in table)	Concept 3 (table-only)
Current	Schema field	Table field (from schema)	Table field (stand-alone)
A. Level-based	Schema-level	Table-level (from schema)	Table-level (custom)
B. Plain words	Shared field	Borrowed field	Custom field
C. Plain + technical anchor	Source (schema field)	Borrowed (table field)	Custom (table field)
D. Linked	Schema	Linked	Local
E. Linked field	Schema field	Linked field	Local field
F. FAIR / linked-data	Global field	Reused field	Local field
G. FAIR / linked-data + Level	Global field (schema)	Reused field (table)	Local field (table)

Tradeoffs

• A (Level-based): foregrounds the level distinction that actually drives the choice; reads as a clean set. "Schema" is jargon for a true layperson, but fits a schema-editing audience well. Similar to Current.
• B (Shared / Borrowed / Custom): everyday single words, clearly distinct. "Borrowed" implies use it but don't alter it but people can still alter it. Slightly informal.
• C (Source / Borrowed / Custom + technical anchor): "Source" names the origin role directly; parenthetical keeps the tab's actual terminology visible. Lead words aren't grammatically parallel (cosmetic).
• D/E Linked / Linked field: "Linked" and "Local" are mild software jargon but may not be clear to everyone.
• F/G FAIR / linked-data: grounded in real global-vs-local scoping and the FAIR Reusable (R) principle; "Global/Reused/Local" stays readable. Best if signaling standards-alignment matters. @cmrn-rhi's recommendation.

Optional scope parenthetical (applies to any family): the lead word can carry the relationship while a parenthetical carries the location, e.g. Shared field (whole schema), Borrowed field (table ID), Custom field (table ID). Be careful about referencing "schema" and "table" without "field" in the label because people may be confused that you are editing non-field data types (regardless of the fact it is within the Field tab).

Caveat for all families: no short label can fully encode "you may fill empty attributes but cannot override what the schema already set." That constraint must live in the tooltip/guidance regardless of the label chosen. "Borrowed" and "Reused" hint at it; the level-based and FAIR sets are silent on it.

---

Decision 2 - Field description

What kind of field this row defines, and where it lives: a shared field defined once for the whole schema, a schema field that one table reuses, or a field belonging to a single table only.

If a label family is chosen, swap the three type names here to match.

---

Decision 3 - Field guidance

Type names should track the chosen label family.

Every field is one of three kinds. Pick based on where the field lives:

Schema field: A field defined once at the schema level that any table can share. Choose this when the same field is (or could be) used by more than one table and you want a single shared definition. It isn't tied to any one table. Editing a schema field requires expert user mode (File > Toggle expert user mode); because these definitions are standardized and shared by every table that reuses them, they should be changed only by an authorized editor.

Table field (from schema): One table's, defined by "Table ID", use of a field that already exists in the schema. Choose this when a table uses a shared schema field but needs to fill in details the schema left blank (e.g. a table-specific example or description). You'll choose which table it belongs to. You can only add values where the schema left an attribute empty - you can't change details the schema already set. Overriding a schema-set value is no longer reusing the field; it would create a separate, derivative definition with its own unique identifier that doesn't belong to the source schema. If the shared definition genuinely needs to change, that change must be made on the schema field itself by an authorized editor in expert user mode, so every table reusing the field stays consistent.

Table field (stand-alone): A field that belongs to one table only, defined by "Table ID", with no connection to the schema's shared fields. Choose this when a field is unique to a single table and reuses nothing from the schema. You'll choose which table it belongs to, and you control all of its attributes.

HOW TO CHOOSE:
Shared by many tables = Schema field.
A table reusing a schema field and filling in the blanks = Table field (from schema).
A one-off custom field for a single table = Table field (stand-alone).

LinkML Technical Note: Schema field = a top-level slot definition. Table field (from schema) = the slot listed in a table's slot_usage (customization limited to empty attributes). Table field (stand-alone) = a field listed in a table's attributes, fully independent of the schema.

---

Review checklist

• Choose a label family from Decision 1 (or keep current)
• Decide whether to add the scope parenthetical
• Approve / edit the Description (Decision 2)
• Approve / edit the Guidance (Decision 3)
• Update the type names in the Description & Guidance to match the chosen family
• Decide whether to add a refined support diagram to the guidance (e.g. via a link to an external website or reference to a user guide).
• Confirm whether "Schema field" creation should be gated behind expert user mode (pending [Schema Builder] Entity Reuse - cannot create table-level fields; validation messages reference UI that doesn't exist #558 ); if so, make sure descriptions and guidance address this.

[cmrn-rhi]

Dev meeting 2026-07-22 (@cmrn-rhi @ddooley @cbarcl01 @griffie):

Agreed upon labels:
Global field (schema)
Derived field (table)
Custom field (table)

Meaning overview:
Global field (schema) - Cannot modify; huge impact, need auth and expert user mode
Derived field (table) - Can modify within reason
Custom field (table) - Can fully modify

Description length is fine but needs to be adjusted to fit these labels. The guidance is too long and should ideally be one sentence (at most) per option and the more technical implications can be in a more in-depth resource.