Lists

A StandardList defines a fixed set of named values for a LIST-typed field. Each item has a key and optional colors for UI rendering.

Definition

{
  "name": "my-project.contractType",
  "items": [
    { "key": "permanent", "color": "#1a7f37", "backgroundColor": "#dafbe1" },
    { "key": "fixedTerm", "color": "#9a6700", "backgroundColor": "#fff8c5" },
    { "key": "freelance", "color": "#0969da", "backgroundColor": "#ddf4ff" }
  ]
}

Property	Type	Description
name	QualifiedName	Unique identifier for this list, used to reference it from fields.
items	StandardListItem[]	The available values in this list.

StandardListItem

Property	Type	Description
key	string	The stored value. Must be unique within the list.
color	string	CSS color value. See rendering behaviour below.
backgroundColor	string	CSS background color. See rendering behaviour below.

Color rendering behaviour

How a list item is rendered in the UI depends on which color properties are set:

color	backgroundColor	Rendering
—	—	Plain text
set	—	Small colored dot next to the text
set	set	Text in color on a backgroundColor background (badge)

Only add colors when they carry meaning. A priority or severity list benefits from color; a list of contract types or categories usually does not.

Referencing a list from a field

Set dataType to LIST and list to the qualified name of the StandardList:

{
  "name": "contractType",
  "dataType": "LIST",
  "list": "my-project.contractType"
}

Where to define lists

Lists are defined in the lists array of any class file. A list can be referenced by any class in the same namespace, regardless of which file it is defined in.

Cross-file list references

Define the list once in the file where it belongs logically, then reference it by qualified name from any other class. In this example my-project.ticketPriority is defined on serviceTicket.json and reused by my-project.changeRequest in a separate file:

serviceTicket.json — defines the list:

{
  "version": 1,
  "class": "my-project.serviceTicket",
  "kind": "ABSTRACT",
  "inherits": "commons.dossier",

  "fields": [
    { "name": "priority", "dataType": "LIST", "list": "my-project.ticketPriority" }
  ],

  "lists": [
    {
      "name": "my-project.ticketPriority",
      "items": [
        { "key": "low",    "color": "#1a7f37", "backgroundColor": "#dafbe1" },
        { "key": "medium", "color": "#9a6700", "backgroundColor": "#fff8c5" },
        { "key": "high",   "color": "#cf222e", "backgroundColor": "#ffebe9" }
      ]
    }
  ]
}

changeRequest.json — references the same list without redefining it:

{
  "version": 1,
  "class": "my-project.changeRequest",
  "kind": "BASIC",
  "inherits": "my-project.serviceTicket",

  "fields": [
    { "name": "impactLevel", "dataType": "LIST", "list": "my-project.ticketPriority" }
  ]
}

{
  "version": 1,
  "class": "my-project.employmentAgreement",
  "kind": "BASIC",
  "inherits": "commons.agreement",

  "fields": [
    { "name": "contractType", "dataType": "LIST", "list": "my-project.contractType" }
  ],

  "lists": [
    {
      "name": "my-project.contractType",
      "items": [
        { "key": "permanent",  "color": "#1a7f37", "backgroundColor": "#dafbe1" },
        { "key": "fixedTerm",  "color": "#9a6700", "backgroundColor": "#fff8c5" },
        { "key": "freelance",  "color": "#0969da", "backgroundColor": "#ddf4ff" }
      ]
    }
  ]
}