Types

Types define custom fields that are used to enhance resources as you need.

Since there is no model that fits all use-cases, we give you the possibility to customize some resources, so that they fit your data model as close as possible.

Use Types to model your own CustomFields on resources, like Category and Customer.

In case you want to customize products, please use product types instead that serve a similar purpose, but tailored to products.

  • product types are specialized to customize products.
  • types are used to customize other resources.

Representations

Type

TypeDraft

TypeDrafts are given as payload for Create Type requests.

FieldDefinition

Field definitions describe custom fields and allow you to define some meta-information associated with the field.

  • type - FieldType
    Describes the type of the field.
  • name - String
    The name of the field.
    The name must be between two and 36 characters long and can contain the ASCII letters A to Z in lowercase or uppercase, digits, underscores (_) and the hyphen-minus (-).
    The name must be unique for a given resource type ID. In case there is a field with the same name in another type it has to have the same FieldType also.
  • label - LocalizedString
    A human-readable label for the field.
  • required - Boolean
    Whether the field is required to have a value.
  • inputHint - TextInputHint Provides a visual representation type for this field. It is only relevant for string-based field types like StringType and LocalizedStringType.

FieldType

All field types have a name. Some have additional fields such as values in enums or elementType in sets.

BooleanType

Valid values for the field are true and false (JSON Boolean).

  • name - Boolean

StringType

  • name - String

LocalizedStringType

  • name - LocalizedString

EnumType

  • name - Enum
  • values - Array of EnumValue
    The field value contain the key of the Enum.

LocalizedEnumType

  • name - LocalizedEnum
  • values - Array of LocalizedEnumValue
    The field value contain the key of the LocalizedEnum.

NumberType

  • name - Number

MoneyType

  • name - Money

DateType

  • name - Date

TimeType

  • name - Time

DateTimeType

  • name - DateTime

ReferenceType

SetType

The set field type defines a set (array without duplicates) with values of the given elementType.

TextInputHint

Provides a visual representation type for this field. It is only relevant for string-based field types like StringType and LocalizedStringType.
A text input hint is a string with one of the following values:

  • SingleLine
  • MultiLine

EnumValue

  • key - String
    The key of the value used as a programmatic identifier.
  • label - String
    A descriptive label of the value.

LocalizedEnumValue

  • key - String
    The key of the value used as a programmatic identifier.
  • label - LocalizedString
    A descriptive, localized label of the value.

Get Type by ID

Endpoint: /{projectKey}/types/{id}
Method: GET
OAuth2 Scopes: view_types:{projectKey}
Response Representation: Type

Get Type by Key

Endpoint: /{projectKey}/types/key={key}
Method: GET
OAuth2 Scopes: view_types:{projectKey}
Response Representation: Type

Query Types

Endpoint: /{projectKey}/types
Method: GET
OAuth2 Scopes: view_types:{projectKey}
Response Representation: PagedQueryResult with the results array of Type
Query Parameters:

Create Type

Endpoint: /{projectKey}/types
Method: POST
OAuth2 Scopes: manage_types:{projectKey}
Request Representation: TypeDraft
Response Representation: Type

Update Type by ID

Endpoint: /{projectKey}/types/{id}
Method: POST
OAuth2 Scopes: manage_types:{projectKey}
Response Representation: Type
Fields:

  • version - Number - Required
    The expected version of the type on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the type.

Update Type by Key

Endpoint: /{projectKey}/types/key={key}
Method: POST
OAuth2 Scopes: manage_types:{projectKey}
Response Representation: Type
Fields:

  • version - Number - Required
    The expected version of the type on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the type.

Update Actions
Please find below the individual update actions provided on this endpoint.


Change Key

  • action - String - "changeKey"
  • key - String - Required

Change Name

Set Description

  • action - String - "setDescription"
  • description - LocalizedString - Optional
    If left blank, the description is removed.

Add FieldDefinition

  • action - String - "addFieldDefinition"
  • fieldDefinition - FieldDefinition - Required

Remove FieldDefinition

  • action - String - "removeFieldDefinition"
  • fieldName - String - Required
    The name of the field to remove.
    The removal of a field definition deletes asynchronously all custom fields using this definition as well.

Change FieldDefinition Label

  • action - String - "changeLabel"
  • fieldName - String - Required
    The name of the field definition to update.
  • label - LocalizedString - Required

Add EnumValue to FieldDefinition

Adds an enum to the values of EnumType. It can update an EnumType field definition or a Set of EnumType field definition.

  • action - String - "addEnumValue"
  • fieldName - String - Required
    The name of the field definition to update.
  • value - EnumValue - Required

Add LocalizedEnumValue to FieldDefinition

Adds an localized enum to the values of LocalizedEnumType. It can update a LocalizedEnumType field definition or a Set of LocalizedEnumType field definition.

  • action - String - "addLocalizedEnumValue"
  • fieldName - String - Required
    The name of the field definition to update.
  • value - LocalizedEnumValue - Required

Change the order of FieldDefinitions

  • action - String - "changeFieldDefinitionOrder"
  • fieldNames - Array of String - Required
    fieldNames must be equal to the type field definition names (except for the order).

Change the order of EnumValues

This action changes the order of enum values in an EnumType field definition. It can update an EnumType field definition or a Set of EnumType field definition.

  • action - String - "changeEnumValueOrder"
  • fieldName - String - Required
  • keys - Array of String - Required
    keys must be equal to the keys of the enum values of the field definition (except for the order).

Change the order of LocalizedEnumValues

This action changes the order of localized enum values in a LocalizedEnumType field definition. It can update a LocalizedEnumType field definition or a Set of LocalizedEnumType field definition.

  • action - String - "changeLocalizedEnumValueOrder"
  • fieldName - String - Required
  • keys - Array of String - Required
    keys must be equal to the keys of the enum values of the field definition (except for the order).

Delete Type

These requests delete a type only if it’s not referenced by other entities.

Delete Type by ID

Endpoint: /{projectKey}/types/{id}
Method: DELETE
OAuth2 Scopes: manage_types:{projectKey}
Query Parameters:

  • version - Number - Required

Delete Type by Key

Endpoint: /{projectKey}/types/key={key}
Method: DELETE
OAuth2 Scopes: manage_types:{projectKey}
Query Parameters:

  • version - Number - Required