Skip to main content
Version: v0.13

Party Data Models

The IDK provides data models for representing parties, identities, tenants, and correlation identifiers. These models form the foundation for managing entities in credential ecosystems.

Overview​

The party module follows an "everything is a party" pattern where:

  • Parties are the central entity representing any actor (person, organization, service)
  • Identities represent how a party presents itself in the credential ecosystem (issuer, verifier, holder)
  • Tenants provide organizational isolation
  • Correlation Identifiers link external identifiers (DIDs, X.509, email) to identities

Core Data Models​

Party​

A party represents any entity in the system:

import com.sphereon.data.store.party.model.*

data class Party(
    val partyId: String,
    val tenantId: String,
    val partyType: PartyType,
    val origin: PartyOrigin,
    val displayName: String,
    val uri: String?,
    val ownerId: String?,
    val createdAt: Instant,
    val updatedAt: Instant,
    val deletedAt: Instant?
)

Party Types​

Party types are extensible value classes:

// Built-in party types
val naturalPerson = PartyType.NATURAL_PERSON  // A human individual
val organization = PartyType.ORGANIZATION    // Company, institution, legal entity

// Custom party types
val customType = PartyType("SERVICE")
val deviceType = PartyType("DEVICE")

Party Origin​

Indicates how the party was created:

OriginDescription
EXTERNALSynced from outside source (IdP, external system, import, auto-discovery)
MANAGEDCreated and managed natively within the system

Identity​

An identity represents a role that a party plays in the credential ecosystem:

data class Identity(
    val identityId: String,
    val partyId: String,
    val tenantId: String,
    val identityRole: IdentityRole,
    val isDefault: Boolean,
    val createdAt: Instant,
    val updatedAt: Instant,
    val deletedAt: Instant?
)

Identity Roles​

Identity roles define how an identity participates in credential flows:

// Built-in identity roles
val issuer = IdentityRole.ISSUER     // Issues credentials (OID4VCI)
val verifier = IdentityRole.VERIFIER // Requests/verifies credentials (OID4VP)
val holder = IdentityRole.HOLDER     // Holds and presents credentials

// Custom roles
val registrar = IdentityRole("REGISTRAR")
val trustAnchor = IdentityRole("TRUST_ANCHOR")

Tenant​

A tenant provides organizational isolation:

data class Tenant(
    val tenantId: String,
    val tenantType: TenantType,
    val name: String,
    val description: String?,
    val ownerPartyId: String?,
    val createdAt: Instant,
    val updatedAt: Instant,
    val deletedAt: Instant?
)

Tenant Types​

// Built-in tenant types
val orgTenant = TenantType.ORGANIZATION
val personTenant = TenantType.NATURAL_PERSON

// Custom types
val departmentTenant = TenantType("DEPARTMENT")

Correlation Identifier​

Links external identifiers to identities:

data class CorrelationIdentifier(
    val correlationId: String,
    val identityId: String,
    val tenantId: String,
    val identifierType: IdentifierType,
    val value: String,
    val isPrimary: Boolean,
    val isVerified: Boolean,
    val validFrom: Instant?,
    val validUntil: Instant?,
    val createdAt: Instant,
    val updatedAt: Instant,
    val deletedAt: Instant?
)

Identifier Types​

Types of external identifiers that can be correlated:

// Built-in identifier types
val didIdentifier = IdentifierType.DID    // W3C Decentralized Identifier
val x509Identifier = IdentifierType.X509  // X.509 Certificate

// Custom identifier types
val vatNumber = IdentifierType("VAT")
val leiCode = IdentifierType("LEI")
val emailIdentifier = IdentifierType("EMAIL")
val phoneIdentifier = IdentifierType("PHONE")

Lookup Flow​

The correlation identifier enables flexible lookup:

External Identifier Value
        ↓
Correlation Identifier (matches type + value)
        ↓
Identity (role in credential ecosystem)
        ↓
Party (the actual entity)

For example, to find who issued a credential:

  1. Extract the issuer DID from the credential
  2. Look up the correlation identifier with type=DID and value=the DID
  3. Get the identity from the correlation identifier
  4. Get the party from the identity

Query Filters​

PartyFilter​

Filter parties when querying:

// Filter by type
val filter = PartyFilter.byType(PartyType.ORGANIZATION)

// Filter by multiple types
val multiFilter = PartyFilter.byTypes(
    setOf(PartyType.ORGANIZATION, PartyType.NATURAL_PERSON)
)

// Filter by origin
val externalFilter = PartyFilter.byOrigin(PartyOrigin.EXTERNAL)

// Filter by display name (partial match)
val nameFilter = PartyFilter.byDisplayName("Acme")

// Filter by owner
val ownedFilter = PartyFilter.byOwner("owner-party-id")

// Filter for root parties (no owner)
val rootFilter = PartyFilter.rootParties()

// Filter by creation date
val recentFilter = PartyFilter.createdBetween(
    from = Instant.now().minus(Duration.ofDays(7)),
    to = Instant.now()
)

Fetch Options​

Control which related data to include when fetching parties:

// Minimal - party only
val minimal = PartyFetchOptions.MINIMAL

// Include owner party
val withOwner = PartyFetchOptions.WITH_OWNER

// Include identities
val withIdentities = PartyFetchOptions.WITH_IDENTITIES

// Include identities with their correlation identifiers
val withFullIdentities = PartyFetchOptions.WITH_FULL_IDENTITIES

// Everything
val full = PartyFetchOptions.FULL

// Custom options
val custom = PartyFetchOptions(
    includeOwner = true,
    includeIdentities = true,
    identityOptions = IdentityFetchOptions(
        includeCorrelationIdentifiers = true
    )
)

Input Models​

Creating Parties​

val createInput = PartyCreateInput(
    partyType = PartyType.ORGANIZATION,
    origin = PartyOrigin.MANAGED,
    displayName = "Acme Corporation",
    uri = "https://acme.example.com",
    ownerId = null  // Root party
)

Updating Parties​

val updateInput = PartyUpdateInput(
    displayName = "Acme Corp (Updated)",
    uri = "https://new.acme.example.com",
    ownerId = "new-owner-id"
)

Result Models​

Query operations return result models with associated data:

data class PartyResult(
    val party: Party,
    val owner: Party?,
    val identities: List<IdentityResult>?
)

data class IdentityResult(
    val identity: Identity,
    val correlationIdentifiers: List<CorrelationIdentifier>?
)

data class TenantResult(
    val tenant: Tenant,
    val ownerParty: Party?
)

Entity Relationships​

Party Entity Relationships

Use Cases​

Representing an Issuer​

// Party for the issuing organization
val issuerParty = Party(
    partyId = "party-gov-dmv",
    tenantId = "tenant-123",
    partyType = PartyType.ORGANIZATION,
    origin = PartyOrigin.EXTERNAL,
    displayName = "Department of Motor Vehicles",
    uri = "https://dmv.gov.example.com",
    // ...
)

// Identity for their issuer role
val issuerIdentity = Identity(
    identityId = "identity-dmv-issuer",
    partyId = "party-gov-dmv",
    tenantId = "tenant-123",
    identityRole = IdentityRole.ISSUER,
    isDefault = true,
    // ...
)

// Correlation identifier for their DID
val issuerDid = CorrelationIdentifier(
    correlationId = "corr-dmv-did",
    identityId = "identity-dmv-issuer",
    tenantId = "tenant-123",
    identifierType = IdentifierType.DID,
    value = "did:web:dmv.gov.example.com",
    isPrimary = true,
    isVerified = true,
    // ...
)

Representing a Wallet User​

// Party for the user
val userParty = Party(
    partyId = "party-user-alice",
    tenantId = "tenant-123",
    partyType = PartyType.NATURAL_PERSON,
    origin = PartyOrigin.MANAGED,
    displayName = "Alice",
    // ...
)

// Identity for their holder role
val holderIdentity = Identity(
    identityId = "identity-alice-holder",
    partyId = "party-user-alice",
    tenantId = "tenant-123",
    identityRole = IdentityRole.HOLDER,
    isDefault = true,
    // ...
)