picked 0.0.101 → 0.0.102-next.2

package/docs/reference/management-api/schema/cms-fields.md

@@ -6,43 +6,43 @@ generated: true
 
 # Cms fields schema
 
-The operations and types that `cms-fields.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Types
 
 ### `ContentFieldType`
 
 ```graphql
-"""All Content field kinds supported by the v1 schema editor."""
+"""The kind of a field in a content schema."""
 enum ContentFieldType {
-  """Single-line text input."""
+  """Single-line text."""
   SINGLE_LINE_TEXT
-  """Multi-line text input."""
+  """Multi-line text."""
   MULTI_LINE_TEXT
-  """Markdown-formatted text input."""
+  """Markdown text."""
   MARKDOWN
-  """URL-friendly slug input."""
+  """A URL-safe slug."""
   SLUG
-  """Numeric input (integer or decimal)."""
+  """A number, integer or decimal."""
   NUMBER
-  """Boolean (checkbox / toggle)."""
+  """A true or false value."""
   BOOLEAN
-  """ISO date or date-time input."""
+  """A date, or a date and time."""
   DATE
-  """Free-form JSON value."""
+  """Any JSON value."""
   JSON
-  """Reference to a binary Asset (image, video, document)."""
+  """A reference to an asset."""
   ASSET
-  """Reference to an HTML-document Asset (an uploaded `.html` file)."""
+  """A reference to an HTML asset, an uploaded `.html` file."""
   HTML_ASSET
-  """Hex colour value (`#rrggbb`)."""
+  """A hex colour, `#rrggbb`."""
   COLOR
-  """Embedded `ContentBlock` instance."""
+  """An embedded block instance."""
   CONTENT_BLOCK
-  """Nested group of fields (sub-schema)."""
+  """A group of nested fields."""
   GROUP
   """
-  Reference to one or more other `ContentEntry` rows, optionally constrained to a target `ContentModel`.
+  A reference to another content entry, optionally limited to one target model.
   """
   REFERENCE
 }
@@ -52,16 +52,18 @@ enum ContentFieldType {
 
 ```graphql
 """
-Format hint applied to string-valued single-line text fields. Controls how the editor renders the input and how the value is validated.
+The format of a single-line text value, which sets how the value is checked.
 """
 enum TextFormat {
-  """Plain text — no extra validation."""
+  """Any text."""
   PLAIN
-  """URL — must parse as a URL."""
+  """A URL with the `http` or `https` scheme."""
   URL
-  """Email address — must match RFC-5322 email syntax."""
+  """An email address."""
   EMAIL
-  """Slug — must match `[a-z0-9-]+`."""
+  """
+  A slug. The value is lowercased, and runs of other characters become `-`.
+  """
   SLUG
 }
 ```
@@ -69,11 +71,9 @@ enum TextFormat {
 ### `ContentSchema`
 
 ```graphql
-"""
-A strongly-typed CMS schema — list of field definitions. Used as the value of `ContentModel.schema` and `ContentBlock.schema`.
-"""
+"""The set of fields that a model or a block defines."""
 type ContentSchema {
-  """The field definitions making up the schema."""
+  """The fields of the schema, in order."""
   fields: [ContentFieldDefinition!]!
 }
 ```
@@ -82,24 +82,20 @@ type ContentSchema {
 
 ```graphql
 """
-One field definition inside a Content Schema. Implementations carry the
-per-kind extras (text format, number bounds, content-block category,
-group nested fields). Use `__typename` to discriminate.
+One field in a content schema. Each implementation adds the settings of its kind.
 """
 interface ContentFieldDefinition {
-  """
-  Stable machine identifier — used as the key inside `ContentEntry.data`.
-  """
+  """The key of the field, which names its value in the entry data."""
   key: String!
-  """Human-readable label shown in the editor."""
+  """The label of the field."""
   name: String!
-  """Optional author-facing description of the field's purpose."""
+  """The description of the field. Null when it has none."""
   description: String
-  """Field kind discriminator — also encoded in `__typename`."""
+  """The kind of the field."""
   type: ContentFieldType!
-  """When true, the value is stored as a list."""
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
-  """When true, validation rejects null / missing values."""
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
 }
 ```
@@ -107,21 +103,29 @@ interface ContentFieldDefinition {
 ### `SingleLineTextFieldDefinition`
 
 ```graphql
-"""Single-line text field definition."""
+"""A single-line text field."""
 type SingleLineTextFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
-  """When non-PLAIN, the value must match this format. Default `PLAIN`."""
+  """The format the value must have."""
   format: TextFormat!
-  """Optional anchored regex applied after the format check."""
+  """
+  A regular expression the whole value must match, checked after the format. Null for none.
+  """
   pattern: String
-  """Minimum number of characters (inclusive)."""
+  """The fewest characters allowed. Null for no minimum."""
   minLength: Int
-  """Maximum number of characters (inclusive)."""
+  """The most characters allowed. Null for no maximum."""
   maxLength: Int
 }
 ```
@@ -129,17 +133,23 @@ type SingleLineTextFieldDefinition implements ContentFieldDefinition {
 ### `MultiLineTextFieldDefinition`
 
 ```graphql
-"""Multi-line text field definition."""
+"""A multi-line text field."""
 type MultiLineTextFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
-  """Minimum number of characters (inclusive)."""
+  """The fewest characters allowed. Null for no minimum."""
   minLength: Int
-  """Maximum number of characters (inclusive)."""
+  """The most characters allowed. Null for no maximum."""
   maxLength: Int
 }
 ```
@@ -147,13 +157,19 @@ type MultiLineTextFieldDefinition implements ContentFieldDefinition {
 ### `MarkdownFieldDefinition`
 
 ```graphql
-"""Markdown field definition. No per-kind extras."""
+"""A Markdown field."""
 type MarkdownFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
 }
 ```
@@ -161,15 +177,23 @@ type MarkdownFieldDefinition implements ContentFieldDefinition {
 ### `SlugFieldDefinition`
 
 ```graphql
-"""Slug field definition. Slugs may optionally derive from another field."""
+"""A slug field."""
 type SlugFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
-  """When set, the slug derives from another field's value (e.g. `title`)."""
+  """
+  The key of the field the slug derives from, such as `title`. Null when it derives from none.
+  """
   derivedFromKey: String
 }
 ```
@@ -177,19 +201,25 @@ type SlugFieldDefinition implements ContentFieldDefinition {
 ### `NumberFieldDefinition`
 
 ```graphql
-"""Number field definition."""
+"""A number field."""
 type NumberFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
-  """Minimum value (inclusive)."""
+  """The lowest value allowed. Null for no minimum."""
   min: Float
-  """Maximum value (inclusive)."""
+  """The highest value allowed. Null for no maximum."""
   max: Float
-  """When true, the value must be an integer."""
+  """Whether the value must be an integer."""
   integerOnly: Boolean!
 }
 ```
@@ -197,13 +227,19 @@ type NumberFieldDefinition implements ContentFieldDefinition {
 ### `BooleanFieldDefinition`
 
 ```graphql
-"""Boolean field definition. No per-kind extras."""
+"""A boolean field."""
 type BooleanFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
 }
 ```
@@ -211,17 +247,21 @@ type BooleanFieldDefinition implements ContentFieldDefinition {
 ### `DateFieldDefinition`
 
 ```graphql
-"""Date field definition. Optionally includes the time component."""
+"""A date field."""
 type DateFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
-  """
-  When true, the value carries both date and time. When false, time is stripped.
-  """
+  """Whether the value holds a time as well as a date."""
   includeTime: Boolean!
 }
 ```
@@ -229,13 +269,19 @@ type DateFieldDefinition implements ContentFieldDefinition {
 ### `JsonFieldDefinition`
 
 ```graphql
-"""JSON field definition — escape hatch for unstructured shapes."""
+"""A JSON field, for values with no fixed shape."""
 type JsonFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
 }
 ```
@@ -244,30 +290,42 @@ type JsonFieldDefinition implements ContentFieldDefinition {
 
 ```graphql
 """
-Asset field definition. Restricts which Assets can be referenced by MIME, size, and (for images) intrinsic dimensions.
+An asset field, with optional limits on the MIME type, size and image dimensions of the asset.
 """
 type AssetFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
   """
-  Allowlist of accepted MIME types (e.g. `["image/png", "image/jpeg"]`). When set, the codec rejects assets whose `mimeType` is not in the list.
+  The MIME types the asset may have, such as `["image/png", "image/jpeg"]`. Null for any.
   """
   acceptedMimeTypes: [String!]
-  """Maximum file size in bytes. The codec rejects assets larger than this."""
+  """The largest file size allowed, in bytes. Null for no limit."""
   maxBytes: Int
   """
-  Image-only: minimum width in pixels. Applied when the asset's MIME type begins with `image/`.
+  The smallest image width allowed, in pixels. Applies to images only. Null for no limit.
   """
   minWidth: Int
-  """Image-only: maximum width in pixels."""
+  """
+  The largest image width allowed, in pixels. Applies to images only. Null for no limit.
+  """
   maxWidth: Int
-  """Image-only: minimum height in pixels."""
+  """
+  The smallest image height allowed, in pixels. Applies to images only. Null for no limit.
+  """
   minHeight: Int
-  """Image-only: maximum height in pixels."""
+  """
+  The largest image height allowed, in pixels. Applies to images only. Null for no limit.
+  """
   maxHeight: Int
 }
 ```
@@ -276,16 +334,22 @@ type AssetFieldDefinition implements ContentFieldDefinition {
 
 ```graphql
 """
-HTML-asset field definition. Like `AssetFieldDefinition` but the referenced Asset is always an uploaded `.html` file (`text/html`); only the file-size cap is author-configurable.
+An HTML asset field, which accepts only an uploaded `.html` file (`text/html`).
 """
 type HtmlAssetFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
-  """Maximum file size in bytes. The codec rejects assets larger than this."""
+  """The largest file size allowed, in bytes. Null for no limit."""
   maxBytes: Int
 }
 ```
@@ -293,13 +357,19 @@ type HtmlAssetFieldDefinition implements ContentFieldDefinition {
 ### `ColorFieldDefinition`
 
 ```graphql
-"""Color field definition. Values are lowercase hex with leading `#`."""
+"""A colour field. Values are lowercase hex with a leading `#`."""
 type ColorFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
 }
 ```
@@ -307,18 +377,22 @@ type ColorFieldDefinition implements ContentFieldDefinition {
 ### `ContentBlockFieldDefinition`
 
 ```graphql
-"""
-Content Block field definition — embeds Block instances of the configured category.
-"""
+"""A block field, which embeds block instances."""
 type ContentBlockFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
   """
-  The Content Block category whose Blocks may be embedded here. Null means any category may be embedded.
+  The category of block the field accepts. Null when it accepts any category.
   """
   contentBlockCategory: ContentBlockCategory
 }
@@ -327,17 +401,21 @@ type ContentBlockFieldDefinition implements ContentFieldDefinition {
 ### `GroupFieldDefinition`
 
 ```graphql
-"""Group field definition — nests a sub-schema."""
+"""A group field, which nests a set of fields."""
 type GroupFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
-  """
-  Nested field definitions (max nesting depth 3 enforced by the validator).
-  """
+  """The nested fields. Groups nest at most three levels deep."""
   nestedFields: [ContentFieldDefinition!]!
 }
 ```
@@ -345,18 +423,22 @@ type GroupFieldDefinition implements ContentFieldDefinition {
 ### `ReferenceFieldDefinition`
 
 ```graphql
-"""
-Reference field definition — points at one or more other Content Entries.
-"""
+"""A reference field, which points at other content entries."""
 type ReferenceFieldDefinition implements ContentFieldDefinition {
+  """The key of the field, which names its value in the entry data."""
   key: String!
+  """The label of the field."""
   name: String!
+  """The description of the field. Null when it has none."""
   description: String
+  """The kind of the field."""
   type: ContentFieldType!
+  """Whether the field holds a list of values."""
   repeatable: Boolean!
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean!
   """
-  The target Content Model `key` whose entries may be referenced. Null means any Content Model in the workspace may be referenced.
+  The key of the target model. Null when entries of any model in the workspace are accepted.
   """
   contentModelKey: String
 }
@@ -366,12 +448,11 @@ type ReferenceFieldDefinition implements ContentFieldDefinition {
 
 ```graphql
 """
-Strongly-typed Content Entry data. Reused as the body of `GroupFieldValue` and `EmbeddedContentBlock` (same shape, different nesting position).
+The values of a content entry, typed by its schema. Group values and embedded blocks hold the same
+shape.
 """
 type ContentEntryData {
-  """
-  The values keyed by field key — order matches the parent schema's `fields`.
-  """
+  """The values, one per field, in the order of the schema's fields."""
   values: [ContentFieldValue!]!
 }
 ```
@@ -380,14 +461,13 @@ type ContentEntryData {
 
 ```graphql
 """
-One value inside a Content Entry. The `__typename` discriminates the
-kind; the corresponding singular / plural field carries the value
-(singular when the parent field is not repeatable, plural otherwise).
+One value in a content entry. The singular member holds the value when the field is not
+repeatable, and the plural member when it is.
 """
 interface ContentFieldValue {
-  """The field key from the parent schema."""
+  """The key of the field in the schema."""
   key: String!
-  """Field kind discriminator — also encoded in `__typename`."""
+  """The kind of the field."""
   type: ContentFieldType!
 }
 ```
@@ -395,13 +475,15 @@ interface ContentFieldValue {
 ### `SingleLineTextFieldValue`
 
 ```graphql
-"""Single-line text value."""
+"""A single-line text value."""
 type SingleLineTextFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular value when the field is not repeatable."""
+  """The value. Null when the field is repeatable or has no value."""
   text: String
-  """Plural values when the field is repeatable."""
+  """The values. Null when the field is not repeatable."""
   texts: [String!]
 }
 ```
@@ -409,13 +491,15 @@ type SingleLineTextFieldValue implements ContentFieldValue {
 ### `MultiLineTextFieldValue`
 
 ```graphql
-"""Multi-line text value."""
+"""A multi-line text value."""
 type MultiLineTextFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular value when the field is not repeatable."""
+  """The value. Null when the field is repeatable or has no value."""
   text: String
-  """Plural values when the field is repeatable."""
+  """The values. Null when the field is not repeatable."""
   texts: [String!]
 }
 ```
@@ -423,13 +507,15 @@ type MultiLineTextFieldValue implements ContentFieldValue {
 ### `MarkdownFieldValue`
 
 ```graphql
-"""Markdown value."""
+"""A Markdown value."""
 type MarkdownFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular value when the field is not repeatable."""
+  """The value. Null when the field is repeatable or has no value."""
   markdown: String
-  """Plural values when the field is repeatable."""
+  """The values. Null when the field is not repeatable."""
   markdowns: [String!]
 }
 ```
@@ -437,13 +523,15 @@ type MarkdownFieldValue implements ContentFieldValue {
 ### `SlugFieldValue`
 
 ```graphql
-"""Slug value."""
+"""A slug value."""
 type SlugFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular value when the field is not repeatable."""
+  """The value. Null when the field is repeatable or has no value."""
   slug: String
-  """Plural values when the field is repeatable."""
+  """The values. Null when the field is not repeatable."""
   slugs: [String!]
 }
 ```
@@ -451,13 +539,15 @@ type SlugFieldValue implements ContentFieldValue {
 ### `NumberFieldValue`
 
 ```graphql
-"""Number value."""
+"""A number value."""
 type NumberFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular value when the field is not repeatable."""
+  """The value. Null when the field is repeatable or has no value."""
   number: Float
-  """Plural values when the field is repeatable."""
+  """The values. Null when the field is not repeatable."""
   numbers: [Float!]
 }
 ```
@@ -465,13 +555,15 @@ type NumberFieldValue implements ContentFieldValue {
 ### `BooleanFieldValue`
 
 ```graphql
-"""Boolean value."""
+"""A boolean value."""
 type BooleanFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular value when the field is not repeatable."""
+  """The value. Null when the field is repeatable or has no value."""
   boolean: Boolean
-  """Plural values when the field is repeatable."""
+  """The values. Null when the field is not repeatable."""
   booleans: [Boolean!]
 }
 ```
@@ -479,13 +571,15 @@ type BooleanFieldValue implements ContentFieldValue {
 ### `DateFieldValue`
 
 ```graphql
-"""Date / date-time value."""
+"""A date value."""
 type DateFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular value when the field is not repeatable."""
+  """The value. Null when the field is repeatable or has no value."""
   date: IsoDate
-  """Plural values when the field is repeatable."""
+  """The values. Null when the field is not repeatable."""
   dates: [IsoDate!]
 }
 ```
@@ -493,13 +587,15 @@ type DateFieldValue implements ContentFieldValue {
 ### `JsonFieldValue`
 
 ```graphql
-"""JSON value — escape hatch preserved as-is."""
+"""A JSON value, stored as given."""
 type JsonFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular JSON value when the field is not repeatable."""
+  """The value. Null when the field is repeatable or has no value."""
   json: JSON
-  """Plural JSON values when the field is repeatable."""
+  """The values. Null when the field is not repeatable."""
   jsons: [JSON!]
 }
 ```
@@ -508,17 +604,17 @@ type JsonFieldValue implements ContentFieldValue {
 
 ```graphql
 """
-An asset reference resolved to the specific version it is pinned to (or its
-oldest-version fallback for a legacy reference).
+A reference to an asset, resolved to the version it pins, or to the asset's oldest version when it
+pins none.
 """
 type AssetRef {
   """
-  The referenced Asset. Its top-level byte fields reflect the CURRENT version;
-  read `version` for the pinned version's bytes.
+  The referenced asset. Its own file fields describe its current version; `version` describes the
+  pinned one.
   """
   asset: Asset!
   """
-  The pinned (or oldest-fallback) version. Null only on a version loader miss.
+  The version the reference resolves to. Null when that version cannot be found.
   """
   version: AssetVersion
 }
@@ -527,13 +623,17 @@ type AssetRef {
 ### `AssetFieldValue`
 
 ```graphql
-"""Asset reference value."""
+"""An asset value."""
 type AssetFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular Asset reference when the field is not repeatable."""
+  """
+  The asset reference. Null when the field is repeatable or has no value.
+  """
   assetRef: AssetRef
-  """Plural Asset references when the field is repeatable."""
+  """The asset references. Null when the field is not repeatable."""
   assetRefs: [AssetRef!]
 }
 ```
@@ -541,15 +641,17 @@ type AssetFieldValue implements ContentFieldValue {
 ### `HtmlAssetFieldValue`
 
 ```graphql
-"""
-HTML-asset reference value. Carries the same resolved `Asset` as `AssetFieldValue`; distinct `__typename` so the field kind round-trips.
-"""
+"""An HTML asset value."""
 type HtmlAssetFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular Asset reference when the field is not repeatable."""
+  """
+  The asset reference. Null when the field is repeatable or has no value.
+  """
   assetRef: AssetRef
-  """Plural Asset references when the field is repeatable."""
+  """The asset references. Null when the field is not repeatable."""
   assetRefs: [AssetRef!]
 }
 ```
@@ -557,15 +659,18 @@ type HtmlAssetFieldValue implements ContentFieldValue {
 ### `ColorFieldValue`
 
 ```graphql
-"""Color value."""
+"""A colour value."""
 type ColorFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
   """
-  Singular color value — lowercase hex with leading `#` (e.g. `#ff0000`).
+  The colour, lowercase hex with a leading `#`, such as `#ff0000`. Null when the field is repeatable
+  or has no value.
   """
   color: String
-  """Plural color values."""
+  """The colours. Null when the field is not repeatable."""
   colors: [String!]
 }
 ```
@@ -573,13 +678,15 @@ type ColorFieldValue implements ContentFieldValue {
 ### `ContentBlockFieldValue`
 
 ```graphql
-"""Embedded Content Block value."""
+"""An embedded block value."""
 type ContentBlockFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular embedded block when the field is not repeatable."""
+  """The embedded block. Null when the field is repeatable or has no value."""
   block: EmbeddedContentBlock
-  """Plural embedded blocks when the field is repeatable."""
+  """The embedded blocks. Null when the field is not repeatable."""
   blocks: [EmbeddedContentBlock!]
 }
 ```
@@ -587,13 +694,17 @@ type ContentBlockFieldValue implements ContentFieldValue {
 ### `GroupFieldValue`
 
 ```graphql
-"""Nested group value — carries a sub-shaped `ContentEntryData`."""
+"""A group value."""
 type GroupFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular nested group value when the field is not repeatable."""
+  """
+  The values of the group. Null when the field is repeatable or has no value.
+  """
   group: ContentEntryData
-  """Plural nested group values when the field is repeatable."""
+  """The values of each group. Null when the field is not repeatable."""
   groups: [ContentEntryData!]
 }
 ```
@@ -602,12 +713,12 @@ type GroupFieldValue implements ContentFieldValue {
 
 ```graphql
 """
-A Content Block instance embedded inside a Content Entry. Pairs the referenced Block (which carries the schema) with its data.
+A block instance inside a content entry: the block, which carries the schema, and its values.
 """
 type EmbeddedContentBlock {
-  """The referenced Content Block — resolves the schema and category."""
+  """The embedded block."""
   contentBlock: ContentBlock!
-  """Block-shaped data, recursively typed."""
+  """The values of the instance, typed by the block's schema."""
   data: ContentEntryData!
 }
 ```
@@ -615,13 +726,18 @@ type EmbeddedContentBlock {
 ### `ReferenceFieldValue`
 
 ```graphql
-"""Reference value — resolves the referenced Content Entry/Entries."""
+"""A reference value."""
 type ReferenceFieldValue implements ContentFieldValue {
+  """The key of the field in the schema."""
   key: String!
+  """The kind of the field."""
   type: ContentFieldType!
-  """Singular referenced Content Entry when the field is not repeatable."""
+  """
+  The referenced content entry. Null when the field is repeatable, has no value, or names a missing
+  entry.
+  """
   contentEntry: ContentEntry
-  """Plural referenced Content Entries when the field is repeatable."""
+  """The referenced content entries. Null when the field is not repeatable."""
   contentEntries: [ContentEntry!]
 }
 ```
@@ -629,9 +745,9 @@ type ReferenceFieldValue implements ContentFieldValue {
 ### `ContentSchemaInput`
 
 ```graphql
-"""A schema input — list of field definitions."""
+"""The fields of a content schema."""
 input ContentSchemaInput {
-  """The field definitions making up the schema."""
+  """The fields of the schema, in order."""
   fields: [ContentFieldDefinitionInput!]!
 }
 ```
@@ -640,46 +756,47 @@ input ContentSchemaInput {
 
 ```graphql
 """
-One field-definition input. Exactly one of the field-kind sub-inputs (`singleLineText`, `number`, `contentBlock`, …) must be set; the resolver rejects with INVALID_INPUT otherwise.
+One field in a content schema. Set exactly one kind input, such as `singleLineText` or `number`;
+any other count fails with `INVALID_INPUT`.
 """
 input ContentFieldDefinitionInput {
-  """Stable machine identifier."""
+  """The key of the field, which names its value in the entry data."""
   key: String!
-  """Human-readable label."""
+  """The label of the field."""
   name: String!
-  """Optional author-facing description of the field's purpose."""
+  """The description of the field."""
   description: String
-  """When true, the value is stored as a list."""
+  """Whether the field holds a list of values."""
   repeatable: Boolean = false
-  """When true, validation rejects null / missing values."""
+  """Whether a filled content entry must hold a value for the field."""
   required: Boolean = false
-  """Single-line text sub-input."""
+  """The settings of a single-line text field."""
   singleLineText: SingleLineTextFieldInput
-  """Multi-line text sub-input."""
+  """The settings of a multi-line text field."""
   multiLineText: MultiLineTextFieldInput
-  """Markdown sub-input."""
+  """Makes the field a Markdown field."""
   markdown: MarkdownFieldInput
-  """Slug sub-input."""
+  """The settings of a slug field."""
   slug: SlugFieldInput
-  """Number sub-input."""
+  """The settings of a number field."""
   number: NumberFieldInput
-  """Boolean sub-input."""
+  """Makes the field a boolean field."""
   boolean: BooleanFieldInput
-  """Date sub-input."""
+  """The settings of a date field."""
   date: DateFieldInput
-  """JSON sub-input."""
+  """Makes the field a JSON field."""
   json: JsonFieldInput
-  """Asset sub-input."""
+  """The settings of an asset field."""
   asset: AssetFieldInput
-  """HTML-asset sub-input."""
+  """The settings of an HTML asset field."""
   htmlAsset: HtmlAssetFieldInput
-  """Color sub-input."""
+  """Makes the field a colour field."""
   color: ColorFieldInput
-  """Content Block sub-input."""
+  """The settings of a block field."""
   contentBlock: ContentBlockFieldInput
-  """Group sub-input."""
+  """The settings of a group field."""
   group: GroupFieldInput
-  """Reference sub-input."""
+  """The settings of a reference field."""
   reference: ReferenceFieldInput
 }
 ```
@@ -687,17 +804,17 @@ input ContentFieldDefinitionInput {
 ### `SingleLineTextFieldInput`
 
 ```graphql
-"""Per-kind input for `SINGLE_LINE_TEXT` fields."""
+"""The settings of a `SINGLE_LINE_TEXT` field."""
 input SingleLineTextFieldInput {
+  """The format the value must have."""
+  format: TextFormat = PLAIN
   """
-  Format hint — controls editor rendering and validation. Default `PLAIN`.
+  A regular expression the whole value must match, checked after the format.
   """
-  format: TextFormat = PLAIN
-  """Optional anchored regex applied after the format check."""
   pattern: String
-  """Minimum length (inclusive)."""
+  """The fewest characters allowed."""
   minLength: Int
-  """Maximum length (inclusive)."""
+  """The most characters allowed."""
   maxLength: Int
 }
 ```
@@ -705,11 +822,11 @@ input SingleLineTextFieldInput {
 ### `MultiLineTextFieldInput`
 
 ```graphql
-"""Per-kind input for `MULTI_LINE_TEXT` fields."""
+"""The settings of a `MULTI_LINE_TEXT` field."""
 input MultiLineTextFieldInput {
-  """Minimum length (inclusive)."""
+  """The fewest characters allowed."""
   minLength: Int
-  """Maximum length (inclusive)."""
+  """The most characters allowed."""
   maxLength: Int
 }
 ```
@@ -717,11 +834,9 @@ input MultiLineTextFieldInput {
 ### `MarkdownFieldInput`
 
 ```graphql
-"""
-Marker input — `MARKDOWN` field has no extras. Presence alone discriminates the field kind.
-"""
+"""Marks a `MARKDOWN` field, which has no settings."""
 input MarkdownFieldInput {
-  """Unused — required so the input is non-empty."""
+  """Unused."""
   _: Boolean
 }
 ```
@@ -729,9 +844,9 @@ input MarkdownFieldInput {
 ### `SlugFieldInput`
 
 ```graphql
-"""Per-kind input for `SLUG` fields."""
+"""The settings of a `SLUG` field."""
 input SlugFieldInput {
-  """When set, the slug derives from another field's value."""
+  """The key of the field the slug derives from."""
   derivedFromKey: String
 }
 ```
@@ -739,13 +854,13 @@ input SlugFieldInput {
 ### `NumberFieldInput`
 
 ```graphql
-"""Per-kind input for `NUMBER` fields."""
+"""The settings of a `NUMBER` field."""
 input NumberFieldInput {
-  """Minimum value (inclusive)."""
+  """The lowest value allowed."""
   min: Float
-  """Maximum value (inclusive)."""
+  """The highest value allowed."""
   max: Float
-  """When true, the value must be an integer. Default `false`."""
+  """Whether the value must be an integer."""
   integerOnly: Boolean = false
 }
 ```
@@ -753,9 +868,9 @@ input NumberFieldInput {
 ### `BooleanFieldInput`
 
 ```graphql
-"""Marker input — `BOOLEAN` field has no extras."""
+"""Marks a `BOOLEAN` field, which has no settings."""
 input BooleanFieldInput {
-  """Unused — required so the input is non-empty."""
+  """Unused."""
   _: Boolean
 }
 ```
@@ -763,9 +878,9 @@ input BooleanFieldInput {
 ### `DateFieldInput`
 
 ```graphql
-"""Per-kind input for `DATE` fields."""
+"""The settings of a `DATE` field."""
 input DateFieldInput {
-  """When true, the value carries both date and time. Default `false`."""
+  """Whether the value holds a time as well as a date."""
   includeTime: Boolean = false
 }
 ```
@@ -773,9 +888,9 @@ input DateFieldInput {
 ### `JsonFieldInput`
 
 ```graphql
-"""Marker input — `JSON` field has no extras."""
+"""Marks a `JSON` field, which has no settings."""
 input JsonFieldInput {
-  """Unused — required so the input is non-empty."""
+  """Unused."""
   _: Boolean
 }
 ```
@@ -783,23 +898,21 @@ input JsonFieldInput {
 ### `AssetFieldInput`
 
 ```graphql
-"""
-Per-asset-field constraints applied by the codec at data-decode time. All fields are optional; an empty input behaves as a plain `asset` field.
-"""
+"""The limits of an `ASSET` field. Every limit is optional."""
 input AssetFieldInput {
   """
-  Allowlist of accepted MIME types. When set and non-empty, the asset's `mimeType` must be in the list.
+  The MIME types the asset may have. Omit it, or pass an empty list, to accept any.
   """
   acceptedMimeTypes: [String!]
-  """Maximum file size in bytes."""
+  """The largest file size allowed, in bytes."""
   maxBytes: Int
-  """Image-only: minimum width in pixels."""
+  """The smallest image width allowed, in pixels."""
   minWidth: Int
-  """Image-only: maximum width in pixels."""
+  """The largest image width allowed, in pixels."""
   maxWidth: Int
-  """Image-only: minimum height in pixels."""
+  """The smallest image height allowed, in pixels."""
   minHeight: Int
-  """Image-only: maximum height in pixels."""
+  """The largest image height allowed, in pixels."""
   maxHeight: Int
 }
 ```
@@ -808,10 +921,10 @@ input AssetFieldInput {
 
 ```graphql
 """
-Per-html-asset-field constraints applied by the codec at data-decode time. The accepted MIME type is always locked to `text/html`; only the size cap is configurable.
+The limits of an `HTML_ASSET` field. The MIME type is always `text/html`.
 """
 input HtmlAssetFieldInput {
-  """Maximum file size in bytes."""
+  """The largest file size allowed, in bytes."""
   maxBytes: Int
 }
 ```
@@ -819,9 +932,9 @@ input HtmlAssetFieldInput {
 ### `ColorFieldInput`
 
 ```graphql
-"""Marker input — `COLOR` field has no extras."""
+"""Marks a `COLOR` field, which has no settings."""
 input ColorFieldInput {
-  """Unused — required so the input is non-empty."""
+  """Unused."""
   _: Boolean
 }
 ```
@@ -829,15 +942,12 @@ input ColorFieldInput {
 ### `AssetRefInput`
 
 ```graphql
-"""
-A CMS asset reference for a content-field value input, with an optional pinned version.
-Omit `versionId` to store a legacy reference (reads back as the asset's oldest version).
-"""
+"""A reference to an asset in a content entry value."""
 input AssetRefInput {
-  """The referenced Asset id."""
+  """The ID of the asset."""
   assetId: ID!
   """
-  The pinned AssetVersion id. Omitting it persists a legacy `{ id }`-only reference, which reads back as the asset's oldest version; the dashboard AssetInput always sets it.
+  The ID of the version to pin. Omit it to pin the asset's current version.
   """
   versionId: ID
 }
@@ -846,10 +956,10 @@ input AssetRefInput {
 ### `ContentBlockFieldInput`
 
 ```graphql
-"""Per-kind input for `CONTENT_BLOCK` fields."""
+"""The settings of a `CONTENT_BLOCK` field."""
 input ContentBlockFieldInput {
   """
-  The Content Block category whose Blocks may be embedded here. Omit (null) to allow any category.
+  The category of block the field accepts. Omit it to accept any category.
   """
   contentBlockCategory: ContentBlockCategory
 }
@@ -858,9 +968,9 @@ input ContentBlockFieldInput {
 ### `GroupFieldInput`
 
 ```graphql
-"""Per-kind input for `GROUP` fields."""
+"""The settings of a `GROUP` field."""
 input GroupFieldInput {
-  """Nested field definitions (max nesting depth 3 enforced by validator)."""
+  """The nested fields. Groups nest at most three levels deep."""
   nestedFields: [ContentFieldDefinitionInput!]!
 }
 ```
@@ -868,11 +978,9 @@ input GroupFieldInput {
 ### `ReferenceFieldInput`
 
 ```graphql
-"""Per-kind input for `REFERENCE` fields."""
+"""The settings of a `REFERENCE` field."""
 input ReferenceFieldInput {
-  """
-  The target Content Model `key` whose entries may be referenced. Omit to allow any Content Model.
-  """
+  """The key of the target model. Omit it to accept entries of any model."""
   contentModelKey: String
 }
 ```
@@ -880,11 +988,9 @@ input ReferenceFieldInput {
 ### `ContentEntryDataInput`
 
 ```graphql
-"""
-A Content Entry data input — list of field values keyed by field key. Reused for nested groups and embedded Content Blocks.
-"""
+"""The values of a content entry, a group, or an embedded block."""
 input ContentEntryDataInput {
-  """The values keyed by field key."""
+  """The values, one per field."""
   values: [ContentFieldValueInput!]!
 }
 ```
@@ -893,48 +999,47 @@ input ContentEntryDataInput {
 
 ```graphql
 """
-One field-value input. The resolver matches the populated singular /
-plural pair against the parent schema's field type for `key`. Setting
-more than one populated pair is rejected with `INVALID_INPUT`.
+One value in a content entry. Set the member that matches the field's type: singular when the
+field is not repeatable, plural when it is. Markdown, slug and colour fields take `text`.
 """
 input ContentFieldValueInput {
-  """The field key from the parent schema."""
+  """The key of the field in the schema."""
   key: String!
-  """Singular text value."""
+  """A text value."""
   text: String
-  """Plural text values."""
+  """Text values."""
   texts: [String!]
-  """Singular number value."""
+  """A number value."""
   number: Float
-  """Plural number values."""
+  """Number values."""
   numbers: [Float!]
-  """Singular boolean value."""
+  """A boolean value."""
   boolean: Boolean
-  """Plural boolean values."""
+  """Boolean values."""
   booleans: [Boolean!]
-  """Singular date value."""
+  """A date value."""
   date: IsoDate
-  """Plural date values."""
+  """Date values."""
   dates: [IsoDate!]
-  """Singular JSON value."""
+  """A JSON value."""
   json: JSON
-  """Plural JSON values."""
+  """JSON values."""
   jsons: [JSON!]
-  """Singular Asset reference."""
+  """An asset reference."""
   assetRef: AssetRefInput
-  """Plural Asset references."""
+  """Asset references."""
   assetRefs: [AssetRefInput!]
-  """Singular embedded Content Block."""
+  """An embedded block."""
   block: EmbeddedContentBlockInput
-  """Plural embedded Content Blocks."""
+  """Embedded blocks."""
   blocks: [EmbeddedContentBlockInput!]
-  """Singular nested group value."""
+  """The values of a group."""
   group: ContentEntryDataInput
-  """Plural nested group values."""
+  """The values of each group."""
   groups: [ContentEntryDataInput!]
-  """Singular referenced Content Entry id."""
+  """The ID of a referenced content entry."""
   contentEntryId: ID
-  """Plural referenced Content Entry ids."""
+  """The IDs of referenced content entries."""
   contentEntryIds: [ID!]
 }
 ```
@@ -942,13 +1047,11 @@ input ContentFieldValueInput {
 ### `EmbeddedContentBlockInput`
 
 ```graphql
-"""
-Input form of `EmbeddedContentBlock` — references a Content Block by id and supplies the block-shaped data.
-"""
+"""A block instance in a content entry value."""
 input EmbeddedContentBlockInput {
-  """The Content Block id to embed."""
+  """The ID of the block to embed."""
   contentBlockId: ID!
-  """Block-shaped data, recursively typed."""
+  """The values of the instance, typed by the block's schema."""
   data: ContentEntryDataInput!
 }
 ```