Skip to content
Sarj Code Standards

prefer-nominal-mapping-keys

Declare record shapes or nominal keys at primitive-keyed mapping boundaries.

SARJ568 Rule source Tests Catalog JSON

Why

A primitive mapping erases both fixed record keys and the domain identity of dynamic keys.

Fix

Use a TypedDict or validated model for a fixed record; for a dynamic domain mapping use a nominal NewType identifier or enum key. Preserve intentionally open transport and algorithm contracts with a reasoned local exception.

Examples

Before — flagged The contract is implicit
app/service.py
class Report:
    timings: dict[str, float]
After — preferred The contract is explicit
app/service.py
from typing import TypedDict




class Timings(TypedDict):
    total: float




class Report:
    timings: Timings