Notion Policy & Guardrails

Contract

Enforces the governance conventions for Notion integrations: integration/token names, token rotation windows, database property naming, and access-audit thresholds. Apply whenever you name a Notion integration token, design or review a Notion database's properties, or write a Notion access-audit script. These are fixed organizational choices — do not substitute your own sensible-looking defaults.

Rules

1. Integration / token names

• Format is exactly {team}-{env}-{purpose}: three lowercase ASCII segments

joined by single hyphens, matching ^[a-z]+-[a-z]+-[a-z]+$.

• The middle segment is the environment and MUST be one of exactly dev,

staging, prod. Never development, production, test, qa, stage, prd, stg.

• All lowercase. No spaces, no camelCase, no underscores, no PascalCase, no digits.
• The environment is always the middle segment — not first, not last.
• Canonical examples: eng-prod-sync, marketing-staging-cms, data-prod-etl,

design-dev-prototype.

2. Token rotation

• Maximum rotation window is 90 days from creation. Set rotateBy to exactly

the creation date plus 90 days.

• Emit a WARNING when fewer than 14 days remain before rotateBy.
• Emit EXPIRED once rotateBy has passed.

3. Database property names

• Title / name properties: PascalCase (e.g. Name, Title, Published Date).
• A status-type property MUST be named exactly one of Status, Stage, or

State. Never Deal Stage, Pipeline Status, Phase, Progress, Workflow.

• Date properties: the name MUST end with Date or At (e.g. Due Date,

Created At, Last Modified At). A bare Deadline, Created, or Updated is non-compliant.

• Relation properties: the name MUST start with Related or Parent

(e.g. Parent Project, Related Docs).

• Multi-select properties: the name MUST be plural, ending in s

(e.g. Categories, Labels, Tags).

• Banned property names (too generic): Data, Info, Stuff, Other,

Misc, Notes2. Replace with a descriptive name.

• Every database MUST have exactly one title property.

4. Access audit

• Flag any integration with access to more than 1000 items; recommend

narrowing the sharing scope.

• Flag any page exposing a public_url as publicly shared.
• Between paginated search calls, sleep 350ms to respect rate limits.

Worked examples

Each pair shows the base model's likely default (BEFORE) and the conforming form (AFTER).

Integration name — production sync for engineering

• BEFORE: EngProdSync or eng_production_sync
• AFTER: eng-prod-sync

Integration name — environment placement

• BEFORE: eng-sync-prod (env pushed to the last segment)
• AFTER: eng-prod-sync (env is the middle segment)

Integration name — environment vocabulary

• BEFORE: eng-production-sync (production is not an allowed env word)
• AFTER: eng-prod-sync

Integration name — non-standard environment

• BEFORE: qa-team-bot for a QA/pre-release connector
• AFTER: qa-staging-cms — QA maps onto the allowed env staging; never invent

qa or test as the middle segment.

Token rotation entry — created today

• BEFORE: "rotate when convenient" / a 1-year expiry
• AFTER: rotateBy = createdDate + 90 days; begin emitting WARNING once fewer

than 14 days remain.

Status property

• BEFORE: Deal Stage (select) on a sales database
• AFTER: Stage (select) — the status-type property must be exactly Status,

Stage, or State.

Date property

• BEFORE: Deadline (date)
• AFTER: Review Deadline Date (date) — must end with Date or At.

Last-modified timestamp

• BEFORE: Modified (date)
• AFTER: Last Modified At (date).

Multi-select property

• BEFORE: Category (multi_select)
• AFTER: Categories (multi_select) — plural, ending in s.

Relation property

• BEFORE: Project (relation) linking a subtask to its project
• AFTER: Parent Project (relation) — must start with Parent or Related .

Relation to reference docs

• BEFORE: Docs (relation)
• AFTER: Related Docs (relation).

Banned generic name

• BEFORE: Info to hold "miscellaneous details"
• AFTER: a descriptive name such as Contact Notes or Account Summary; Info,

Data, Stuff, Misc, Other, Notes2 are all banned.

Access audit threshold

• BEFORE: a script that only warns above 10,000 items, or never
• AFTER: warn as soon as accessible items exceed 1000, and recommend narrowing

scope.

Audit pagination throttle

• BEFORE: a tight while (has_more) loop with no delay
• AFTER: sleep(350ms) between successive search calls.

Edge cases & exceptions

• QA / UAT / pre-prod environments have no dedicated token: map them onto the

closest allowed value (staging for QA/UAT/pre-release, dev for local scratch work). Never widen the env vocabulary.

• Multi-word teams or purposes must collapse to a single lowercase segment

with no separator (dataeng-prod-etl, not data-eng-prod-etl) — the regex permits only three segments.

• A date property that is also the title (rare) still follows the title

PascalCase rule; the Date/At suffix rule applies to non-title date properties.

• status vs select Notion type: the name rule (Status/Stage/State)

applies regardless of whether the underlying Notion type is select or the native status type.

• Legacy integrations that predate the policy keep their names only with an

explicit exceptions list and a migration deadline — new names never get a pass.

• object_not_found mid-audit (a page was unshared since the last run) is

expected: log and continue, do not abort the audit.

Do / Don't

• DON'T use production/development/test/qa as the env segment. DO use

exactly dev, staging, or prod.

• DON'T put the environment first or last. DO keep it as the middle segment.
• DON'T name a status property Deal Stage or Pipeline Status. DO name it

exactly Status, Stage, or State.

• DON'T leave a date property as a bare Deadline/Created. DO suffix it with

Date or At.

• DON'T name a relation property after the bare target (Project, Docs). DO

prefix it with Parent or Related .

• DON'T use a singular multi-select name (Category). DO pluralize it

(Categories).

• DON'T accept generic names like Info/Data/Misc/Notes2. DO require a

descriptive name.

• DON'T set a 1-year token expiry. DO cap rotation at 90 days and warn under 14.

Common mistakes

• Spelling out the environment (eng-production-sync) — the base prefers full

words; the policy requires the short forms dev/staging/prod.

• Defaulting to camelCase or PascalCase integration names (engProdSync) instead

of lowercase-hyphenated.

• Reordering segments so the environment lands last (eng-sync-prod).
• Naming a sales pipeline property Deal Stage or Pipeline Status because it

reads naturally — the vocabulary is fixed to Status/Stage/State.

• Using bare date names (Deadline, Created) without the Date/At suffix.
• Leaving multi-selects singular (Tag, Label).
• Picking a vague catch-all column (Info, Notes2) instead of a specific name.
• Setting no rotation window, or one far longer than 90 days.

Quick checklist

• ] Token name matches ^[a-z]+-[a-z]+-[a-z]+$, env in the middle.
• ] Env segment is exactly dev, staging, or prod.
• ] rotateBy = created + 90 days; warn under 14 days.
• ] Status property named exactly Status/Stage/State.
• ] Date properties end with Date or At.
• ] Relation properties start with Parent or Related .
• ] Multi-selects are plural (end in s).
• ] No banned generic names; exactly one title property per database.
• ] Audit flags >1000 items and any public_url; 350ms between searches.