picked 0.0.101 → 0.0.102-next.2

package/docs/reference/management-api/schema/field.md

@@ -6,13 +6,14 @@ generated: true
 
 # Field schema
 
-The operations and types that `field.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.
 
 ## Queries
 
 ### `field`
 
-Get a field by ID within a workspace.
+Reads a field.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 field(id: ID!, workspaceId: ID!): Field @auth
@@ -20,7 +21,9 @@ field(id: ID!, workspaceId: ID!): Field @auth
 
 ### `fields`
 
-Get list of fields within a workspace.
+Lists the fields in a workspace. `search` matches a case-insensitive substring of the name;
+`sortKey` and `reverse` set the order.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 fields(
@@ -33,7 +36,7 @@ fields(
   sortKey: FieldSortKeys = NAME
   reverse: Boolean = false
   """
-  Restrict the listing to the fields attached to this step. Search, sort and paging still apply; `totalCount` counts the step.
+  Only the fields on this step. `totalCount` then counts that step's fields.
   """
   stepId: ID
 ): FieldConnection! @auth
@@ -43,7 +46,8 @@ fields(
 
 ### `fieldCreate`
 
-Create a new field. Requires scope: `ORGANIZATION_PROJECTS_CREATE`.
+Creates a field in a workspace.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 fieldCreate(input: FieldCreateInput!): FieldCreatePayload! @auth
@@ -51,7 +55,8 @@ fieldCreate(input: FieldCreateInput!): FieldCreatePayload! @auth
 
 ### `fieldUpdate`
 
-Update a field. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates a field.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 fieldUpdate(input: FieldUpdateInput!): FieldUpdatePayload! @auth
@@ -59,7 +64,9 @@ fieldUpdate(input: FieldUpdateInput!): FieldUpdatePayload! @auth
 
 ### `fieldDelete`
 
-Delete a field. Requires scope: `ORGANIZATION_PROJECTS_DELETE`.
+Deletes a field. A field that is on a step is not deleted, and comes back as an `IN_USE` user
+error.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 fieldDelete(input: FieldDeleteInput!): FieldDeletePayload! @auth
@@ -70,15 +77,15 @@ fieldDelete(input: FieldDeleteInput!): FieldDeletePayload! @auth
 ### `FieldType`
 
 ```graphql
-"""Field type — what kind of value the field captures."""
+"""The kinds of value a field captures."""
 enum FieldType {
-  """Plain text input."""
+  """Text."""
   TEXT
-  """Numeric input."""
+  """A number."""
   NUMBER
-  """Boolean (checkbox/toggle)."""
+  """True or false, as a checkbox or toggle."""
   BOOLEAN
-  """Free-form JSON structure (the SDK plugin renders an editor)."""
+  """A JSON value."""
   OBJECT
 }
 ```
@@ -87,64 +94,55 @@ enum FieldType {
 
 ```graphql
 """
-A form field within a workspace. Reused across steps via `Step.fields`.
-Defines the input control's type, label, validation rules, default
-value, and any select-style options.
-
-`validation`, `defaultValue`, `condition`, and `options` are JSON blobs
-whose shapes depend on `type` — see the field-create / field-update
-mutations for the canonical shapes.
+A data input inside a step, such as a name, an email address or a choice. A field belongs to the
+workspace and can sit on more than one step.
 """
 type Field {
-  """Unique field identifier."""
+  """The ID of the field."""
   id: ID!
-  """
-  Stable machine-readable name (used to key the value in the captured payload).
-  """
+  """The machine-readable name of the field."""
   name: String!
-  """Stable, human-readable key for SDK consumers."""
+  """The stable identifier of the field, unique within its workspace."""
   key: String!
-  """Human-readable label shown to end-users next to the input."""
+  """The label shown next to the input."""
   label: String!
   """The kind of value the field captures."""
   type: FieldType!
-  """
-  Whether multiple values are allowed (renders as a multi-select / repeating input).
-  """
+  """Whether the field accepts more than one value."""
   multiple: Boolean!
-  """Whether the field is required."""
+  """Whether the visitor must answer the field."""
   required: Boolean!
-  """JSON validation rules (shape depends on `type`)."""
+  """The validation rules, as JSON. Null when none are set."""
   validation: JSON
   """
-  Selectable options when the field is a single/multi-select (shape: `{ label, value, ... }`).
+  The choices of a field with a fixed set of choices. Null when the field has none.
   """
   options: [FieldOption!]
   """
-  JSON condition controlling whether the field is rendered (JSON Logic AST).
+  A JSON Logic rule that decides whether the field renders. Null when none is set.
   """
   condition: JSON
-  """JSON default value (shape depends on `type`)."""
+  """The value the field starts with. Null when none is set."""
   defaultValue: JSON
-  """Placeholder text rendered inside the input when empty."""
+  """The text shown in the empty input. Null when none is set."""
   placeholder: String
-  """Field description shown alongside the label."""
+  """A description shown with the label. Null when none is set."""
   description: String
-  """Help text rendered below the field as a hint."""
+  """A hint shown below the field. Null when none is set."""
   helpText: String
-  """When true, the captured value is excluded from analytics tracking."""
+  """Whether the answer is left out of analytics."""
   doNotTrack: Boolean!
-  """When true, the captured value is excluded from persistence."""
+  """Whether the answer is left out of storage."""
   doNotStore: Boolean!
-  """The list of steps this field belongs to."""
+  """The steps the field is on."""
   steps: StepConnection!
-  """The workspace this field belongs to."""
+  """The workspace the field belongs to."""
   workspace: Workspace!
-  """The workspace ID this field belongs to."""
+  """The ID of the workspace the field belongs to."""
   workspaceId: ID!
-  """When this field was created."""
+  """When the field was created."""
   createdAt: DateTime!
-  """When this field was last updated."""
+  """When the field last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -152,21 +150,19 @@ type Field {
 ### `FieldOption`
 
 ```graphql
-"""
-A single selectable option within a field (only meaningful for select-style fields).
-"""
+"""One choice in a field that has a fixed set of choices."""
 type FieldOption {
-  """Stable option identifier."""
+  """The ID of the option."""
   id: ID!
-  """Human-readable label shown to end-users."""
+  """The label shown for the option."""
   label: String!
-  """Optional description shown alongside the label."""
+  """A description shown with the label. Null when none is set."""
   description: String
+  """The value the field captures when the visitor picks the option."""
+  value: JSON!
   """
-  The option's machine value (becomes the field's captured value when selected).
+  A JSON Logic rule that decides whether the option renders. Null when none is set.
   """
-  value: JSON!
-  """JSON Logic condition controlling whether this option is rendered."""
   condition: JSON
 }
 ```
@@ -174,9 +170,9 @@ type FieldOption {
 ### `FieldEdge`
 
 ```graphql
-"""Edge type for `FieldConnection`."""
+"""A field in a page of results."""
 type FieldEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The field."""
   node: Field!
@@ -186,19 +182,15 @@ type FieldEdge {
 ### `FieldConnection`
 
 ```graphql
-"""
-Relay-style connection of fields, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of fields."""
 type FieldConnection {
-  """List of field edges."""
+  """The edges in this page."""
   edges: [FieldEdge!]!
-  """
-  Flat list of fields, equivalent to `edges[].node`. Convenience accessor.
-  """
+  """The fields in this page."""
   nodes: [Field!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of fields."""
+  """The number of fields across all pages, ignoring `search`."""
   totalCount: Int!
 }
 ```
@@ -206,47 +198,41 @@ type FieldConnection {
 ### `FieldCreateInput`
 
 ```graphql
-"""Input for `fieldCreate`."""
+"""The input of `fieldCreate`."""
 input FieldCreateInput {
-  """Workspace ID to create the field in."""
+  """The ID of the workspace to create the field in."""
   workspaceId: ID!
-  """Stable machine-readable name."""
+  """The machine-readable name of the field."""
   name: String!
-  """Unique key identifier for the field."""
+  """
+  The stable identifier of the field, unique within the workspace. It cannot change later.
+  """
   key: String!
-  """Human-readable label."""
+  """The label shown next to the input."""
   label: String!
-  """The field type."""
+  """The kind of value the field captures."""
   type: FieldType!
-  """Whether multiple values are allowed."""
+  """Whether the field accepts more than one value."""
   multiple: Boolean
-  """Whether the field is required."""
+  """Whether the visitor must answer the field."""
   required: Boolean
-  """
-  Validation rules as a JSON-encoded string. Server parses before persisting.
-  """
+  """The validation rules, as a JSON string. Invalid JSON is rejected."""
   validationString: String
-  """JSON default value (shape depends on `type`)."""
+  """The value the field starts with."""
   defaultValue: JSON
-  """
-  Field options as a JSON array (only meaningful for select-style fields).
-  """
+  """The choices, as a JSON array. An option without an `id` gets one."""
   options: JSON
-  """JSON Logic condition controlling whether the field is rendered."""
+  """A JSON Logic rule that decides whether the field renders."""
   condition: JSON
-  """Placeholder text."""
+  """The text shown in the empty input."""
   placeholder: String
-  """Description shown alongside the label."""
+  """A description shown with the label."""
   description: String
-  """Help text shown below the field."""
+  """A hint shown below the field."""
   helpText: String
-  """
-  When true, the captured value is excluded from analytics tracking. Omitted defaults to `true`: tracking is opt-in.
-  """
+  """Whether the answer is left out of analytics. Defaults to `true`."""
   doNotTrack: Boolean
-  """
-  When true, the captured value is excluded from persistence. Omitted defaults to `true`: persistence is opt-in.
-  """
+  """Whether the answer is left out of storage. Defaults to `true`."""
   doNotStore: Boolean
 }
 ```
@@ -254,7 +240,7 @@ input FieldCreateInput {
 ### `FieldCreatePayload`
 
 ```graphql
-"""Payload returned by `fieldCreate`."""
+"""The result of `fieldCreate`."""
 type FieldCreatePayload {
   """The created field."""
   field: Field
@@ -265,42 +251,44 @@ type FieldCreatePayload {
 
 ```graphql
 """
-Input for `fieldUpdate`. Omit a field to leave it unchanged (but `type` is required because it is used to coerce other fields).
+The input of `fieldUpdate`. Omit a field to keep its value. `type` is required.
 """
 input FieldUpdateInput {
-  """Field ID."""
+  """The ID of the field."""
   id: ID!
-  """Workspace ID the field belongs to."""
+  """The ID of the workspace the field belongs to."""
   workspaceId: ID!
-  """New machine-readable name."""
+  """The machine-readable name of the field."""
   name: String
-  """New label."""
+  """The label shown next to the input."""
   label: String
   """
-  Field type. Required even when unchanged — used to coerce `validationString`, `options`, and `defaultValue` server-side.
+  The kind of value the field captures. Required: send the current type to keep it.
   """
   type: FieldType!
-  """Whether multiple values are allowed."""
+  """Whether the field accepts more than one value."""
   multiple: Boolean
-  """Whether the field is required."""
+  """Whether the visitor must answer the field."""
   required: Boolean
-  """Validation rules as a JSON-encoded string."""
+  """The validation rules, as a JSON string. Invalid JSON is rejected."""
   validationString: String
-  """JSON default value."""
+  """The value the field starts with."""
   defaultValue: JSON
-  """Field options as a JSON array."""
+  """
+  The choices, as a JSON array. Replaces the current choices; an option without an `id` gets one.
+  """
   options: JSON
-  """JSON Logic condition controlling whether the field is rendered."""
+  """A JSON Logic rule that decides whether the field renders."""
   condition: JSON
-  """Placeholder text."""
+  """The text shown in the empty input."""
   placeholder: String
-  """Description shown alongside the label."""
+  """A description shown with the label."""
   description: String
-  """Help text shown below the field."""
+  """A hint shown below the field."""
   helpText: String
-  """When true, the captured value is excluded from analytics tracking."""
+  """Whether the answer is left out of analytics."""
   doNotTrack: Boolean
-  """When true, the captured value is excluded from persistence."""
+  """Whether the answer is left out of storage."""
   doNotStore: Boolean
 }
 ```
@@ -308,7 +296,7 @@ input FieldUpdateInput {
 ### `FieldUpdatePayload`
 
 ```graphql
-"""Payload returned by `fieldUpdate`."""
+"""The result of `fieldUpdate`."""
 type FieldUpdatePayload {
   """The updated field."""
   field: Field
@@ -318,11 +306,11 @@ type FieldUpdatePayload {
 ### `FieldDeleteInput`
 
 ```graphql
-"""Input for `fieldDelete`."""
+"""The input of `fieldDelete`."""
 input FieldDeleteInput {
-  """Field ID."""
+  """The ID of the field."""
   id: ID!
-  """Workspace ID the field belongs to."""
+  """The ID of the workspace the field belongs to."""
   workspaceId: ID!
 }
 ```
@@ -330,13 +318,11 @@ input FieldDeleteInput {
 ### `FieldDeletePayload`
 
 ```graphql
-"""
-Payload returned by `fieldDelete`. Returns `userErrors` when the field is in use.
-"""
+"""The result of `fieldDelete`."""
 type FieldDeletePayload {
-  """ID of the deleted field (null when `userErrors` is non-empty)."""
+  """The ID of the deleted field. Null when `userErrors` is not empty."""
   deletedFieldId: ID
-  """Validation errors. Empty array indicates success."""
+  """The reasons the field was not deleted. Empty on success."""
   userErrors: [FieldDeleteUserError!]!
 }
 ```
@@ -344,9 +330,9 @@ type FieldDeletePayload {
 ### `FieldDeleteUserErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `fieldDelete`."""
+"""The reasons `fieldDelete` refuses a delete."""
 enum FieldDeleteUserErrorCode {
-  """The field is attached to one or more steps and cannot be deleted."""
+  """The field is on a step."""
   IN_USE
 }
 ```
@@ -354,17 +340,17 @@ enum FieldDeleteUserErrorCode {
 ### `FieldDeleteUserError`
 
 ```graphql
-"""
-A user error from `fieldDelete`. Carries the steps that block the delete when `code` is `IN_USE`.
-"""
+"""A reason `fieldDelete` did not delete a field."""
 type FieldDeleteUserError {
-  """Path to the input field that caused the error."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """A machine-readable code."""
   code: FieldDeleteUserErrorCode!
-  """Steps this field is attached to (present when `code` is `IN_USE`)."""
+  """The steps the field is on. Null unless `code` is `IN_USE`."""
   referencingSteps: [ReferencingStep!]
 }
 ```
@@ -372,13 +358,11 @@ type FieldDeleteUserError {
 ### `ReferencingStep`
 
 ```graphql
-"""
-A step that has this field attached, preventing its deletion. Returned in `FieldDeleteUserError` when the delete is blocked by usage.
-"""
+"""A step that a field is on, and so blocks the field's delete."""
 type ReferencingStep {
-  """The step id."""
+  """The ID of the step."""
   id: ID!
-  """The step name."""
+  """The name of the step."""
   name: String!
 }
 ```
@@ -386,15 +370,13 @@ type ReferencingStep {
 ### `FieldSortKeys`
 
 ```graphql
-"""
-Sort keys for `fields(...)`. Pair with `reverse: true` to flip the order (`NAME` + `reverse: false` sorts A→Z; `CREATED_AT` + `reverse: true` is newest-first).
-"""
+"""The orders `fields` can sort by. `reverse: true` flips each."""
 enum FieldSortKeys {
-  """Sort by `name` (alphabetical)."""
+  """By name, A to Z."""
   NAME
-  """Sort by `createdAt`."""
+  """By creation time, oldest first."""
   CREATED_AT
-  """Sort by `updatedAt`."""
+  """By last change, oldest first."""
   UPDATED_AT
 }
 ```