generated from coulomb/repo-seed
tegwick
3ccf841095
Record B2B SaaS subscriber tenancy and Stripe billing source notes. Resolve the Customer Account open question: reject it as canonical, add Commercial Record and Commercial Relationship to the Record and relationship layers, and document Subscriber as a convenience term only.
100 lines
4.3 KiB
Markdown
100 lines
4.3 KiB
Markdown
# Design Principles
|
|
|
|
Status: draft. Refined after IDENTITY-WP-0003 corpus backfill. These principles
|
|
make the proposal's modeling stance explicit. They are constraints for canonical
|
|
vocabulary and conceptual model work, not implementation requirements for
|
|
downstream systems.
|
|
|
|
## P1. Use Actor As The Participation Root
|
|
|
|
Do not start the model with `user`. An Actor is anything that can participate
|
|
in relationships, hold accounts, be represented, or be evaluated by downstream
|
|
systems. Natural persons, organizations, communities, families, and artificial
|
|
agents can all be actors.
|
|
|
|
## P2. Keep Person, Account, Identity, Profile, And Principal Separate
|
|
|
|
A natural person is not an account. An account is not a profile. A profile is
|
|
not a credential. A principal is an authorization projection. A subject is an
|
|
issuer-bound protocol view. These distinctions prevent the most common identity
|
|
model collapse.
|
|
|
|
## P3. Treat Scope As First Class
|
|
|
|
Identifiers, accounts, relationships, roles, policies, and meanings are only
|
|
stable within a scope. A scope may be a tenant, realm, relying party, sector,
|
|
community, application, namespace, or authorization domain.
|
|
|
|
## P4. Model Collective Actors Without Collapsing Them
|
|
|
|
Organizations, legal entities, customers, vendors, communities, families,
|
|
households, groups, and teams are not interchangeable. They may relate to each
|
|
other, but each should keep its social, legal, operational, or commercial
|
|
meaning visible.
|
|
|
|
## P5. Model Relationships Explicitly
|
|
|
|
Membership, affiliation, following, ownership, representation, delegation,
|
|
administration, employment, guardianship, and trust are separate relationship
|
|
types. Do not hide them inside groups, roles, or ad hoc attributes.
|
|
|
|
## P6. Keep Authorization Projections Separate
|
|
|
|
Authorization engines need principals, resources, actions, roles, policies, and
|
|
relationship tuples. These are projections from the conceptual identity model,
|
|
not the whole identity model.
|
|
|
|
## P7. Treat Synonymity As An Assertion
|
|
|
|
Weak matches, verified links, same-as claims, and merges are different. The
|
|
canon should represent synonymity as a scoped, evidenced, revocable assertion
|
|
with confidence and method, never as an automatic destructive merge.
|
|
|
|
## P8. Preserve Source And Evidence
|
|
|
|
Source systems, issuers, import jobs, operators, documents, and verification
|
|
events matter. Claims and relationships should be traceable to evidence or
|
|
source references when the model depends on them.
|
|
|
|
## P9. Prefer Orthogonal Concepts Over Product Terms
|
|
|
|
External systems are mapping targets, not the source of canonical truth. If a
|
|
product calls something a user, organization, group, project, tenant, or realm,
|
|
the canon should identify the underlying concept before adopting the label.
|
|
|
|
## P10. Test Concepts Against Scenarios
|
|
|
|
Every canonical concept should survive concrete scenarios: enterprise
|
|
directories, vendor/customer tenancy, families, communities, social graphs,
|
|
service accounts, delegated agents, weak matches, strong links, and
|
|
pseudonymous profiles. After corpus backfill, all fifteen scenarios in
|
|
`scenarios/ScenarioTests.md` have explicit representation paths in
|
|
`model/ConceptualModel.md`.
|
|
|
|
## P12. Distinguish Assurance Dimensions
|
|
|
|
Identity proofing, authentication, and federation assurance are separable
|
|
dimensions (NIST IAL, AAL, FAL). Do not collapse them into a single "trust
|
|
level" on an account. Record assurance metadata on bindings, credentials, and
|
|
federation relationships where sources provide it.
|
|
|
|
## P14. Separate Commercial Records From Accounts
|
|
|
|
Billing customers (Stripe), CRM accounts (Salesforce), and login accounts are
|
|
different layers. Model billing and commerce artifacts as Commercial Records
|
|
linked to actors and tenants through Commercial Relationships — not as Customer
|
|
Accounts and not by overloading Account.
|
|
|
|
## P13. Prefer Non-Destructive Linking
|
|
|
|
Entity resolution, federation account linking, and semantic web equivalence
|
|
patterns should produce Synonymity Assertions, not silent record merges.
|
|
Probabilistic matches default to weak strength with review lifecycle. Deterministic
|
|
and verified matches may be strong but remain scoped and revocable.
|
|
|
|
## P11. Keep Implementation Recommendations Downstream
|
|
|
|
The repository may recommend downstream schemas, APIs, UI flows, or adapters,
|
|
but it should not implement them directly. Implementation ideas belong in
|
|
`DownstreamRecommendations.md` or a dedicated downstream workplan.
|