Storage contract and UI
See how BaseBuddy chooses editor controls from storage primitives, value kinds, semantic roles, and patch modes.
The rule
BaseBuddy picks the UI control based on the storage shape first.
textrendered control = base type control + placement adapter + semantic overlayA semantic role can refine labels or workflow behavior, but it won't hide the real storage shape underneath.
Core concepts defines the storage contract, semantic role, and read-only states. Mapping fields and relations shows how those pieces appear when mapping real content fields.
Common storage placement
| Placement | Meaning | Write behavior |
|---|---|---|
| Direct column | Whole value lives in one column | Replace that value |
| JSON path | Value lives inside json or jsonb | Patch the path only |
| Composite field | Value lives inside a known composite column | Patch the composite field when safe |
| Array value | Whole column is a list | Replace the array |
| Array item | One mapped field writes one list index | Patch that index |
| Foreign key | Column points at one related row | Replace the foreign key |
| Join table | Many rows encode many selected values | Diff join rows |
| Related helper row | Separate row keyed by the post stores metadata | Upsert or patch the helper value |
| Join row | Single helper row per post stores one value | Upsert the helper row |
| Value-match relation | Stored value points at a related value | Replace the stored value |
| Polymorphic join | Helper rows point at multiple target types | Edit only with explicit discriminator rules |
| Derived read-only | Value is computed or unsafe | Do not write |
Value kinds
| Value kind | Default control |
|---|---|
| Text | Text input |
| Long text | Textarea or rich text editor |
| Markdown | Markdown-aware editor preserving mapped storage |
| Number | Number input |
| Boolean | Toggle |
| Enum | Dropdown |
| Date or datetime | Date/time input |
| JSON | Structured editor or JSON editor |
| Relation | Single or multi selector |
| Media | Media picker |
| File | File picker |
| Generated/system | Read-only display |
Why this matters
Two fields can both be called "title" but need completely different write behavior. One might be a direct text column. Another might be the first item in an array. Another might live inside JSON. The UI can look the same, but the patch has to respect the storage placement.
That's why BaseBuddy stores the contract in the mapping instead of guessing from field names during save.
For Markdown and rich text, this is the difference between editing with a rich surface and silently changing storage formats. How to map Markdown content safely covers that specific case.
Unsupported shapes
Some shapes shouldn't be editable by default: system identifiers, unknown composites, trigger-managed values, views without write rules, opaque binary blobs, and polymorphic relations without an explicit discriminator contract.
When BaseBuddy can't prove a safe write path, the correct behavior is to mark it read-only or unsupported.
Safe editing model explains why this protects production data, and How to fix a field showing as read-only helps you inspect a specific field.