Custom Fields Reference

Field types, validation, schema, and visibility for SG-Core Custom Fields.

Custom Fields is the schema layer attached to Custom Objects. Each Custom Object type carries a Custom Fields group. That group defines which fields appear on every record of that type, what data those fields accept, and who can see them. This page is the authoritative catalog: every field type, its rules, its schema shape, and how it behaves when records are created, edited, and read.

What is this for?

Read this page when you need to know:

• which field type to choose for a given data shape,
• what validation a field type enforces,
• how to define a field in the schema editor,
• what visibility settings control who sees field values,
• how default values and required flags interact,
• or what "relation" cardinality means at the record level.

For operator how-to — creating groups, adding fields, reordering — open SG-Admin Custom Fields. For the Custom Object type model that Custom Fields attaches to, open Custom Objects.

Scope

This reference covers:

• every field type available in the Custom Fields schema editor,
• the validation rules each type supports,
• the schema definition shape (what the group configuration stores),
• field visibility modes (admin-only, public, API),
• required vs optional behavior,
• default value support per type,
• how fields attach to Custom Object types,
• and the behavioral boundaries operators need to know about.

This reference does not cover:

• creating or managing field groups (operator how-to lives in SG-Admin Custom Fields),
• rendering field values in templates (template authoring lives in the SG-Builder documentation),
• or per-release field-type additions (those appear in the Changelog).

Where to find it

Custom Fields groups are managed inside each Custom Object type's configuration screen. Navigate to the Custom Object type, then open its Schema tab. Each group entry lists the fields in order; clicking a field opens its settings panel. Field types are set at creation time — the type of an existing field cannot be changed after records carry values.

Field types

The schema editor offers ten field types. Each type matches a distinct data shape and carries its own set of validation options.

text

Stores a plain string. Use for names, labels, short copy, external identifiers, and any free-form text that does not need formatting.

The regex validation runs on save. A field marked max length 100 with a regex pattern for URL format will reject any value that fails either check. Both rules must pass independently.

number

Stores an integer or decimal value. Use for prices, quantities, ratings, measurements, and any numeric data.

Setting decimal places to 0 constrains the field to integers. Min and max are inclusive bounds. A field defined as min 1, max 100, decimals 0 rejects 0, rejects 101, and rejects 1.5.

date

Stores a date or a date-with-time. Use for publish dates, expiry dates, event dates, deadlines, and any time-anchored data.

The future-only and past-only flags are mutually exclusive. A date field with a range defined rejects any value outside the range even if the future-only flag is also set; the range takes precedence. The "today" dynamic default resolves at record creation time, not at schema definition time.

boolean

Stores a true/false toggle. Use for flags: published, featured, active, archived, visible, or any binary state.

A boolean field without a default value starts as false on new records. The edit UI renders the field as a checkbox or toggle depending on the active theme.

select

Stores one value chosen from an operator-defined list. Use for status fields, category assignments, priority levels, type classifiers, and any enumerated single-choice data.

Options are defined as a list of label/value pairs in the schema editor. The stored value is the value key, not the display label. Changing a label does not change stored values. Removing an option from the list does not clear existing records that carry the removed value — those records retain the stored string but the UI will display it as "Unknown option" until the operator remaps or clears the value.

multi-select

Stores one or more values from an operator-defined list. Use for tagging, skill sets, applicable regions, content categories, and any data that can legitimately hold multiple simultaneous values.

The same label/value pair semantics apply as for select. A record with no selections stores an empty array, not null. The minimum-selections validation requires the array length to meet or exceed the configured minimum before the record saves.

file

Stores a reference to a file in Media Library. Use for PDFs, spreadsheets, downloadable assets, certificates, and any non-image binary attachment.

File fields default to admin-only visibility. A public file field is possible but requires explicit opt-in in the visibility setting. The stored value is a reference to the Media Library record; if the file is deleted from Media Library, the field retains the stale reference until the operator clears it.

image

Stores a reference to an image in Media Library. Use for featured images, hero images, thumbnails, logos, and any image asset attached to a record.

Dimension validation checks the uploaded image dimensions at the time the image is selected. Images already in Media Library that fail the dimension rule cannot be assigned to the field; the operator must upload a compliant image first.

rich-text

Stores formatted HTML content. Use for long-form descriptions, biographies, product narratives, terms and conditions, and any field that needs paragraph structure, links, or inline formatting.

The rich-text editor produces a sanitized HTML subset. Raw <script> tags are stripped on save. The character count validation strips HTML tags before measuring — a value of <p>Hello</p> counts as 5 characters, not 14.

relation

Stores a reference to one or more records of a specified Custom Object type (or a default type: Pages, Posts, Products, Events, Locations). Use for author references, related articles, linked products, parent organisations, and any association between records.

Cardinality "one" enforces a maximum of one selection in the UI. The underlying storage is still an array with one entry. When the target record is deleted, the relation field retains the stale ID. The operator must clear stale relations manually or via bulk action. Cross-type relations are permitted: a Custom Object of type "Project" can carry a relation field pointing to records of type "Client" (another Custom Object type).

Schema

A Custom Fields group schema is the ordered collection of fields bound to a Custom Object type. The schema stores, per field:

{"field_id": "cf_2041","type": "select","label": "Status","key": "status","required": true,"visibility": "public","options": [{ "label": "Active", "value": "active" },{ "label": "Archived", "value": "archived" },{ "label": "Pending Review", "value": "pending_review" }],"default_value": "active","order": 3}

Field properties common to every type:

Type-specific properties (options, validation rules, cardinality) are stored under a config key alongside the common properties.

Visibility

Field visibility controls which contexts can read a field's value. Three modes are available:

Visibility is per field, not per group. A group can mix admin-only fields (internal notes) with public fields (display title) with API fields (external integration ID) on the same Custom Object type.

Changing a field's visibility takes effect immediately on next record render. No re-save of individual records is required.

Required vs optional

A required field blocks record save until a value is present. Required applies at the edit UI level and at the storage level. Programmatic saves that omit a required field return a validation error; the record is not written.

Optional fields (the default) save with an empty or null value. An optional text field on a record that has never been filled stores an empty string. An optional relation field stores an empty array. Optional fields that carry a default value will have that default applied only at record creation time. Editing an existing record does not re-apply the default to an empty optional field.

Default values

Default value support varies by type:

Defaults apply only to records created after the default is set. Existing records that pre-date the default addition are not backfilled. To apply a default retroactively, use the bulk-edit surface on the Custom Object type's list view.

How fields attach to objects

A Custom Fields group is created and named in the schema editor. The group is then bound to a Custom Object type. One type → one group → many fields.

When the group is bound:

• every existing record of that type immediately shows the new group's fields in the edit UI,
• every new record created from that point carries the fields on first open,
• fields that are required but have no default will block save on existing records if an operator opens and saves them without filling the new required field.

Multiple groups on one type are not supported. If a type needs fields from two different groups, merge the fields into one group.

Examples

Example 1 — Agency client project tracker

An agency creates a Project Custom Object type. The schema group carries:

• client_name (text, public, required)
• project_status (select: Active / On Hold / Delivered, public, default: Active)
• launch_date (date, future-only flag off, public)
• budget_band (select: Small / Medium / Large, admin-only, optional)
• hero_image (image, public, required)
• results_summary (rich-text, public, optional)

The budget_band field is admin-only — it appears in the edit UI but does not render on the public /projects/<slug>/ page. The results_summary field is optional — early-stage projects save without it; the operator fills it after the project concludes.

{"field_id": "cf_2099","type": "date","label": "Launch Date","key": "launch_date","required": false,"visibility": "public","config": {"future_only": false,"past_only": false},"default_value": null,"order": 3}

Example 2 — Multi-select skills on a team member type

A professional services firm creates a Team Member Custom Object type. One field is specialisms (multi-select, public, minimum 1 selection):

Options: Strategy / Research / UX Design / Brand Identity / Content / Development / Analytics

Every team member record must carry at least one specialism. The field stores an array: ["research", "ux_design", "content"]. The public team page template reads the array and renders each value as a badge.

Example 3 — Relation field linking case studies to authors

A content team creates two Custom Object types: Author and Case Study. The Case Study type carries a lead_author relation field pointing to the Author type, cardinality "one". Each Case Study record holds a single Author ID. The public case study template reads the relation, fetches the Author record, and renders the author's name and headshot.

When an author record is archived (not deleted), the relation remains valid. When an author record is deleted, the lead_author field on linked Case Study records retains the stale ID. The operator resolves stale relations from the Case Study list view using bulk edit.

Edge cases

Renaming a field label. Label changes are cosmetic. The key property — what templates and integrations reference — does not change. Rename labels freely without breaking existing templates.

Reordering fields after records exist. Field order is a schema-level setting. Reordering fields changes the display order in the edit UI immediately. Existing stored values are not affected.

Adding a required field to a type that already has records. New required fields with no default value do not block existing records from displaying. They block saving if an operator opens an existing record and attempts to save without filling the new field. The recommended pattern: add the field as optional, bulk-fill existing records, then change to required once all existing records carry a value.

Changing a select option's value key after records exist. Changing the value key (not the label) of an option orphans every stored record that carries the old value. Those records retain the old string; the field UI renders it as "Unknown option." Change option labels freely; never change option value keys on live types with existing records.

Deleting a field from the schema. The field disappears from the edit UI and template access immediately. Stored values are retained at the storage layer. Restoring the field (adding a field with the same key) does not recover the stored values in the UI by default — the storage values are still present but only surfaced if the type and key match exactly. Within the trash retention window, restoring the entire schema group recovers all field definitions and their stored values together.

Relation field pointing to a type with public render off. The relation is valid at the storage layer. The referenced record has no public URL. Templates that attempt to render a public link to the related record will produce an empty href. Design templates to check for public-render availability before outputting links.

Related features

• Custom Objects — the post-type model that Custom Fields attaches to.
• Pages & Posts — the default record types; Custom Fields can also attach to Pages and Posts in supported configurations.
• SG-Admin Custom Fields — the operator how-to surface for creating and managing groups and fields.
• SG-Admin Custom Objects — the operator surface for creating and configuring Custom Object types.
• Media Library — the source for all file and image field values.

Vocabulary