Skip to content
Sarj Standards

Python · correctness

prefer-nominal-id-types

python:prefer-nominal-id-types

Production boundaries with multiple ID roles must distinguish them with nominal types.

Code
SARJ093
Default
error
Fix
none
Languages
python

Why

Primitive carriers such as str, int, and UUID allow distinct identifier roles to be swapped without a type-checking error.

Fix

Define or reuse NewType identifier types and propagate them through the boundary.

Before / after

Executed by this rule’s unit tests.

Before

Distinct ID roles share a primitive type

app/services/files.py · focus
def move(file_id: str, parent_folder_id: str) -> None: ...

After

Distinct ID roles use nominal types

app/services/files.py · focus
def move(file_id: FileId, parent_folder_id: FolderId) -> None: ...

Limits

  • The rule checks public module functions, classes, direct methods, and constructors with at least two ID-shaped roles.
  • Tests, generated code, migrations, helpers, external adapters, operational IDs, raw schemas, ambiguous containers, and private callbacks are excluded.