smoa/docs/reference/IDENTITY-TEMPLATE-ALIGNMENT.md

Identity templates: SMOA ↔ Complete Credential alignment

This document aligns SMOA credential templates (mobile presentation, barcode formats, sync payloads) with the Complete Credential umbrella program (complete-credential repo), in particular:

• Shared OpenAPI draft: submodules/cc-shared-schemas/openapi/v1/openapi.yaml — CredentialRef.domain
• Master plan credential domains (PIV, travel-adjacent, payment, NFC, mobile)

SMOA code lives in this repository; Complete Credential is an external reference layout. Keep the string constants in sync with:

• Android: modules/credentials/.../SmoaCredentialTemplateIds.kt
• Backend: backend/.../SmoaCredentialType.kt (same literal values)

---

1. Complete Credential CredentialRef.domain

From cc-shared-schemas (draft v0.1):

domain value	Meaning (program)
payment	Payment / financial instrument workflows
piv_pki	PIV-class, PKI-backed, high-assurance identity
nfc_access	Physical access, badge, NFC-adjacent credentials
mobile	Derived / mobile wallet–style credentials

---

2. SMOA credentialType (canonical)

Use these values in backend CredentialSyncRequest.credentialType, database credentials.credential_type, and mobile when serializing sync payloads.

credentialType	Maps to CC domain	SMOA implementation
piv_pki	piv_pki	PIV / smart card presentation; no single barcode class—use secure element / card APIs. Pair with org PKI metadata in payload.
payment	payment	Payment tokens / instruments (future wire-up to issuance services).
nfc_access	nfc_access	Access cards, mission badges; often QR/PDF417 from directory or access system.
mobile	mobile	Derived credentials, mobile-issued wallet artifacts.
icao9303_mrtd	(travel-adjacent issuance — CC Phase / national programs)	ICAO Doc 9303 MRTD: com.smoa.core.barcode.formats.ICAO9303Credential
aamva_dlid	(state ID — often under organizational / civil ID)	AAMVA DL/ID PDF417: com.smoa.core.barcode.formats.AAMVACredential
mil_std_129	(defense ID — organizational / sovereign)	MIL-STD-129: com.smoa.core.barcode.formats.MILSTD129Credential
agency_badge	Often co-issued with nfc_access	Agency photo ID / badge; generic card UI when format is org-specific.

2.1 Legacy aliases (older API / docs)

Prefer canonical types above for new integrations.

Legacy	Prefer
id	agency_badge or piv_pki (context-dependent)
badge	nfc_access or agency_badge
license	aamva_dlid
permit	agency_badge or domain-specific extension in payload
other	Explicit new credentialType after design review

---

3. Optional payload keys for cross-system identity

When syncing, payload (JSON object) may include:

Key	Type	Description
completeCredentialDomain	string	Echo CC CredentialRef.domain: payment | piv_pki | nfc_access | mobile
issuingAuthority	object	Preferred for tenant / jurisdiction / ministry / agency (see docs/schemas/credential-authority.schema.json): tenantId, jurisdiction, government, credentialRegistryRef, etc.
credentialId	string	External issuance id (if different from sync credentialId)
subjectId	string (uuid)	Aligns with CC SubjectRef.subjectId when known

Do not rely on a duplicate top-level tenantId alone; nest under issuingAuthority for consistency with JSON Schema.

Format-specific fields should match the Kotlin models (e.g. ICAO field names as JSON keys) when embedding structured data for rendering or barcode regeneration.

---

4. Barcode / format mapping (SMOA modules)

credentialType	Kotlin model	Module / usage
icao9303_mrtd	ICAO9303Credential	core/barcode, modules/credentials
aamva_dlid	AAMVACredential	core/barcode, modules/credentials
mil_std_129	MILSTD129Credential	core/barcode, modules/credentials
piv_pki	(no default barcode)	PIV is typically X.509 / card APDU, not MRZ in-app
nfc_access, agency_badge	(varies)	Often backend-supplied bitmap or QR payload in payload

---

5. Operational checklist

1. Issuance systems in Complete Credential should set CredentialRef.domain consistently; SMOA sync should set credentialType and optionally completeCredentialDomain to the same logical row in §2.
2. Travel documents use icao9303_mrtd and MRZ/check digit rules already implemented in ICAO9303Credential.
3. PIV uses piv_pki; do not conflate with icao9303_mrtd unless the credential is literally an eMRTD with ICAO structure.
4. When CC publishes expanded enums or template packs under platform/entity-packs/, update this file and the two Kotlin SmoaCredential* files in the same commit.

---

6. JSON Schema (issuance pipeline validation)

Payload shapes for icao9303_mrtd, aamva_dlid, and mil_std_129 are defined under docs/schemas/:

File	Purpose
credential-authority.schema.json	Reusable issuing authority and jurisdiction (multi-government: tenant, country, subdivision, ministry, agency, service branch, localized names).
credential-payload-icao9303_mrtd.schema.json	MRZ-oriented travel document fields (YYMMDD).
credential-payload-aamva_dlid.schema.json	AAMVA-style DL/ID (YYYYMMDD).
credential-payload-mil_std_129.schema.json	Military ID-style card (YYYYMMDD).
credential-payload-piv_pki.schema.json	PIV/PKI optional payload.
credential-payload-payment.schema.json	Payment token refs.
credential-payload-nfc_access.schema.json	Access / badge metadata.
credential-payload-mobile.schema.json	Mobile / derived wallet refs.
credential-payload-agency_badge.schema.json	Agency photo ID / badge.
credential-payload-document.schema.json	oneOf union over all payload schemas (select by credentialType on the request body).

Resolve $ref from the schema directory (same folder as the referring file). Schemas describe CredentialSyncRequest.payload only — the top-level credentialType field is on the sync JSON body alongside credentialId, holderId, etc.; do not duplicate credentialType inside payload. Use issuingAuthority in payload when syncing across ministries, agencies, or coalition programs.

The credential-payload-document.schema.json oneOf union is ambiguous without a discriminator on payload; issuance pipelines should select the schema file that matches request.credentialType after validating that string against SmoaCredentialType.CANONICAL.

---

7. Related paths

Artifact	Path
Complete Credential — integration runbook + ADR-0010	Umbrella repo: docs/integrations/smoa.md, adr/0010-smoa-mobile-integration-boundary.md (when cloned as e.g. ../complete-credential/)
Client config example (FQDN / endpoints)	backend/docs/examples/smoa-client-config.example.json
LXC / hosting	backend/docs/LXC-PROXMOX-CONTAINERS.md
Backend credential entity	backend/.../CredentialEntity.kt
Sync DTO	backend/.../CredentialSyncRequest in SyncRequest.kt
OpenAPI (SMOA API)	docs/api/api-specification.yaml

7.1 Contract drift check (with Complete Credential clone)

From the complete-credential repository root (submodules initialized):

SMOA_REPO=/path/to/smoa ./tools/verify/verify-smoa-cc-domain-alignment.sh

This asserts the shared CredentialRef.domain line in cc-shared-schemas and that SmoaCredentialType.kt still contains literals payment, piv_pki, nfc_access, mobile.