Custom directories
A directory, shown as "Directories" in the app, is a small table of reference data that cards can pick from, such as "Data providers" with a name, a contact email and a country. One record defines the table: its name and its fields, the columns. The rows of the table are custom_directory_records, a separate entity because a directory can have many of them.
How the pieces fit:
- this record, the directory with its
fields; custom_directory_records, one per row, each naming the directory indirectory_refand giving the cell of every field invalues, keyed by theexternal_idof the field;- a custom property of type
directory(custom_properties), which lets a card pick a row.
A directory with two fields:
{
"external_id": "dir-providers",
"name": "Data providers",
"fields": [
{ "external_id": "fld-name", "name": "Name", "type": "string", "is_display": true },
{ "external_id": "fld-seats", "name": "Licensed seats", "type": "number" }
]
}One of its rows:
{
"external_id": "rec-nimbus",
"directory_ref": "dir-providers",
"display_value": "Nimbus Analytics",
"values": { "fld-name": "Nimbus Analytics", "fld-seats": 40 }
}A card picks the row through a property of type directory, by the external_id of the row in its properties (only that field of the card is shown):
{
"external_id": "k-mrr",
"properties": { "cp-provider": "rec-nimbus" }
}Files in the package
List every file of this entity in resource_files of the manifest, with "resource": "custom_directories". An entity can have any number of files. See Bundle format.
[
{
"resource": "custom_directories",
"path": "resources/custom_directories.json"
}
]Fields
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string (ExternalId) | Yes | Your own identifier of the record, for example k-mrr, unique within the resource across all of its files and case sensitive. Other records refer to this one by it.Constraints: 1–512 characters. |
name | string | Yes | Name of the directory, for example Data providers. Up to 255 characters.Constraints: 1–255 characters. |
author_ref | Ref<users>? refers to Users | No | The user who created the record, by the external_id of a users record, for example u-ava. Leave it out or use null when the author is unknown or has left. |
condition | enum | No | Whether the record is active (the default) or inactive.Constraints: one of active, inactive. Default: |
created_at | Timestamp | No | When the record was created, with a time zone, for example 2026-01-12T09:30:00Z.Constraints: RFC 3339 with a time zone. Default: |
description | string? | No | A short note about what the directory holds. |
fields | object[] refers to Custom directories or Custom properties | No | The fields (columns) of the directory, in the order they are shown: the first item is the first column. Each item has its own external_id, which the values of the directory's records use as a key. Left out, the directory has no fields. At most one field is the display field: its value is the text shown for a record in lists.Rule: At most one is_display field. |
fields[].external_id | string (ExternalId) | Yes | Your own identifier of the field, for example fld-name, unique among the fields of all directories of the package and case sensitive. The values of a directory record name the field by it.Constraints: 1–512 characters. |
fields[].name | string | Yes | Name of the field, for example Country. Up to 255 characters.Constraints: 1–255 characters. |
fields[].type | enum | Yes | What the field holds: checkbox, date, directory_link (a row of another directory), email, file, number, phone, select, string (text), url or user.Constraints: one of checkbox, date, directory_link, email, file, number, phone, select, string, url, user. |
fields[].custom_property_ref | Ref<custom_properties> refers to Custom properties | When type is select or user | For a select or user field: the custom property whose options the field offers, for example cp-priority. Give the external_id of a custom_properties record; required for these two types and not allowed for others.Constraints: 1–512 characters. |
fields[].linked_directory_ref | Ref<custom_directories> refers to Custom directories | When type is directory_link | For a directory_link field: the directory whose records the field links to, for example Countries. Give the external_id of a custom_directories record; required for this type and not allowed for others.Constraints: 1–512 characters. |
fields[].condition | enum | No | Whether the field is in use: active (the default) or inactive. An inactive field is left out of the directory's fields.Constraints: one of active, inactive. |
fields[].is_display | boolean | No | Whether this field gives each record its title: the text shown for the record in lists and when a card picks it, for example the Name field. At most one field per directory. |
fields[].required | boolean | No | Whether every record of the directory must have this field filled in. The default is false. |
References
Referenced by
- Custom directories:
fields[].linked_directory_ref - Custom directory records:
directory_ref,values - Custom properties:
directory_ref
Custom directories
Refers to
author_ref→ Usersfields[].custom_property_ref→ Custom propertiesfields[].linked_directory_ref→ Custom directories
Show on the entity map
Example
A record of this entity:
{
"external_id": "dir-providers",
"name": "Data providers",
"description": "Vendors that deliver data to the warehouse.",
"fields": [
{
"external_id": "fld-name",
"name": "Name",
"type": "string",
"is_display": true,
"required": true
},
{
"external_id": "fld-email",
"name": "Contact email",
"type": "email"
},
{
"external_id": "fld-seats",
"name": "Licensed seats",
"type": "number"
},
{
"external_id": "fld-since",
"name": "Partner since",
"type": "date"
},
{
"external_id": "fld-tier",
"name": "Tier",
"type": "select",
"custom_property_ref": "cp-priority"
},
{
"external_id": "fld-owner",
"name": "Account owner",
"type": "user",
"custom_property_ref": "cp-steward"
},
{
"external_id": "fld-parent",
"name": "Parent company",
"type": "directory_link",
"linked_directory_ref": "dir-providers"
}
],
"author_ref": "u-ava"
}Rules
- custom_property_ref is given for select and user fields and only for them.
- linked_directory_ref is given for directory_link fields and only for them.
- Among the items of
fieldsof one record, at most 1 can have is_display = true.
Related entities
Custom directory records, Custom properties
Check after the import
After the import, the records of this entity can be checked on Custom directories › Get list of custom directories and Custom directory fields › Get list of fields.
JSON Schema
custom_directories.json
