0
# Collections
1

2
Type definitions for Notion databases (collections) including schemas, properties, and data validation. Collections represent structured data with typed properties and validation rules.
3

4
## Capabilities
5

6
### Collection Interface
7

8
Main interface representing a Notion database/collection.
9

10
```typescript { .api }
11
/**
12
 * Database/collection definition
13
 */
14
interface Collection {
15
  /** Collection identifier */
16
  id: ID;
17
  /** Collection version */
18
  version: number;
19
  /** Collection name (decorated text) */
20
  name: Decoration[];
21
  /** Property schema definitions */
22
  schema: CollectionPropertySchemaMap;
23
  /** Collection icon */
24
  icon: string;
25
  /** Parent block ID */
26
  parent_id: ID;
27
  /** Parent table type */
28
  parent_table: string;
29
  /** Whether collection is active */
30
  alive: boolean;
31
  /** Source collection if copied */
32
  copied_from: string;
33
  /** Template page IDs */
34
  template_pages?: ID[];
35
  /** Collection formatting */
36
  format?: {
37
    collection_page_properties?: Array<{
38
      property: string;
39
      visible: boolean;
40
    }>;
41
    property_visibility?: Array<{
42
      property: string;
43
      visibility: 'show' | 'hide';
44
    }>;
45
    hide_linked_collection_name?: boolean;
46
  };
47
}
48
```
49

50
### Property Schema System
51

52
```typescript { .api }
53
/**
54
 * Schema definition for collection properties
55
 */
56
interface CollectionPropertySchema {
57
  /** Property name */
58
  name: string;
59
  /** Property data type */
60
  type: PropertyType;
61
  /** Options for select properties */
62
  options?: SelectOption[];
63
  /** Formatting for number properties */
64
  number_format?: NumberFormat;
65
  /** Formula definition for formula properties */
66
  formula?: Formula;
67
}
68

69
/**
70
 * Map of property schemas
71
 */
72
interface CollectionPropertySchemaMap {
73
  [key: string]: CollectionPropertySchema;
74
}
75

76
/**
77
 * Option for select/multi-select properties
78
 */
79
interface SelectOption {
80
  /** Option identifier */
81
  id: string;
82
  /** Option color */
83
  color: Color;
84
  /** Option display text */
85
  value: string;
86
}
87
```
88

89
### Property Types
90

91
```typescript { .api }
92
/**
93
 * Types of structured data supported by Notion collections
94
 */
95
type PropertyType =
96
  | 'title'              // Title/primary text
97
  | 'text'               // Plain text
98
  | 'number'             // Numeric values
99
  | 'select'             // Single select dropdown
100
  | 'status'             // Status property
101
  | 'multi_select'       // Multi-select dropdown
102
  | 'auto_increment_id'  // Auto-incrementing ID
103
  | 'date'               // Date/datetime
104
  | 'person'             // User reference
105
  | 'file'               // File attachment
106
  | 'checkbox'           // Boolean checkbox
107
  | 'url'                // URL/link
108
  | 'email'              // Email address
109
  | 'phone_number'       // Phone number
110
  | 'formula'            // Computed formula
111
  | 'relation'           // Relation to other collection
112
  | 'created_time'       // Creation timestamp
113
  | 'created_by'         // Creator user
114
  | 'last_edited_time'   // Last edit timestamp
115
  | 'last_edited_by';    // Last editor user
116
```
117

118
### Number Formatting
119

120
```typescript { .api }
121
/**
122
 * Types of number formatting supported by Notion
123
 */
124
type NumberFormat =
125
  // Basic formats
126
  | 'number_with_commas'
127
  | 'percent'
128
  | 'number'
129
  
130
  // Major currencies
131
  | 'dollar'
132
  | 'euro'
133
  | 'pound'
134
  | 'yen'
135
  | 'rupee'
136
  | 'won'
137
  | 'yuan'
138
  
139
  // Regional currencies
140
  | 'argentine_peso'
141
  | 'baht'
142
  | 'canadian_dollar'
143
  | 'chilean_peso'
144
  | 'colombian_peso'
145
  | 'danish_krone'
146
  | 'dirham'
147
  | 'forint'
148
  | 'franc'
149
  | 'hong_kong_dollar'
150
  | 'koruna'
151
  | 'krona'
152
  | 'leu'
153
  | 'lira'
154
  | 'mexican_peso'
155
  | 'new_taiwan_dollar'
156
  | 'new_zealand_dollar'
157
  | 'norwegian_krone'
158
  | 'philippine_peso'
159
  | 'peruvian_sol'
160
  | 'rand'
161
  | 'real'
162
  | 'ringgit'
163
  | 'riyal'
164
  | 'ruble'
165
  | 'rupiah'
166
  | 'shekel'
167
  | 'singapore_dollar'
168
  | 'uruguayan_peso'
169
  | 'zloty';
170
```
171

172
**Usage Examples:**
173

174
```typescript
175
import { 
176
  Collection, 
177
  CollectionPropertySchema, 
178
  PropertyType, 
179
  NumberFormat,
180
  SelectOption 
181
} from "notion-types";
182

183
// Define select options
184
const statusOptions: SelectOption[] = [
185
  { id: "1", color: "green", value: "Active" },
186
  { id: "2", color: "yellow", value: "Pending" },
187
  { id: "3", color: "red", value: "Inactive" }
188
];
189

190
// Define property schema
191
const userSchema: CollectionPropertySchemaMap = {
192
  title: {
193
    name: "Name",
194
    type: "title"
195
  },
196
  email: {
197
    name: "Email",
198
    type: "email"
199
  },
200
  age: {
201
    name: "Age",
202
    type: "number",
203
    number_format: "number"
204
  },
205
  salary: {
206
    name: "Salary",
207
    type: "number",
208
    number_format: "dollar"
209
  },
210
  status: {
211
    name: "Status",
212
    type: "select",
213
    options: statusOptions
214
  },
215
  skills: {
216
    name: "Skills",
217
    type: "multi_select",
218
    options: [
219
      { id: "js", color: "yellow", value: "JavaScript" },
220
      { id: "ts", color: "blue", value: "TypeScript" },
221
      { id: "py", color: "green", value: "Python" }
222
    ]
223
  },
224
  active: {
225
    name: "Active",
226
    type: "checkbox"
227
  },
228
  hire_date: {
229
    name: "Hire Date",
230
    type: "date"
231
  },
232
  manager: {
233
    name: "Manager",
234
    type: "person"
235
  },
236
  website: {
237
    name: "Website",
238
    type: "url"
239
  }
240
};
241

242
// Create a collection
243
const usersCollection: Collection = {
244
  id: "collection-123",
245
  version: 1,
246
  name: [["Users Database"]],
247
  schema: userSchema,
248
  icon: "👥",
249
  parent_id: "page-456",
250
  parent_table: "block",
251
  alive: true,
252
  copied_from: "",
253
  template_pages: [],
254
  format: {
255
    collection_page_properties: [
256
      { property: "title", visible: true },
257
      { property: "email", visible: true },
258
      { property: "status", visible: true }
259
    ],
260
    property_visibility: [
261
      { property: "age", visibility: "show" },
262
      { property: "salary", visibility: "hide" }
263
    ]
264
  }
265
};
266

267
// Type-safe property access
268
function getPropertyType(collection: Collection, propertyId: string): PropertyType | undefined {
269
  return collection.schema[propertyId]?.type;
270
}
271

272
// Validate property schema
273
function validateProperty(schema: CollectionPropertySchema): boolean {
274
  if (schema.type === 'select' || schema.type === 'multi_select') {
275
    return Array.isArray(schema.options) && schema.options.length > 0;
276
  }
277
  if (schema.type === 'number') {
278
    return schema.number_format !== undefined;
279
  }
280
  return true;
281
}
282
```