identity-canon/DownstreamRecommendations.md

Downstream Recommendations

Status: draft. This file captures implementation ideas derived from the canon without moving implementation work into this repository.

Recommended Consumption Pattern

Downstream repositories should consume identity-canon as a conceptual reference. They should map their schemas, APIs, CLI commands, UI labels, and authorization policies to canonical terms, but they should not depend on this repository as a runtime package unless a later explicit package is extracted.

Near-Term Recommendations

• When designing user-management schemas, separate Natural Person, Account, Profile, Credential, and Principal fields.
• When designing tenant-aware systems, model Tenant as a scope and relate it to Organization, Customer, Vendor, and Realm explicitly.
• When designing organization features, do not reuse Group or Role as a generic replacement for Organization.
• When designing authorization adapters, treat Principal and relationship tuples as projections from canonical actors, accounts, and relationships.
• When designing account-linking features, store Synonymity Assertions with source, evidence, confidence, scope, lifecycle state, and privacy controls.
• When designing UI copy, use product-friendly labels but maintain internal mappings to canonical concepts.

Avoid For Now

• Do not implement identity provider integrations in this repository.
• Do not add database migrations or production APIs here.
• Do not treat this glossary as a finalized schema.
• Do not use user as a canonical table, API, or class name without a mapping note that explains which canonical concept it represents.