REST Resource: labels

Resource: Label

A label defines a taxonomy that can be applied to Drive items in order to organize and search across items. Labels can be simple strings, or can contain fields that describe additional metadata that can be further used to organize and search Drive items.

JSON representation
{
  "name": string,
  "id": string,
  "revisionId": string,
  "labelType": enum (LabelType),
  "creator": {
    object (UserInfo)
  },
  "createTime": string,
  "revisionCreator": {
    object (UserInfo)
  },
  "revisionCreateTime": string,
  "publisher": {
    object (UserInfo)
  },
  "publishTime": string,
  "disabler": {
    object (UserInfo)
  },
  "disableTime": string,
  "properties": {
    object (Properties)
  },
  "lifecycle": {
    object (Lifecycle)
  },
  "displayHints": {
    object (DisplayHints)
  },
  "appliedCapabilities": {
    object (AppliedCapabilities)
  },
  "schemaCapabilities": {
    object (SchemaCapabilities)
  },
  "appliedLabelPolicy": {
    object (AppliedLabelPolicy)
  },
  "fields": [
    {
      object (Field)
    }
  ],
  "learnMoreUri": string,
  "lockStatus": {
    object (LockStatus)
  }
}
Fields
name

string

Output only. Resource name of the label. Will be in the form of either: labels/{id} or labels/{id}@{revisionId} depending on the request. See id and revisionId below.

id

string

Output only. Globally unique identifier of this label. ID makes up part of the label name, but unlike name, ID is consistent between revisions. Matches the regex: ([a-zA-Z0-9])+

revisionId

string

Output only. Revision ID of the label. Revision ID might be part of the label name depending on the request issued. A new revision is created whenever revisioned properties of a label are changed. Matches the regex: ([a-zA-Z0-9])+

labelType

enum (LabelType)

Required. The type of label.

creator

object (UserInfo)

Output only. The user who created this label.

createTime

string (Timestamp format)

Output only. The time this label was created.

revisionCreator

object (UserInfo)

Output only. The user who created this label revision.

revisionCreateTime

string (Timestamp format)

Output only. The time this label revision was created.

publisher

object (UserInfo)

Output only. The user who published this label. This value has no meaning when the label is not published.

publishTime

string (Timestamp format)

Output only. The time this label was published. This value has no meaning when the label is not published.

disabler

object (UserInfo)

Output only. The user who disabled this label. This value has no meaning when the label is not disabled.

disableTime

string (Timestamp format)

Output only. The time this label was disabled. This value has no meaning when the label is not disabled.

properties

object (Properties)

Required. The basic properties of the label.

lifecycle

object (Lifecycle)

Output only. The lifecycle state of the label including whether it's published, deprecated, and has draft changes.

displayHints

object (DisplayHints)

Output only. UI display hints for rendering the label.

appliedCapabilities

object (AppliedCapabilities)

Output only. The capabilities related to this label on applied metadata.

schemaCapabilities

object (SchemaCapabilities)

Output only. The capabilities the user has on this label.

appliedLabelPolicy

object (AppliedLabelPolicy)

Output only. Behavior of this label when it's applied to Drive items.

fields[]

object (Field)

List of fields in descending priority order.

learnMoreUri

string

Custom URL to present to users to allow them to learn more about this label and how it should be used.

lockStatus

object (LockStatus)

Output only. The LockStatus of this label.

LabelType

The type of this label.

Enums
LABEL_TYPE_UNSPECIFIED Unknown label type.
SHARED Shared labels may be shared with users to apply to Drive items.
ADMIN Admin-owned label. Only creatable and editable by admins. Supports some additional admin-only features.

UserInfo

Information about a user.

JSON representation
{
  "person": string
}
Fields
person

string

The identifier for this user that can be used with the People API to get more information. For example, people/12345678.

Properties

Basic properties of the label.

JSON representation
{
  "title": string,
  "description": string
}
Fields
title

string

Required. Title of the label.

description

string

The description of the label.

Lifecycle

The lifecycle state of an object, such as label, field, or choice. The lifecycle enforces the following transitions:

  • UNPUBLISHED_DRAFT (starting state)
  • UNPUBLISHED_DRAFT -> PUBLISHED
  • UNPUBLISHED_DRAFT -> (Deleted)
  • PUBLISHED -> DISABLED
  • DISABLED -> PUBLISHED
  • DISABLED -> (Deleted)

The published and disabled states have some distinct characteristics:

  • Published—Some kinds of changes might be made to an object in this state, in which case hasUnpublishedChanges will be true. Also, some kinds of changes are not permitted. Generally, any change that would invalidate or cause new restrictions on existing metadata related to the label are rejected.
  • Disabled—When disabled, the configured DisabledPolicy takes effect.
JSON representation
{
  "state": enum (State),
  "hasUnpublishedChanges": boolean,
  "disabledPolicy": {
    object (DisabledPolicy)
  }
}
Fields
state

enum (State)

Output only. The state of the object associated with this lifecycle.

hasUnpublishedChanges

boolean

Output only. Whether the object associated with this lifecycle has unpublished changes.

disabledPolicy

object (DisabledPolicy)

The policy that governs how to show a disabled label, field, or selection choice.

State

The state of the object associated with this lifecycle.

Enums
STATE_UNSPECIFIED Unknown State.
UNPUBLISHED_DRAFT The initial state of an object. Once published, the object can never return to this state. Once an object is published, certain kinds of changes are no longer permitted.
PUBLISHED The object has been published. The object might have unpublished draft changes as indicated by hasUnpublishedChanges.
DISABLED The object has been published and has since been disabled. The object might have unpublished draft changes as indicated by hasUnpublishedChanges.
DELETED The object has been deleted.

DisabledPolicy

The policy that governs how to treat a disabled label, field, or selection choice in different contexts.

JSON representation
{
  "hideInSearch": boolean,
  "showInApply": boolean
}
Fields
showInApply

boolean

Whether to show this disabled object in the apply menu on Drive items.

  • When true, the object is generally shown in the UI as disabled and is unselectable.
  • When false, the object is generally hidden in the UI.

DisplayHints

UI display hints for rendering the label.

JSON representation
{
  "disabled": boolean,
  "hiddenInSearch": boolean,
  "shownInApply": boolean,
  "priority": string
}
Fields
disabled

boolean

Whether the label should be shown in the UI as disabled.

shownInApply

boolean

This label should be shown in the apply menu when applying values to a Drive item.

priority

string (int64 format)

Order to display label in a list.

AppliedCapabilities

The capabilities a user has on this label's applied metadata.

JSON representation
{
  "canRead": boolean,
  "canApply": boolean,
  "canRemove": boolean
}
Fields
canRead

boolean

Whether the user can read applied metadata related to this label.

canApply

boolean

Whether the user can apply this label to items.

canRemove

boolean

Whether the user can remove this label from items.

SchemaCapabilities

The capabilities related to this label when editing the label.

JSON representation
{
  "canUpdate": boolean,
  "canDelete": boolean,
  "canDisable": boolean,
  "canEnable": boolean
}
Fields
canUpdate

boolean

Whether the user can change this label.

canDelete

boolean

Whether the user can delete this label. The user must have permission and the label must be disabled.

canDisable

boolean

Whether the user can disable this label. The user must have permission and this label must not already be disabled.

canEnable

boolean

Whether the user can enable this label. The user must have permission and this label must be disabled.

AppliedLabelPolicy

Behavior of this label when it's applied to Drive items.

JSON representation
{
  "copyMode": enum (CopyMode)
}
Fields
copyMode

enum (CopyMode)

Indicates how the applied label and field values should be copied when a Drive item is copied.

CopyMode

Indicates how the applied label and field values should be copied when a Drive item is copied.

Enums
COPY_MODE_UNSPECIFIED Copy mode unspecified.
DO_NOT_COPY The applied label and field values are not copied by default when the Drive item it's applied to is copied.
ALWAYS_COPY The applied label and field values are always copied when the Drive item it's applied to is copied. Only admins can use this mode.
COPY_APPLIABLE The applied label and field values are copied if the label is appliable by the user making the copy.

Field

Defines a field that has a display name, data type, and other configuration options. This field defines the kind of metadata that may be set on a Drive item.

JSON representation
{
  "id": string,
  "queryKey": string,
  "properties": {
    object (Properties)
  },
  "lifecycle": {
    object (Lifecycle)
  },
  "displayHints": {
    object (DisplayHints)
  },
  "schemaCapabilities": {
    object (SchemaCapabilities)
  },
  "appliedCapabilities": {
    object (AppliedCapabilities)
  },
  "creator": {
    object (UserInfo)
  },
  "createTime": string,
  "updater": {
    object (UserInfo)
  },
  "updateTime": string,
  "publisher": {
    object (UserInfo)
  },
  "disabler": {
    object (UserInfo)
  },
  "disableTime": string,
  "lockStatus": {
    object (LockStatus)
  },

  // Union field type can be only one of the following:
  "textOptions": {
    object (TextOptions)
  },
  "integerOptions": {
    object (IntegerOptions)
  },
  "dateOptions": {
    object (DateOptions)
  },
  "selectionOptions": {
    object (SelectionOptions)
  },
  "userOptions": {
    object (UserOptions)
  }
  // End of list of possible types for union field type.
}
Fields
id

string

Output only. The key of a field, unique within a label or library.

This value is autogenerated. Matches the regex: ([a-zA-Z0-9])+

queryKey

string

Output only. The key to use when constructing Drive search queries to find files based on values defined for this field on files. For example, "{queryKey} > 2001-01-01".

properties

object (Properties)

The basic properties of the field.

lifecycle

object (Lifecycle)

Output only. The lifecycle of this field.

displayHints

object (DisplayHints)

Output only. UI display hints for rendering a field.

schemaCapabilities

object (SchemaCapabilities)

Output only. The capabilities this user has when editing this field.

appliedCapabilities

object (AppliedCapabilities)

Output only. The capabilities this user has on this field and its value when the label is applied on Drive items.

creator

object (UserInfo)

Output only. The user who created this field.

createTime

string (Timestamp format)

Output only. The time this field was created.

updater

object (UserInfo)

Output only. The user who modified this field.

updateTime

string (Timestamp format)

Output only. The time this field was updated.

publisher

object (UserInfo)

Output only. The user who published this field. This value has no meaning when the field is not published.

disabler

object (UserInfo)

Output only. The user who disabled this field. This value has no meaning when the field is not disabled.

disableTime

string (Timestamp format)

Output only. The time this field was disabled. This value has no meaning when the field is not disabled.

lockStatus

object (LockStatus)

Output only. The LockStatus of this field.

Union field type. The data type and options of this field. Once published, the data type cannot be changed. type can be only one of the following:
textOptions

object (TextOptions)

Text field options.

integerOptions

object (IntegerOptions)

Integer field options.

dateOptions

object (DateOptions)

Date field options.

selectionOptions

object (SelectionOptions)

Selection field options.

userOptions

object (UserOptions)

User field options.

TextOptions

Options for the Text field type.

JSON representation
{
  "minLength": integer,
  "maxLength": integer
}
Fields
minLength

integer

Output only. The minimum valid length of values for the text field.

maxLength

integer

Output only. The maximum valid length of values for the text field.

IntegerOptions

Options for the Integer field type.

JSON representation
{
  "minValue": string,
  "maxValue": string
}
Fields
minValue

string (int64 format)

Output only. The minimum valid value for the integer field.

maxValue

string (int64 format)

Output only. The maximum valid value for the integer field.

DateOptions

Options for the date field type.

JSON representation
{
  "dateFormatType": enum (DateFormat),
  "dateFormat": string,
  "minValue": {
    object (Date)
  },
  "maxValue": {
    object (Date)
  }
}
Fields
dateFormatType

enum (DateFormat)

Localized date formatting option. Field values are rendered in this format according to their locale.

dateFormat

string

Output only. ICU date format.

minValue

object (Date)

Output only. Minimum valid value (year, month, day).

maxValue

object (Date)

Output only. Maximum valid value (year, month, day).

DateFormat

Localized date format options.

Enums
DATE_FORMAT_UNSPECIFIED Date format unspecified.
LONG_DATE Includes full month name. For example, January 12, 1999 (MMMM d, y)
SHORT_DATE Short, numeric, representation. For example, 12/13/99 (M/d/yy)

SelectionOptions

Options for the selection field type.

JSON representation
{
  "listOptions": {
    object (ListOptions)
  },
  "choices": [
    {
      object (Choice)
    }
  ]
}
Fields
listOptions

object (ListOptions)

When specified, indicates this field supports a list of values. Once the field is published, this cannot be changed.

choices[]

object (Choice)

The options available for this selection field. The list order is consistent, and modified with insertBeforeChoice.

ListOptions

Options for a multi-valued variant of an associated field type.

JSON representation
{
  "maxEntries": integer
}
Fields
maxEntries

integer

Maximum number of entries permitted.

Choice

Selection field choice.

JSON representation
{
  "id": string,
  "properties": {
    object (Properties)
  },
  "lifecycle": {
    object (Lifecycle)
  },
  "displayHints": {
    object (DisplayHints)
  },
  "schemaCapabilities": {
    object (SchemaCapabilities)
  },
  "appliedCapabilities": {
    object (AppliedCapabilities)
  },
  "creator": {
    object (UserInfo)
  },
  "createTime": string,
  "updater": {
    object (UserInfo)
  },
  "updateTime": string,
  "publisher": {
    object (UserInfo)
  },
  "publishTime": string,
  "disabler": {
    object (UserInfo)
  },
  "disableTime": string,
  "lockStatus": {
    object (LockStatus)
  }
}
Fields
id

string

The unique value of the choice. This ID is autogenerated. Matches the regex: ([a-zA-Z0-9_])+.

properties

object (Properties)

Basic properties of the choice.

lifecycle

object (Lifecycle)

Output only. Lifecycle of the choice.

displayHints

object (DisplayHints)

Output only. UI display hints for rendering a choice.

schemaCapabilities

object (SchemaCapabilities)

Output only. The capabilities related to this option when editing the option.

appliedCapabilities

object (AppliedCapabilities)

Output only. The capabilities related to this choice on applied metadata.

creator

object (UserInfo)

Output only. The user who created this choice.

createTime

string (Timestamp format)

Output only. The time this choice was created.

updater

object (UserInfo)

Output only. The user who updated this choice last.

updateTime

string (Timestamp format)

Output only. The time this choice was updated last.

publisher

object (UserInfo)

Output only. The user who published this choice. This value has no meaning when the choice is not published.

publishTime

string (Timestamp format)

Output only. The time this choice was published. This value has no meaning when the choice is not published.

disabler

object (UserInfo)

Output only. The user who disabled this choice. This value has no meaning when the option is not disabled.

disableTime

string (Timestamp format)

Output only. The time this choice was disabled. This value has no meaning when the choice is not disabled.

lockStatus

object (LockStatus)

Output only. The LockStatus of this choice.

Properties

Basic properties of the choice.

JSON representation
{
  "displayName": string,
  "description": string,
  "badgeConfig": {
    object (BadgeConfig)
  },
  "insertBeforeChoice": string
}
Fields
displayName

string

Required. The display text to show in the UI identifying this field.

description

string

The description of this label.

badgeConfig

object (BadgeConfig)

The badge configuration for this choice. When set, the label that owns this choice is considered a "badged label".

insertBeforeChoice

string

Input only. Insert or move this choice before the indicated choice. If empty, the choice is placed at the end of the list.

BadgeConfig

Badge status of the label.

JSON representation
{
  "color": {
    object (Color)
  },
  "priorityOverride": string
}
Fields
color

object (Color)

The color of the badge. When not specified, no badge is rendered. This color will be changed into the closest recommended supported color.

priorityOverride

string (int64 format)

Override the default global priority of this badge. When set to 0, the default priority heuristic is used.

DisplayHints

UI display hints for rendering an option.

JSON representation
{
  "disabled": boolean,
  "hiddenInSearch": boolean,
  "shownInApply": boolean,
  "badgeColors": {
    object (BadgeColors)
  },
  "darkBadgeColors": {
    object (BadgeColors)
  },
  "badgePriority": string
}
Fields
disabled

boolean

Whether the option should be shown in the UI as disabled.

shownInApply

boolean

This option should be shown in the apply menu when applying values to a Drive item.

badgeColors

object (BadgeColors)

The colors to use for the badge. Changed to Google Material colors based on the chosen properties.badge_config.color.

darkBadgeColors

object (BadgeColors)

The dark-mode color to use for the badge. Changed to Google Material colors based on the chosen properties.badge_config.color.

badgePriority

string (int64 format)

The priority of this badge. Used to compare and sort between multiple badges. A lower number means the badge should be shown first. When a badging configuration is not present, this will be 0. Otherwise, this will be set to BadgeConfig.priority_override or the default heuristic which prefers creation date of the label, and field and option priority.

BadgeColors

The color derived from BadgeConfig and changed to the closest recommended supported color.

JSON representation
{
  "backgroundColor": {
    object (Color)
  },
  "foregroundColor": {
    object (Color)
  },
  "soloColor": {
    object (Color)
  }
}
Fields
backgroundColor

object (Color)

Output only. Badge background that pairs with the foreground.

foregroundColor

object (Color)

Output only. Badge foreground that pairs with the background.

soloColor

object (Color)

Output only. Color that can be used for text without a background.

SchemaCapabilities

The capabilities related to this choice when editing the choice.

JSON representation
{
  "canUpdate": boolean,
  "canDelete": boolean,
  "canDisable": boolean,
  "canEnable": boolean
}
Fields
canUpdate

boolean

Whether the user can update this choice.

canDelete

boolean

Whether the user can delete this choice.

canDisable

boolean

Whether the user can disable this choice.

canEnable

boolean

Whether the user can enable this choice.

AppliedCapabilities

The capabilities related to this choice on applied metadata.

JSON representation
{
  "canRead": boolean,
  "canSearch": boolean,
  "canSelect": boolean
}
Fields
canRead

boolean

Whether the user can read related applied metadata on items.

canSelect

boolean

Whether the user can select this choice on an item.

LockStatus

Contains information about whether a label component should be considered locked.

JSON representation
{
  "locked": boolean
}
Fields
locked

boolean

Output only. Indicates whether this label component is the (direct) target of a LabelLock. A label component can be implicitly locked even if it's not the direct target of a LabelLock, in which case this field is set to false.

UserOptions

Options for the user field type.

JSON representation
{
  "listOptions": {
    object (ListOptions)
  }
}
Fields
listOptions

object (ListOptions)

When specified, indicates that this field supports a list of values. Once the field is published, this cannot be changed.

Properties

The basic properties of the field.

JSON representation
{
  "displayName": string,
  "required": boolean,
  "insertBeforeField": string
}
Fields
displayName

string

Required. The display text to show in the UI identifying this field.

required

boolean

Whether the field should be marked as required.

insertBeforeField

string

Input only. Insert or move this field before the indicated field. If empty, the field is placed at the end of the list.

DisplayHints

UI display hints for rendering a field.

JSON representation
{
  "required": boolean,
  "disabled": boolean,
  "hiddenInSearch": boolean,
  "shownInApply": boolean
}
Fields
required

boolean

Whether the field should be shown as required in the UI.

disabled

boolean

Whether the field should be shown in the UI as disabled.

shownInApply

boolean

This field should be shown in the apply menu when applying values to a Drive item.

SchemaCapabilities

The capabilities related to this field when editing the field.

JSON representation
{
  "canUpdate": boolean,
  "canDelete": boolean,
  "canDisable": boolean,
  "canEnable": boolean
}
Fields
canUpdate

boolean

Whether the user can change this field.

canDelete

boolean

Whether the user can delete this field. The user must have permission and the field must be deprecated.

canDisable

boolean

Whether the user can disable this field. The user must have permission and this field must not already be disabled.

canEnable

boolean

Whether the user can enable this field. The user must have permission and this field must be disabled.

AppliedCapabilities

The capabilities related to this field on applied metadata.

JSON representation
{
  "canRead": boolean,
  "canSearch": boolean,
  "canWrite": boolean
}
Fields
canRead

boolean

Whether the user can read related applied metadata on items.

canWrite

boolean

Whether the user can set this field on Drive items.

Methods

create

Creates a new Label.

delete

Permanently deletes a Label and related metadata on Drive Items.

delta

Updates a single Label by applying a set of update requests resulting in a new draft revision.

disable

Disable a published Label.

enable

Enable a disabled Label and restore it to its published state.

get

Get a label by its resource name.

list

List labels.

publish

Publish all draft changes to the Label.

updateLabelCopyMode

Updates a Label's CopyMode.