Fields and field types

Card key

docs_25

Status

Ready

Card type

base/cardTypes/page

Labels

Owner

N/A

Information classification

public

Introduction

In Cyberismo, a card consists of an AsciiDoc document, stored technically in a text file index.adoc, and metadata stored in a JSON file index.json.

The metadata consists of standard metadata, such as built-in fields, links and labels, and optional custom fields.

A field type defines a name, a display name, and a data type for a custom field of a card.

Standard card metadata fields

The following table documents the standard built-in metadata that can be included in the index.json file of any card regardless of the card type. Notice that you should not edit the index.json files directly, but you should use the Cyberismo app, whenever applicable.

Table 1. Common metadata fields of cards
Property	Type	Description	Required
cardType	`string`	The name of the card type	✓ Yes
title	`string`	A short title of the card	✓ Yes
workflowState	`string`	the name of the card’s current state in the workflow	✓ Yes
labels	`string` `[]`	Labels or tags that can be used for organising cards	No
links	`object` `[]`	links to or from this card to other cards	No

To enable card type specific custom fields, additional properties are allowed. The custom fields are card metadata properties, whose name is a name of a field type.

Managing field types using the Cyberismo command line tool

To see a list of the available workflows, use the following command:

$ cyberismo show fieldTypes

The names of field types are of the format module/fieldTypes/fieldType, for example base/fieldTypes/owner.

To see the help for how to create a field type, use the following command:

$ cyberismo create fieldType --help

To create a new field type, for example a text field myField, use the following command:

$ cyberismo create fieldType myField shortText

In this case, the data type of the new field is shortText.

Cyberismo will create a new file called myField.json in .cards/local/fieldTypes/myField.json. If the card prefix of your Cyberismo project is example, then the full name of the new field type will be example/fieldTypes/myField.

When choosing a name for your field type, see Naming conventions.

To finalise the field type definition, you need to edit the myField.json file with a text editor.

Data types of custom fields

The data type of a custom field must be one of the following values:

shortText: A string that contains a single line of text.
longText: A string that contains a longer text that may have multiple lines.
number: A number that may be a floating point number or an integer (a standard JSON type).
integer: An integral number (a standard JSON type).
boolean: Either true or false (a standard JSON type). In user interfaces, boolean values may be presented by display names Yes and No.
enum: An enumeration. A string that has one of the values defined in a separate enumValues array. In user interfaces, an enum is represented as a selection component (drop down list).
list: An array that contains zero or more strings, where the allowed values are defined in a separate enumValues array. In user interfaces, a list data type is represented as a multiple selection component, where the user can select zero or more of the available options.
date: A date. A date is stored in the index.json file as a string in the ISO 8601 format. For example "2024-01-01".
dateTime: A combination of a date and a time. A dateTime is stored in the index.json file as a string in UTC in the ISO 8601 format. For example "2024-06-09T08:43:25Z".
person: A string that is an email address of a person.

Field type file format

Field types are defined in JSON files that follow the field type schema, as described in the following table.

Table 2. Properties of a field type
Property	Type	Description	Required
name	`string`	The technical name by which the field is referred to.	✓ Yes
displayName	`string`	A name by which the field is referred to in the user interface.	No
fieldDescription	`string`	A longer description of the field type.	No
dataType	`string`	The data type of the field.	✓ Yes
enumValues	`object` `[]`	An array of available enum values. Used for the enum and list data types only.	No

Enum values of a field type

The enumValues property of a field type is an array of available values in selection data types. This property is used for the enum and list data types only. The items of the array are objects that have the following properties:

Table 3. Properties of the items in the enumValues array
Property	Type	Description	Required
enumValue	`string`	A string that represents a possible value for an enum field or for an item in a list array.	✓ Yes
enumDisplayValue	`string`	A display name for the enum value for user interfaces.	No
enumDescription	`string`	A longer description of the enum value.	No