identity-canon/INTENT.md

INTENT.md

Purpose

identity-canon exists to research, clarify, and define a canonical terminology and conceptual data model for identity, user, organization, community, and relationship management across multi-tenant, multi-vendor, multi-community systems.

The project is intentionally focused on the research and terminology layer. It does not implement user management, identity provisioning, authentication, authorization, or UI workflows directly. Instead, it provides the conceptual foundation that later implementation projects can rely on.

Core Intent

The core intent is to develop a clear, orthogonal vocabulary and canonical model for describing:

• natural persons, users, accounts, identities, personas, and profiles
• organizations, enterprises, sub-organizations, vendors, tenants, customers, and legal entities
• communities, families, households, teams, spontaneous groups, and social graphs
• actors, agents, bots, service accounts, and delegated representatives
• memberships, affiliations, followers, ownership, representation, delegation, and trust relationships
• weak and strong synonymity between identities, accounts, identifiers, and real-world actors
• the distinction between social, legal, operational, and authorization-relevant relationships

The project should help avoid the common collapse of overloaded terms such as user, group, role, tenant, organization, account, and identity.

Strategic Role

identity-canon is a reference project for future identity-related systems and implementation repositories.

It should provide:

1. a researched corpus of relevant standards, concepts, and terminology;
2. a canonical vocabulary suitable for humans and agents;
3. a conceptual model for user, organization, community, and identity management;
4. a basis for later schemas, APIs, CLI tools, UI workflows, and adapter implementations;
5. a shared language for connecting IAM, social graph, enterprise directory, community, family, and authorization concepts.

The repository should serve as a stable conceptual anchor before implementation-specific decisions are made.

Intended Users

The primary users of this repository are:

• system architects designing multi-tenant identity and user-management systems;
• developers implementing user, organization, tenant, and community management components;
• security and IAM engineers integrating systems such as Keycloak, Keycape, LLDAP, Authelia, privacyIDEA, OpenBao, SCIM, OIDC, SAML, LDAP, OpenFGA, Cedar, or related tools;
• product designers creating CLI and UI workflows for managing users, organizations, communities, and relationships;
• AI agents that need a precise terminology reference when generating schemas, documentation, workflows, or implementation plans.

Scope

identity-canon covers research, terminology, and conceptual modeling.

In scope:

• literature and standards research;
• terminology analysis;
• canonical concept definitions;
• comparison of overlapping terms across IAM, directory services, social graphs, enterprise systems, and authorization models;
• conceptual diagrams and model descriptions;
• model constraints and design principles;
• synonymity and entity-resolution concepts;
• scope, tenant, organization, community, family, and group distinctions;
• relationship semantics such as membership, affiliation, representation, delegation, following, ownership, and trust;
• recommendations for future implementation repositories.

Out of scope:

• implementation code;
• production APIs;
• database migrations;
• UI components;
• CLI commands;
• adapter implementations;
• direct integration with Keycloak, LDAP, SCIM, OIDC, SAML, OpenFGA, or other systems;
• operational identity lifecycle tooling.

Implementation repositories may later consume the results of identity-canon, but this repository remains implementation-neutral.

Design Principles

1. Do not start with “user”

The term user is overloaded. The canonical model should avoid using user as the root concept. Instead, it should distinguish actors, natural persons, accounts, identities, profiles, personas, credentials, and principals.

2. Separate social, legal, operational, and authorization semantics

An organization may be a legal entity, a tenant, a community, a billing customer, an employer, a vendor, or an authorization scope — but these meanings must not be collapsed into one concept.

3. Model relationships explicitly

Membership, affiliation, following, ownership, representation, delegation, administration, and trust should be modeled as distinct relationship types, not hidden inside groups or roles.

4. Treat synonymity as an assertion, not a destructive merge

Weak and strong synonymity should be represented as scoped, evidenced assertions between identifiers, accounts, identities, or actors. Identity linking should preserve source, confidence, scope, evidence, and revocation state.

5. Keep concepts orthogonal

The model should minimize conceptual overlap. If two terms are similar, the repository should explain the distinction or deliberately collapse them with clear justification.

6. Remain implementation-neutral

The canonical model should be compatible with common IAM, directory, social graph, and authorization systems, but should not mirror any single product’s terminology too closely.

Research Areas

The repository should collect and analyze knowledge from at least the following areas:

• SCIM, LDAP, and directory schemas;
• OpenID Connect, SAML, WebAuthn, and federation models;
• NIST digital identity guidelines and identity assurance terminology;
• Keycloak, ZITADEL, Ory, Authelia, LLDAP, and related IAM systems;
• ActivityPub, FOAF, WebID, Solid, and social graph models;
• Google Zanzibar, OpenFGA, Cedar, Cerbos, and relationship-based authorization;
• W3C DID and Verifiable Credentials;
• entity resolution, identity matching, and synonymity;
• GDPR-relevant concepts such as pseudonymization, data minimization, and identity linkage.

Expected Outputs

The repository should eventually contain:

• a curated research corpus;
• a glossary of canonical identity-management terms;
• a terminology conflict map;
• a conceptual entity and relationship model;
• synonymity and identity-linking model notes;
• comparison notes against major standards and tools;
• model design principles;
• candidate schema sketches;
• recommendations for downstream implementation projects.

Downstream Relationship

identity-canon may later inform projects such as:

• user-engine — operational user and account management;
• user-accounts — user-facing account and preference UI;
• user-manager — administrative user-management UI;
• identity-connect — adapters to IAM and directory systems;
• actor-graph — relationship and synonymity graph engine;
• access-control or related authorization projects;
• tenant, organization, community, and family management tooling.

These projects should treat identity-canon as a conceptual reference, not as an implementation dependency unless a later explicit schema package is extracted.

Non-Goals

identity-canon is not intended to become:

• a replacement for Keycloak, LDAP, SCIM, OIDC, SAML, or OpenFGA;
• a complete authorization policy language;
• a production identity provider;
• a database product;
• a UI framework;
• a CLI implementation;
• a social network implementation.

Its value lies in making the terminology and conceptual structure clear enough that such systems can later be designed and integrated coherently.

Guiding Question

The guiding question of identity-canon is:

What is the smallest clear set of orthogonal concepts needed to model persons, accounts, identities, organizations, tenants, communities, families, agents, and their relationships across enterprise IAM, social systems, and multi-tenant platforms?

Status

This repository begins as a research and terminology project. Its early work should prioritize clarity, comparison, and conceptual grounding over premature schema or implementation design.