picked 0.0.101 → 0.0.102-next.2

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

@@ -6,16 +6,16 @@ generated: true
 
 # Label schema
 
-The operations and types that `label.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.
 
 ## Mutations
 
 ### `labelsSet`
 
-Create or replace labels on an owner. Requires scope:
-`ORGANIZATION_LEADS_UPDATE` on the lead's project for a `LEAD` owner, and
-`ORGANIZATION_PROJECTS_UPDATE` on the project for a `PROJECT` or
-`WORKFLOW_RUN` owner.
+Creates or replaces labels on a lead, a project or a workflow run. Labels the call does not name
+are unchanged. A `LEAD` owner needs `ORGANIZATION_LEADS_UPDATE`; the other owners need
+`ORGANIZATION_PROJECTS_UPDATE`.
+Scope: `ORGANIZATION_LEADS_UPDATE` or `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 labelsSet(input: LabelsSetInput!): LabelsSetPayload! @auth
@@ -23,9 +23,10 @@ labelsSet(input: LabelsSetInput!): LabelsSetPayload! @auth
 
 ### `labelsDelete`
 
-Remove labels from an owner. Requires scope: `ORGANIZATION_LEADS_UPDATE` on
-the lead's project for a `LEAD` owner, and `ORGANIZATION_PROJECTS_UPDATE` on
-the project for a `PROJECT` or `WORKFLOW_RUN` owner.
+Deletes labels from a lead, a project or a workflow run. Deleting a label that is not set
+succeeds. A `LEAD` owner needs `ORGANIZATION_LEADS_UPDATE`; the other owners need
+`ORGANIZATION_PROJECTS_UPDATE`.
+Scope: `ORGANIZATION_LEADS_UPDATE` or `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 labelsDelete(input: LabelsDeleteInput!): LabelsDeletePayload! @auth
@@ -36,7 +37,7 @@ labelsDelete(input: LabelsDeleteInput!): LabelsDeletePayload! @auth
 ### `LabelType`
 
 ```graphql
-"""How to read a label's `value`."""
+"""How to read the `value` of a label."""
 enum LabelType {
   """A plain string."""
   TEXT
@@ -53,8 +54,7 @@ enum LabelType {
 
 ```graphql
 """
-The kind of entity a label is attached to. Each kind is read under its own
-scope and written under another:
+The kind of entity a label is on. Each kind is read and written under its own scopes:
 
 | Owner type | Read scope | Write scope |
 | --- | --- | --- |
@@ -62,14 +62,14 @@ scope and written under another:
 | `PROJECT` | `ORGANIZATION_PROJECTS_READ` | `ORGANIZATION_PROJECTS_UPDATE` |
 | `WORKFLOW_RUN` | `ORGANIZATION_PROJECTS_READ` | `ORGANIZATION_PROJECTS_UPDATE` |
 
-A workflow run reads and writes its own labels without either scope.
+A workflow run reads and writes its own labels without a scope.
 """
 enum LabelOwnerType {
-  """A captured lead. Its labels are deleted with it."""
+  """A lead. Its labels are deleted with it."""
   LEAD
-  """A project, whose id is the owner id. Its labels outlive every lead."""
+  """A project. The owner ID is the project ID."""
   PROJECT
-  """A workflow run. Its labels outlive every lead."""
+  """A workflow run."""
   WORKFLOW_RUN
 }
 ```
@@ -78,31 +78,27 @@ enum LabelOwnerType {
 
 ```graphql
 """
-An annotation on an owner. Unique per owner, namespace and key, so setting one
-that already exists replaces its value and type.
-
-A label written with `expiresIn` expires that many seconds after the write.
-Once it has expired it reads as absent: it leaves its owner's `labels`, matches
-no lead query clause, and a later write to it creates a new label with a new id.
+A name and a value on a lead, a project or a workflow run. An owner holds one label per namespace
+and key, and an expired label reads as absent everywhere.
 """
 type Label {
-  """Unique label identifier."""
+  """The ID of the label."""
   id: ID!
-  """Grouping for related keys, rendered as a section heading."""
+  """The first part of the name of the label, which groups related keys."""
   namespace: String!
-  """Name of this label within its namespace."""
+  """The name of the label within its namespace."""
   key: String!
   """How to read `value`."""
   type: LabelType!
-  """The value, always a string. Interpret it through `type`."""
+  """The value, as a string to read through `type`."""
   value: String!
-  """When this label was first set."""
+  """When the label was created."""
   createdAt: DateTime!
-  """When this label was last changed."""
+  """When the label last changed."""
   updatedAt: DateTime!
-  """When this label expires, or null when it does not expire."""
+  """When the label expires. Null when it does not expire."""
   expiresAt: DateTime
-  """The owner this label annotates."""
+  """The lead, project or workflow run the label is on."""
   owner: LabelOwner!
 }
 ```
@@ -110,7 +106,7 @@ type Label {
 ### `LabelOwner`
 
 ```graphql
-"""The resource a label annotates: a lead, a project or a workflow run."""
+"""The entity a label is on: a lead, a project or a workflow run."""
 union LabelOwner = Lead | Project | WorkflowRun
 ```
 
@@ -118,22 +114,20 @@ union LabelOwner = Lead | Project | WorkflowRun
 
 ```graphql
 """
-One entry in a label's log: something done to the label, by a workflow run
-task, a person or an integration. `label` is null once the label has been
-removed or has expired.
+A change to a label, made by a workflow run task, a person or an integration.
 """
 type LabelOperation implements Operation {
-  """Unique operation identifier."""
+  """The ID of the operation."""
   id: ID!
-  """What was done to the label."""
+  """What the operation did to the label."""
   type: OperationType!
   """When the operation happened."""
   occurredAt: DateTime!
   """
-  The workflow run task that performed the operation, or null when it was not a workflow.
+  The workflow run task that made the change. Null when a workflow did not make it.
   """
   task: WorkflowTask
-  """The label, or null once it has been removed or has expired."""
+  """The label. Null when the label was deleted or has expired."""
   label: Label
 }
 ```
@@ -142,61 +136,35 @@ type LabelOperation implements Operation {
 
 ```graphql
 """
-One label to set. Namespace and key must be 1-64 characters of lowercase
-letters, digits, underscore or hyphen; a dot is rejected, because the leads
-search query language splits `labels.<namespace>.<key>` on it.
-
-Exactly one of `value` and `increment` is required; a label carrying both, or
-neither, is refused with `LABEL_WRITE_INVALID`.
-
-Example, a lock that holds the caller's id for an hour unless another caller
-holds it already:
-
-    { namespace: "cms", key: "request-callback", type: TEXT, value: "wkrun_abc",
-      onlyIfAbsent: true, expiresIn: 3600 }
-
-Example, a counter:
-
-    { namespace: "cms", key: "sent-today", type: NUMBER, increment: 1, expiresIn: 86400 }
+A label to set. A namespace and a key are each 1-64 lowercase letters, digits, underscores or
+hyphens. Exactly one of `value` and `increment` is required.
 """
 input LabelInput {
-  """Grouping for related keys."""
+  """The first part of the name of the label, which groups related keys."""
   namespace: String!
-  """Name of this label within its namespace."""
+  """The name of the label within its namespace."""
   key: String!
   """How to read `value`. Must be `NUMBER` with `increment`."""
   type: LabelType!
   """
-  The value, as a string. Must parse as `type`. A write with `value` and no
-  `expiresIn` makes the label permanent, clearing any expiry it had.
+  The value, as a string that parses as `type`. Without `expiresIn`, the label does not expire.
   """
   value: String
   """
-  A finite number to add to the label's current value, in place of `value`; a
-  negative number subtracts.
-  An absent or expired label reads as 0. The label must be of type `NUMBER`:
-  an increment of a label of another type is refused with
-  `VALUE_INVALID_FOR_TYPE`, and the label is unchanged. Concurrent increments
-  all count. An increment keeps a live label's expiry, so its `expiresIn`
-  applies only when the increment creates the label. Each increment records an
-  operation, and cannot be combined with `onlyIfAbsent`.
+  A finite number to add to the current value; a negative number subtracts. An absent or expired
+  label counts as 0, concurrent increments all count, and a live label keeps its expiry. Cannot
+  be combined with `onlyIfAbsent`.
   """
   increment: Float
   """
-  Seconds from the write until the label expires: a whole number from 1 to
-  31536000 (365 days). An expired label reads as absent everywhere.
+  The number of seconds until the label expires, from 1 to 31536000 (365 days).
   """
   expiresIn: Int
   """
-  Writes the label only when the owner holds no unexpired label under this
-  namespace and key. The check and the write are one atomic step, so of
-  several concurrent writes to an absent label exactly one takes effect.
-  
-  A live label that already holds this write's type and value counts as taken,
-  is left unchanged (its expiry included) and records no operation, so a
-  retried write reads the same result. A live label holding anything else is
-  left unchanged, is not taken, and is listed in `LabelsSetPayload.skipped`. A
-  lock's value should therefore be unique to its holder, such as a run id.
+  Whether to write the label only when no live label has this namespace and key. Of several
+  concurrent writes to an absent label, exactly one takes effect. A live label with this type and
+  value counts as written and is unchanged; a live label with another value is unchanged and is
+  listed in `LabelsSetPayload.skipped`.
   """
   onlyIfAbsent: Boolean
 }
@@ -205,17 +173,15 @@ input LabelInput {
 ### `LabelIdentifierInput`
 
 ```graphql
-"""Names one label without its value, for deletion."""
+"""A label to delete, named by namespace and key."""
 input LabelIdentifierInput {
-  """Grouping for related keys."""
+  """The first part of the name of the label, which groups related keys."""
   namespace: String!
-  """Name of this label within its namespace."""
+  """The name of the label within its namespace."""
   key: String!
   """
-  Removes the label only when it has not expired and its stored value equals
-  this. The check and the removal are one atomic step. A label holding another
-  value is left unchanged, records no operation, and is not counted as
-  removed: a holder releases its lock and never another holder's.
+  The value the label must hold to be deleted. A live label with another value is unchanged and
+  is not listed in `deletedLabelIds`.
   """
   ifValue: String
 }
@@ -224,31 +190,17 @@ input LabelIdentifierInput {
 ### `LabelsSetInput`
 
 ```graphql
-"""
-Input for `labelsSet`. Creates or replaces each named label and leaves every
-other label on the owner untouched, so a partial save cannot discard work
-another writer did.
-
-The labels are taken in (namespace, key) order, so two concurrent calls naming
-the same labels cannot deadlock.
-"""
+"""The input of `labelsSet`."""
 input LabelsSetInput {
-  """The kind of entity being annotated."""
+  """The kind of entity the labels are on."""
   ownerType: LabelOwnerType!
-  """ID of the entity being annotated."""
+  """The ID of the entity the labels are on."""
   ownerId: ID!
-  """
-  Labels to create or replace, one per namespace and key. A label naming the
-  namespace and key of an earlier one is refused with `LABEL_WRITE_INVALID`.
-  """
+  """The labels to create or replace, one per namespace and key."""
   labels: [LabelInput!]!
   """
-  Takes every label or none. When any `onlyIfAbsent` label is skipped, the call
-  writes nothing, records no operation, returns no `labels`, and lists in
-  `skipped` the existing labels that blocked it. Of two concurrent
-  `atomic` calls that both write some label with `onlyIfAbsent`, each
-  with a value unique to its caller, at most one takes effect. Defaults to
-  false.
+  Whether to write every label or none. When an `onlyIfAbsent` label is skipped, the call writes
+  nothing and lists the blocking labels in `skipped`. Defaults to false.
   """
   atomic: Boolean
 }
@@ -257,20 +209,18 @@ input LabelsSetInput {
 ### `LabelsSetPayload`
 
 ```graphql
-"""Payload returned by `labelsSet`."""
+"""The result of `labelsSet`."""
 type LabelsSetPayload {
   """
-  The labels the call took, as they now stand: those it wrote, and those an
-  `onlyIfAbsent` label found already holding its own type and value. Empty when
-  input failed validation.
+  The labels the call wrote, and the `onlyIfAbsent` labels that already held this type and value.
+  Empty when the call has `userErrors`, or when an `atomic` call wrote nothing.
   """
   labels: [Label!]!
   """
-  The existing labels an `onlyIfAbsent` label left in place, because they held
-  another type or value.
+  The live labels that an `onlyIfAbsent` label left in place because they held another value.
   """
   skipped: [Label!]!
-  """Per-label validation errors. Empty array indicates success."""
+  """The errors, one per invalid label. Empty on success."""
   userErrors: [LabelUserError!]!
 }
 ```
@@ -278,16 +228,13 @@ type LabelsSetPayload {
 ### `LabelsDeleteInput`
 
 ```graphql
-"""
-Input for `labelsDelete`. Deleting a label that is not set is a no-op success.
-An expired label is deleted without being counted as removed.
-"""
+"""The input of `labelsDelete`."""
 input LabelsDeleteInput {
-  """The kind of entity being annotated."""
+  """The kind of entity the labels are on."""
   ownerType: LabelOwnerType!
-  """ID of the entity being annotated."""
+  """The ID of the entity the labels are on."""
   ownerId: ID!
-  """Labels to remove."""
+  """The labels to delete."""
   labels: [LabelIdentifierInput!]!
 }
 ```
@@ -295,13 +242,11 @@ input LabelsDeleteInput {
 ### `LabelsDeletePayload`
 
 ```graphql
-"""Payload returned by `labelsDelete`."""
+"""The result of `labelsDelete`."""
 type LabelsDeletePayload {
-  """
-  IDs of the labels that were removed. A label `ifValue` spared is not listed.
-  """
+  """The IDs of the labels the call deleted."""
   deletedLabelIds: [ID!]!
-  """Per-label validation errors. Empty array indicates success."""
+  """The errors, one per invalid label. Empty on success."""
   userErrors: [LabelUserError!]!
 }
 ```
@@ -309,24 +254,23 @@ type LabelsDeletePayload {
 ### `LabelUserErrorCode`
 
 ```graphql
-"""Machine-readable error codes for the label mutations."""
+"""What went wrong in a label mutation."""
 enum LabelUserErrorCode {
-  """The namespace is outside the accepted character set."""
+  """
+  The namespace has a character outside the allowed set, or a wrong length.
+  """
   NAMESPACE_INVALID
-  """The key is outside the accepted character set."""
+  """The key has a character outside the allowed set, or a wrong length."""
   KEY_INVALID
-  """The value does not parse as the declared type."""
-  VALUE_INVALID_FOR_TYPE
   """
-  No owner of that type exists with that id, or the id carries another owner
-  type's prefix.
+  The value does not parse as the type, or the incremented label is not a `NUMBER`.
   """
+  VALUE_INVALID_FOR_TYPE
+  """No owner of that type has that ID."""
   OWNER_NOT_FOUND
   """
-  The write is malformed: it carries both `value` and `increment` or neither,
-  an `increment` with `onlyIfAbsent` or with a type other than `NUMBER`, an
-  `expiresIn` outside 1 to 31536000 seconds, or the namespace and key of an
-  earlier label in the same call.
+  A malformed write: both or neither of `value` and `increment`, `increment` with `onlyIfAbsent`
+  or a type other than `NUMBER`, `expiresIn` out of range, or a repeated namespace and key.
   """
   LABEL_WRITE_INVALID
 }
@@ -335,15 +279,15 @@ enum LabelUserErrorCode {
 ### `LabelUserError`
 
 ```graphql
-"""A user error from `labelsSet` or `labelsDelete`."""
+"""An error from `labelsSet` or `labelsDelete`."""
 type LabelUserError {
   """
-  Path to the input field that caused the error, e.g. `['labels', '0', 'namespace']`.
+  The path to the input field that caused the error, such as `["labels", "0", "namespace"]`.
   """
   field: [String!]
-  """Human-readable error message."""
+  """A message that describes the error."""
   message: String!
-  """Machine-readable error code."""
+  """The error code."""
   code: LabelUserErrorCode!
 }
 ```