Define content types and fields
A content type describes a stable API collection. Labels help editors; identifiers are the contract used by applications.
How to use it
- Open Content types and create a type or browse starter templates. Templates produce editable definitions, not a live connection to another CMS.
- Choose a display name and a lowercase API identifier. Add labelled fields and mark only genuinely required publication values as required.
- Use text, long text, number, boolean, color, date/time, single choice, multiple choice, Markdown or rich text as appropriate. Use image/file and reference fields for shared resources.
- Review defaults and translation settings, then save. Existing field keys and types are protected; compatible additions and label/default/validation changes use the model editor.
Good practice
- Prefer small models with descriptive field labels. Coordinate schema changes with website developers.
- Treat defaults as an authoring aid; review existing entries after changing publication requirements.
Avoid
- Do not encode business structure in a long free-text field when it needs separate validation.
- Do not assume new required rules retroactively rewrite published snapshots or rename an existing API identifier.
Save and reuse model templates
Model templates are private, environment-local schema snapshots. They copy content type structure and reference dependencies, including component definitions; they do not copy entries, media files, credentials or a live connection. They differ from content templates, which copy selected draft values into a new entry.
How to use it
- Open Content types → Your model templates. Name the template, select source types with checkboxes and save. Reference dependencies are included automatically, up to 25 content types and 256 KiB per document; each environment has 50 saved snapshots.
- Use Export JSON to download the saved schema. Field defaults are included, so review them before sharing. Edit / recapture replaces only the saved snapshot with the selected source types as they are now; earlier copies and source content are unchanged.
- Choose the destination workspace and environment. Upload a model-template JSON file, or choose Review use for a saved template. Read the proposed types, components, identifier conflicts and workspace-wide capacity impact.
- Imports create new types only: any existing API identifier, incompatible component definition or exceeded allowance blocks the whole import. To reuse a structure in the same environment, edit its identifiers and every corresponding reference in a reviewed copy of the JSON file, or choose an empty environment.
- Confirm the impact and choose Create content types. Approval expires after 15 minutes; changes to schema, plan or usage require Review again. Permissions and limits are checked again when applying. Nothing is published.
- Remove deletes the library snapshot only. New component definitions require the existing Owner or Developer component-management access; custom roles still need the relevant model grants for every selected or imported type.
Good practice
- Use safe shared defaults, stable API identifiers and a version-controlled reviewed JSON file for repeated project structures.
- Check the destination environment and available capacity before importing. Keep the previous exported file when replacing a library snapshot.
Avoid
- Never put passwords, tokens or private editorial values in field defaults. Exported JSON is portable and must be shared deliberately.
- Do not use template imports to update existing types or migrate entries. Use reviewed schema migrations or environment transfers for those tasks.
Organize long entry forms into groups
Editor groups keep related top-level controls together without changing your flat content fields or API responses.
How to use it
- In Content types, open a type you can manage. Give related top-level fields the same Editor group name, then save. Names are case-sensitive, single-line text of at most 80 UTF-8 bytes; Studio trims surrounding whitespace and removes a blank group.
- Open an entry. Sections start expanded; their header buttons work with the pointer, Enter or Space. Groups follow their first field's schema position and preserve field order within a section. Unassigned fields appear in General when other fields are grouped; completely ungrouped types keep their existing layout.
- Collapse sections to focus on your task. Their controls remain mounted, preserving unsaved input. Errors and field-target navigation reveal the relevant section. Collapsing never bypasses requiredness, conditions, permissions or backend validation.
- Save, review, schedule, publish and restore through the usual workflow. Group metadata travels in supported model exports/imports/promotions and reviewed CLI additions; entry values, GraphQL field types and generated TypeScript/C#/Python types stay unchanged. Group names do not rewrite history or publications. Saving a group change still advances the model version; existing version-bound approvals, schedules and release reviews may need to be renewed, following the usual schema-change rules.
- This version groups top-level content-type fields. Component child groups, manual section ordering, field widths and multi-column layouts are not included.
Good practice
- Use a few task-focused names such as Product details, Images and Search & social.
- Keep important fields easy to find and check the resulting form on mobile.
Avoid
- Do not use a collapsed group as a privacy or permission boundary.
- Use components and references for content relationships; editor grouping does not create nested data.
Select several predefined content values
Multiple choice gives creators labeled checkboxes for controlled attributes such as product features. Content APIs return selected string arrays; your website decides how to display them. This is not a public form builder or visitor-submission feature.
How to use it
- In Content types, add a Multiple choice field with a stable API key. Use New choice and Add choice to define 1–100 distinct nonempty options; keep allowed choices checked. Option strings have no leading/trailing whitespace and are limited to 100 UTF-8 bytes each.
- Open Default value, optionally check Use a default value and select its checkbox values. Defaults apply only to independent new drafts or new component instances; explicit empty/null values and existing content are not replaced. Multiple choice stays shared across languages: edit it in the workspace's default language.
- Open Help & validation for instructions and optional Minimum selections / Maximum selections under Add publishing validation. Bounds are whole numbers from 0 to 100, minimum no greater than maximum. Optional empty selections stay allowed; combine Required with a minimum when every publication needs selections.
- In an entry, select applicable values or choose Clear selection. Save incomplete drafts as usual. Backend type/allowed-value checks always apply; selection counts and requiredness apply before publication, including hidden fields and reusable component children.
- REST, GraphQL, RPC and the client preserve arrays. Filter top-level multiple-choice fields with contains_any or contains_all; GraphQL uses containsAny and containsAll. Supply 1–100 unique allowed strings; scalar equality and sorting are not supported for this field. Published filters never inspect private draft edits.
- Keep option strings stable. Existing values cannot be removed or renamed once a type has entries, protecting drafts, history and publications. Tighter count rules or newly Required fields use Review publishing rules. See docs/reference/multiple-choice.md for schema, filter and client examples.
Good practice
- Use a small controlled vocabulary for attributes. Choose references when categories need independent content, translations or pages. Regenerate client types after schema changes and keep consuming applications responsible for rendering.
Avoid
- Do not turn a scalar Single choice into an array on an existing populated type, encode a large evolving taxonomy as options, or treat content checkboxes as consent from website visitors. Never put secrets in options or help text.
Manage one-off content with a single entry
A singleton is a content type limited to one entry in each environment. Use it for site settings, a homepage or a shared navigation record. It has the same fields, permissions, publication and history as a collection.
How to use it
- Open Content types, create or edit a type, and check Single entry before saving. Types with multiple entries cannot switch; review and explicitly remove extra entries first. No content is merged or deleted automatically.
- Open the type in Content and choose New entry. Creation is explicit: browsing an empty singleton never creates a draft. Once saved, open its existing entry to edit it; no second entry is offered.
- Save, request review, schedule, publish, unpublish and restore as usual. Drafts and unpublished records still occupy the slot. Translations use that same entry ID rather than separate entries.
- Consuming applications use the existing REST, GraphQL or RPC collection and item calls through their preferred client. Collection results contain zero or one accessible record. There is no automatic upsert or framework-specific route.
- Imports and promotions preserve singleton mode and require an empty target or an existing linked identity. They never replace a different target entry implicitly. Uncheck Single entry and save if the type should allow more future entries; existing content and history stay intact.
Good practice
- Choose a singleton for content that is truly one-off. Keep products, articles and categories as collections. Check the environment before creating or publishing.
Avoid
- Do not delete an entry just to change its values: open it to preserve its ID and history. A second entry is rejected by the backend even if a browser control is re-enabled. Keep permissions and plan allowances in mind; singleton mode does not bypass either.
Suggest editable slugs and prevent duplicates
Slugs remain ordinary text. Suggestions help authoring; your website owns routes and redirects. Existing fields and published URLs stay unchanged until you explicitly edit and publish.
How to use it
- In Content types, enable slug suggestions on a top-level Text field, choose a different sibling Text source, and review uniqueness. The checkbox starts checked; clear it for suggestions only. Components do not support slug settings. Save the type; duplicate existing values prevent enabling uniqueness without changing any entry.
- In an entry, write the source title and choose Suggest from the source field. It uses current unsaved text, produces a lowercase ASCII suggestion and remains editable. If the title cannot produce a suggestion, type the slug yourself. Changing a title or saving never silently regenerates a value.
- Save draft, review and publish as usual. A new draft value does not rename the published snapshot. Both draft and live values stay reserved to that entry until they are no longer used.
- Uniqueness compares exact nonempty values within a workspace, environment, content type, field and language, including delivery fallback for missing translations. Shared fields use one value across languages. Blank optional values are allowed; requiredness still applies at publication.
- REST, GraphQL, RPC, the client and generated types keep string values. The same backend rule covers restoration, scheduling, releases, imports and promotions. A conflict preserves existing content; choose another value or explicitly resolve the conflicting content.
Good practice
- Use stable addresses and review website redirects before publishing an intentional slug change. Leave unique slug fields out of templates; their checkboxes start unchecked.
Avoid
- Do not assume case-insensitive or cross-collection uniqueness: News and news are different. Websites combining models in one route need their own routing policy. Suggestions are not reservations until the backend accepts the save.
Explain fields and validate publication
Help text guides creators; optional field rules prevent a new publication that does not meet your content requirements. Existing values, URLs, published snapshots and history are never rewritten by a schema change.
How to use it
- Open Help & validation on a field in Content types. Add up to 500 characters of plain-text Help text. It appears beside the field in the entry editor; HTML and Markdown are not rendered.
- Check Add publishing validation for Text, Long text, Markdown, Number or Multiple choice. Set at least one rule: minimum/maximum characters for text, inclusive minimum/maximum values for numbers, Minimum selections / Maximum selections for Multiple choice, or Email address / HTTP or HTTPS URL format for Text. Unused bounds stay blank; minimums cannot exceed maximums. Text supports up to 500 characters, Long text/Markdown up to 20,000 and selection counts from 0 to 100.
- Creators can Save draft while configured rules still need corrections. Existing draft type and size checks remain. Optional blank text and empty multiple-choice arrays are allowed; use Required when a value must be present. Selection counts apply to nonempty arrays. Hidden fields and reusable component children still receive backend publication validation.
- Save changes. Stricter rules or newly required fields on existing content open Review publishing rules. Inspect affected draft/published-entry counts by field and language, check the acknowledgement and choose Confirm schema changes. The report includes saved default-language values and authored translations, without exposing private excerpts or entry IDs. Summary counts cover all checked entries; the bounded details table indicates omitted groups.
- Review again after changing the proposal or saved content. The fifteen-minute acknowledgement is bound to your user, workspace/environment, model versions, language settings and current content; changed or revoked access cannot reuse it. Review requires model-update and draft-read access for every enabled language in each affected model. Try review again after a failed check; unsaved schema inputs remain available.
- Edit a reusable component definition to share help and rules across its using models. Tightening its rules reviews the affected models together and applies atomically. Help-only edits and relaxed rules do not need a stricter-rule acknowledgement.
- Correct affected drafts before their next publication. Existing live content stays available; scheduling and releases check current rules when they execute. Import or promotion cannot silently tighten existing target rules: review/apply them in the target Content types first, then retry. Reviewed CLI additions retain optional validation/help metadata but do not edit existing policies or change generated delivery field types. See docs/reference/field-validation.md for portable examples and limits.
Good practice
- Use concise instructions and rules justified by the content itself. Review each environment, coordinate stricter requirements with creators, and check scheduled work. Keep help free of secrets because it is portable schema metadata.
Avoid
- Do not use arbitrary regex/scripts, assume email syntax verifies ownership or a URL rule fetches the website, or treat impact acknowledgement as entry approval. Do not expect the CMS to truncate, repair, republish or unpublish existing values automatically.
Show relevant fields with conditions
Visibility conditions simplify the Studio entry form. They do not change stored content, API fields, permissions or backend validation.
How to use it
- Add a boolean or single-choice field, such as On sale or Product type, and give it a stable API key.
- Open Visibility condition on the field to show conditionally. Check Show this field only when a condition matches, choose a sibling controlling field and its Equals value, then save the content type. For example, show Sale price when On sale is Checked, or Download URL when Product type equals Digital.
- The rule uses one exact comparison. Missing values do not match, even a false comparison. Set a boolean default if new entries should start with a defined state. Chained conditions also require their controlling fields to be visible. Self-references and circular conditions cannot be saved.
- In the entry editor, change the controlling value to show or hide the dependent control. Hidden controls retain saved and unsaved values, including references, media and blocks. Use the Show conditional fields checkbox to inspect or edit them regardless of the rule.
- Required fields still need values before publishing, even when hidden. Errors reveal affected controls; correct the values or ask a developer to review the field's required rule. Hidden references and media still need valid published dependencies.
- Inside a reusable component, rules refer only to sibling fields within the same block. Shared booleans and choices also control translated text fields; edit those controllers in the workspace's default language. Disable the condition checkbox and save to return a field to always visible.
Good practice
- Use conditions for relevance, and reserve Required for values every publication needs. Preview the complete editing workflow before applying new rules to a team.
Avoid
- Do not use visibility to hide confidential data or bypass validation. Published and preview APIs still return the stored field values; consuming applications decide their own rendering. No JavaScript, cross-model expressions or arbitrary formulas are supported.
Reuse components and ordered blocks
Components share field definitions. Single components, component lists and blocks make repeatable sections without duplicating an entire model.
How to use it
- Create a component definition in Content types, such as a call to action or SEO group.
- Add a component, component-list or blocks field to the model and select allowed definitions.
- In an entry, add permitted sections, fill their values and reorder supported lists. Save before previewing.
- Implement every allowed section in the consuming website renderer; unsupported sections need an explicit fallback.
Good practice
- Use a small set of reusable sections whose names describe their editorial purpose.
Avoid
- Allowing a block in the CMS does not automatically create a website component or run arbitrary code.
References and dependency impact
References connect entries; image/file fields connect media. Publishing readiness checks that the final public graph can resolve those dependencies.
How to use it
- Select the allowed reference content type when defining the field.
- Open the picker in the editor to search its paginated candidates. Selected values stay selected across searches and pages.
- Use Where used and reference impact before unpublishing or deleting shared content.
- Publish dependencies first, or include a complete valid set in a coordinated release.
Good practice
- Share authors and common assets through references rather than copying their values.
Avoid
- Do not remove a shared record because only one currently filtered collection appears to use it.