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.