picked 0.0.101-next.2 → 0.0.101

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

@@ -0,0 +1,400 @@
+---
+type: reference
+layout: docs
+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.
+
+## Queries
+
+### `field`
+
+Get a field by ID within a workspace.
+
+```graphql
+field(id: ID!, workspaceId: ID!): Field @auth
+```
+
+### `fields`
+
+Get list of fields within a workspace.
+
+```graphql
+fields(
+  workspaceId: ID!
+  first: Int
+  after: String
+  last: Int
+  before: String
+  search: String
+  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.
+  """
+  stepId: ID
+): FieldConnection! @auth
+```
+
+## Mutations
+
+### `fieldCreate`
+
+Create a new field. Requires scope: `ORGANIZATION_PROJECTS_CREATE`.
+
+```graphql
+fieldCreate(input: FieldCreateInput!): FieldCreatePayload! @auth
+```
+
+### `fieldUpdate`
+
+Update a field. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+fieldUpdate(input: FieldUpdateInput!): FieldUpdatePayload! @auth
+```
+
+### `fieldDelete`
+
+Delete a field. Requires scope: `ORGANIZATION_PROJECTS_DELETE`.
+
+```graphql
+fieldDelete(input: FieldDeleteInput!): FieldDeletePayload! @auth
+```
+
+## Types
+
+### `FieldType`
+
+```graphql
+"""Field type — what kind of value the field captures."""
+enum FieldType {
+  """Plain text input."""
+  TEXT
+  """Numeric input."""
+  NUMBER
+  """Boolean (checkbox/toggle)."""
+  BOOLEAN
+  """Free-form JSON structure (the SDK plugin renders an editor)."""
+  OBJECT
+}
+```
+
+### `Field`
+
+```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.
+"""
+type Field {
+  """Unique field identifier."""
+  id: ID!
+  """
+  Stable machine-readable name (used to key the value in the captured payload).
+  """
+  name: String!
+  """Stable, human-readable key for SDK consumers."""
+  key: String!
+  """Human-readable label shown to end-users 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).
+  """
+  multiple: Boolean!
+  """Whether the field is required."""
+  required: Boolean!
+  """JSON validation rules (shape depends on `type`)."""
+  validation: JSON
+  """
+  Selectable options when the field is a single/multi-select (shape: `{ label, value, ... }`).
+  """
+  options: [FieldOption!]
+  """
+  JSON condition controlling whether the field is rendered (JSON Logic AST).
+  """
+  condition: JSON
+  """JSON default value (shape depends on `type`)."""
+  defaultValue: JSON
+  """Placeholder text rendered inside the input when empty."""
+  placeholder: String
+  """Field description shown alongside the label."""
+  description: String
+  """Help text rendered below the field as a hint."""
+  helpText: String
+  """When true, the captured value is excluded from analytics tracking."""
+  doNotTrack: Boolean!
+  """When true, the captured value is excluded from persistence."""
+  doNotStore: Boolean!
+  """The list of steps this field belongs to."""
+  steps: StepConnection!
+  """The workspace this field belongs to."""
+  workspace: Workspace!
+  """The workspace ID this field belongs to."""
+  workspaceId: ID!
+  """When this field was created."""
+  createdAt: DateTime!
+  """When this field was last updated."""
+  updatedAt: DateTime!
+}
+```
+
+### `FieldOption`
+
+```graphql
+"""
+A single selectable option within a field (only meaningful for select-style fields).
+"""
+type FieldOption {
+  """Stable option identifier."""
+  id: ID!
+  """Human-readable label shown to end-users."""
+  label: String!
+  """Optional description shown alongside the label."""
+  description: String
+  """
+  The option's machine value (becomes the field's captured value when selected).
+  """
+  value: JSON!
+  """JSON Logic condition controlling whether this option is rendered."""
+  condition: JSON
+}
+```
+
+### `FieldEdge`
+
+```graphql
+"""Edge type for `FieldConnection`."""
+type FieldEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The field."""
+  node: Field!
+}
+```
+
+### `FieldConnection`
+
+```graphql
+"""
+Relay-style connection of fields, with both an `edges` list and a flat `nodes` accessor.
+"""
+type FieldConnection {
+  """List of field edges."""
+  edges: [FieldEdge!]!
+  """
+  Flat list of fields, equivalent to `edges[].node`. Convenience accessor.
+  """
+  nodes: [Field!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of fields."""
+  totalCount: Int!
+}
+```
+
+### `FieldCreateInput`
+
+```graphql
+"""Input for `fieldCreate`."""
+input FieldCreateInput {
+  """Workspace ID to create the field in."""
+  workspaceId: ID!
+  """Stable machine-readable name."""
+  name: String!
+  """Unique key identifier for the field."""
+  key: String!
+  """Human-readable label."""
+  label: String!
+  """The field type."""
+  type: FieldType!
+  """Whether multiple values are allowed."""
+  multiple: Boolean
+  """Whether the field is required."""
+  required: Boolean
+  """
+  Validation rules as a JSON-encoded string. Server parses before persisting.
+  """
+  validationString: String
+  """JSON default value (shape depends on `type`)."""
+  defaultValue: JSON
+  """
+  Field options as a JSON array (only meaningful for select-style fields).
+  """
+  options: JSON
+  """JSON Logic condition controlling whether the field is rendered."""
+  condition: JSON
+  """Placeholder text."""
+  placeholder: String
+  """Description shown alongside the label."""
+  description: String
+  """Help text shown below the field."""
+  helpText: String
+  """
+  When true, the captured value is excluded from analytics tracking. Omitted defaults to `true`: tracking is opt-in.
+  """
+  doNotTrack: Boolean
+  """
+  When true, the captured value is excluded from persistence. Omitted defaults to `true`: persistence is opt-in.
+  """
+  doNotStore: Boolean
+}
+```
+
+### `FieldCreatePayload`
+
+```graphql
+"""Payload returned by `fieldCreate`."""
+type FieldCreatePayload {
+  """The created field."""
+  field: Field
+}
+```
+
+### `FieldUpdateInput`
+
+```graphql
+"""
+Input for `fieldUpdate`. Omit a field to leave it unchanged (but `type` is required because it is used to coerce other fields).
+"""
+input FieldUpdateInput {
+  """Field ID."""
+  id: ID!
+  """Workspace ID the field belongs to."""
+  workspaceId: ID!
+  """New machine-readable name."""
+  name: String
+  """New label."""
+  label: String
+  """
+  Field type. Required even when unchanged — used to coerce `validationString`, `options`, and `defaultValue` server-side.
+  """
+  type: FieldType!
+  """Whether multiple values are allowed."""
+  multiple: Boolean
+  """Whether the field is required."""
+  required: Boolean
+  """Validation rules as a JSON-encoded string."""
+  validationString: String
+  """JSON default value."""
+  defaultValue: JSON
+  """Field options as a JSON array."""
+  options: JSON
+  """JSON Logic condition controlling whether the field is rendered."""
+  condition: JSON
+  """Placeholder text."""
+  placeholder: String
+  """Description shown alongside the label."""
+  description: String
+  """Help text shown below the field."""
+  helpText: String
+  """When true, the captured value is excluded from analytics tracking."""
+  doNotTrack: Boolean
+  """When true, the captured value is excluded from persistence."""
+  doNotStore: Boolean
+}
+```
+
+### `FieldUpdatePayload`
+
+```graphql
+"""Payload returned by `fieldUpdate`."""
+type FieldUpdatePayload {
+  """The updated field."""
+  field: Field
+}
+```
+
+### `FieldDeleteInput`
+
+```graphql
+"""Input for `fieldDelete`."""
+input FieldDeleteInput {
+  """Field ID."""
+  id: ID!
+  """Workspace ID the field belongs to."""
+  workspaceId: ID!
+}
+```
+
+### `FieldDeletePayload`
+
+```graphql
+"""
+Payload returned by `fieldDelete`. Returns `userErrors` when the field is in use.
+"""
+type FieldDeletePayload {
+  """ID of the deleted field (null when `userErrors` is non-empty)."""
+  deletedFieldId: ID
+  """Validation errors. Empty array indicates success."""
+  userErrors: [FieldDeleteUserError!]!
+}
+```
+
+### `FieldDeleteUserErrorCode`
+
+```graphql
+"""Machine-readable error codes for `fieldDelete`."""
+enum FieldDeleteUserErrorCode {
+  """The field is attached to one or more steps and cannot be deleted."""
+  IN_USE
+}
+```
+
+### `FieldDeleteUserError`
+
+```graphql
+"""
+A user error from `fieldDelete`. Carries the steps that block the delete when `code` is `IN_USE`.
+"""
+type FieldDeleteUserError {
+  """Path to the input field that caused the error."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: FieldDeleteUserErrorCode!
+  """Steps this field is attached to (present when `code` is `IN_USE`)."""
+  referencingSteps: [ReferencingStep!]
+}
+```
+
+### `ReferencingStep`
+
+```graphql
+"""
+A step that has this field attached, preventing its deletion. Returned in `FieldDeleteUserError` when the delete is blocked by usage.
+"""
+type ReferencingStep {
+  """The step id."""
+  id: ID!
+  """The step name."""
+  name: String!
+}
+```
+
+### `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).
+"""
+enum FieldSortKeys {
+  """Sort by `name` (alphabetical)."""
+  NAME
+  """Sort by `createdAt`."""
+  CREATED_AT
+  """Sort by `updatedAt`."""
+  UPDATED_AT
+}
+```