Notion: databases, data sources and pages
The practical consequences of Notion’s database/data-source split for schema discovery, page creation and integration identity.
- Database container
- Selected source and schema
- Pages and property values
Investigation question
Why does a database ID no longer identify every table-shaped operation in Notion? The 2025-09-03 API model separates the visible database container from its data sources. This investigation follows the consequences for an integration that previously assumed one database meant one schema.
Observed
Notion’s upgrade guide introduces the separation between database containers and data sources. A database can contain multiple data sources. A data source owns its property schema, and pages are records under that source whose property values must conform to the schema. The reference offers separate operations for retrieving and querying a data source. This is an API-model distinction, not simply a display rename. Container identity, table/schema identity and page identity now answer different questions. A request written around the older one-to-one assumption needs an explicit source-selection step when more than one source is possible.
Inferred
A client should not silently choose the first source returned by a container and assume it represents the user’s intended table. Persist the selected data-source ID with the integration’s mapping. If that source becomes unavailable or changes, surface the mismatch instead of writing into a different source that happens to be visible. Property names are another layer of identity. A user-facing label can change while the application still needs to understand which property its mapping refers to. Schema discovery and validation should be explicit parts of an upgrade rather than incidental consequences of the first write.
Unknown & limitations
The article addresses the cited 2025-09-03 model change rather than every later Notion API feature. It does not reproduce workspace permissions, concurrent schema edits or a multi-source migration. No private workspace content or undocumented client protocol is included. Verify the actual API revision and the chosen source’s schema before applying the model to a live integration.
Domain & data models
Conceptual model: database container → one or more data sources → pages. The container organizes sources; each source supplies a schema; each page supplies values for that schema. An integration configuration should identify the layer it stores instead of calling all three objects “database.”
Workflows & state machines
Illustrative scenario: an integration used to store a database ID for a task table. After the model change, the containing database offers Tasks and Milestones as separate sources. The client must identify the intended source, retrieve its schema and validate its field mapping before it queries or creates pages. Choosing whichever source appears first could produce valid requests against the wrong table. A bounded upgrade test would retrieve the container, enumerate accessible sources, select one explicitly, read its schema, and query a small known set of pages. Check behavior when the configured source is missing or access is removed. This is a proposed test, not an operation performed on a user workspace.