Metadata that controls how a database property behaves.

Database properties

Each database property object contains the following keys. In addition, it must contain a key corresponding with the value of type. The value is an object containing type-specific configuration. The type-specific configurations are described in the sections below.

Property

Type

Description

Example value

id

string

The ID of the property, usually a short string of random letters and symbols.
Some automatically generated property types have special human-readable IDs. For example, all Title properties have an ID of "title".

"fy:{"

type

string (enum)

Type that controls the behavior of the property. Possible values are: "title", "rich_text", "number", "select", "multi_select", "date", "people", "files", "checkbox", "url", "email", "phone_number", "formula", "relation", "rollup", "created_time", "created_by", "last_edited_time", "last_edited_by", "status".

"rich_text"

name

string

The name of the property as it appears in Notion.

Title configuration

Each database must have exactly one database property of type "title". This database property controls the title that appears at the top of the page when the page is opened. Title database property objects have no additional configuration within the title property.

Text configuration

Text database property objects have no additional configuration within the rich_text property.

Number configuration

Number database property objects contain the following configuration within the number property:

Property

Type

Description

Example value

format

string (enum)

How the number is displayed in Notion. Potential values include: number, number_with_commas, percent, dollar, canadian_dollar, euro, pound, yen, ruble, rupee, won, yuan, real, lira, rupiah, franc, hong_kong_dollar, new_zealand_dollar, krona, norwegian_krone, mexican_peso, rand, new_taiwan_dollar, danish_krone, zloty, baht, forint, koruna, shekel, chilean_peso, philippine_peso, dirham, colombian_peso, riyal, ringgit, leu, argentine_peso, uruguayan_peso.

"percent"

Select configuration

Select database property objects contain the following configuration within the select property:

Property

Type

Description

Example value

options

array of select option objects.

Sorted list of options available for this property.

Select options

Property

Type

Description

Example value

name

string

Name of the option as it appears in Notion.

Note: Commas (",") are not valid for select values.

"Fruit"

id

string

Identifier of the option, which does not change if the name is changed. These are sometimes, but not always, UUIDs.

"ff8e9269-9579-47f7-8f6e-83a84716863c"

color

string (enum)

Color of the option. Possible values include: default, gray, brown, orange, yellow, green, blue, purple, pink, red.

"red"

Status configuration

Property

Type

Description

Example value

options

array of status option objects.

Sorted list of options available for this property.

groups

array of status group objects.

Sorted list of groups available for this property.

Status options

Property

Type

Description

Example value

name

string

Name of the option as it appears in Notion.

Note: Commas (",") are not valid for select values.

"Fruit"

id

string

Identifier of the option, which does not change if the name is changed. These are sometimes, but not always, UUIDs.

"ff8e9269-9579-47f7-8f6e-83a84716863c"

color

string (enum)

Color of the option. Possible values include: default, gray, brown, orange, yellow, green, blue, purple, pink, red.

"red"

Status groups

Property

Type

Description

Example value

name

string

Name of the option as it appears in Notion.

Note: Commas (",") are not valid for select values.

"Fruit"

id

string

Identifier of the option, which does not change if the name is changed. These are sometimes, but not always, UUIDs.

"ff8e9269-9579-47f7-8f6e-83a84716863c"

color

string (enum)

Color of the option. Possible values include: default, gray, brown, orange, yellow, green, blue, purple, pink, red.

"red"

option_ids

array of string (UUID)

Sorted list of ids of all options that belong to a group.

Multi-select configuration

Multi-select database property objects contain the following configuration within the multi_select property:

Property

Type

Description

Example value

options

array of multi-select option objects.

Settings for multi select properties.

Multi-select options

Property

Type

Description

Example value

name

string

Name of the option as it appears in Notion.

Note: Commas (",") are not valid for select values.

"Fruit"

id

string

Identifier of the option, which does not change if the name is changed. These are sometimes, but not always, UUIDs.

"ff8e9269-9579-47f7-8f6e-83a84716863c"

color

string (enum)

Color of the option. Possible values include: default, gray, brown, orange, yellow, green, blue, purple, pink, red.

"red"

Date configuration

Date database property objects have no additional configuration within the date property.

People configuration

People database property objects have no additional configuration within the people property.

Files configuration

Files database property objects have no additional configuration within the files property.

Checkbox configuration

Checkbox database property objects have no additional configuration within the checkbox property.

URL configuration

URL database property objects have no additional configuration within the url property.

Email configuration

Email database property objects have no additional configuration within the email property.

Phone number configuration

Phone number database property objects have no additional configuration within the phone_number property.

Formula configuration

Formula database property objects contain the following configuration within the formula property:

Property

Type

Description

Example value

expression

string

Formula to evaluate for this property. You can read more about the syntax for formulas in the help center.

"if(prop(\"In stock\"), 0, prop(\"Price\"))"

Relation configuration

Relation database property objects contain the following configuration within the relation property. In addition, they must contain a key corresponding with the value of type. The value is an object containing type-specific configuration. The type-specific configurations are defined below.

Property

Type

Description

Example value

database_id

string (UUID)

The database this relation refers to. New linked pages must belong to this database in order to be valid.

"668d797c-76fa-4934-9b05-ad288df2d136"

type

string (optional enum)

The type of the relation. Can be "single_property" or "dual_property".

"single_property"

Single property relation configuration

Single property relation objects have no additional configuration within the single_property property.

Dual property relation configuration

Dual property relation objects contain the following configuration within the dual_property property:

Property

Type

Description

Example value

synced_property_name

string

The relation is formed as two synced properties. If you make a change to one property, it updates the other property at the same time. synced_property_name
refers to the name
of the related property.

"Ingredients"

synced_property_id

string

The relation is formed as two synced properties. If you make a change to one property, it updates the other property at the same time. synced_property_id refers to the id
of the related property. This is usually a short string of random letters and symbols.

"fy:{"

Rollup configuration

Rollup database property objects contain the following configuration within the rollup property:

Property

Type

Description

Example value

relation_property_name

string

The name of the relation property this property is responsible for rolling up.

"Meals"

relation_property_id

string

The id of the relation property this property is responsible for rolling up.

"fy:{"

rollup_property_name

string

The name of the property of the pages in the related database that is used as an input to function.

"Name"

rollup_property_id

string

The id of the property of the pages in the related database that is used as an input to function.

"fy:{"

function

string (enum)

The function that is evaluated for every page in the relation of the rollup.
Possible values include: count_all, count_values, count_unique_values, count_empty, count_not_empty, percent_empty, percent_not_empty, sum, average, median, min, max, range, show_original

"count_unique_values"

Created time configuration

Created time database property objects have no additional configuration within the created_time property.

Created by configuration

Created by database property objects have no additional configuration within the created_by property.

Last edited time configuration

Last edited time database property objects have no additional configuration within the last_edited_time property.

Last edited by configuration

Last edited by database property objects have no additional configuration within the last_edited_by property.