# Digital Credential and VC Analysis Taxonomy

**Status:** Proofet Atlas 0.1.0

## Purpose and Scope

This taxonomy defines independent dimensions for classifying and analyzing digital credential artifacts. It is intended to guide the Proofet analysis model, response schema, fixture catalogue, and implementation roadmap.

The broader term **digital credential** is intentional. W3C Verifiable Credentials, SD-JWT VC, ISO mdoc, and X.509 certificates belong to related ecosystems but are not all W3C VCs. Proofet must report the applicable family without implying that every recognized credential conforms to the W3C Verifiable Credentials Data Model.

Classification and assurance are separate:

- **Classification** describes what an artifact declares or how it is represented.
- **Analysis** reports bounded observations derived from available data.
- **Verification** establishes properties through cryptographic or external checks.
- **Validation** applies profile, trust, and business rules for a particular use.

A credential must be classified across multiple dimensions rather than placed in one exclusive category.

## Group A: Intrinsic Classification

Intrinsic dimensions determine what the artifact is and how Proofet can parse it. These observations do not establish authenticity or conformance.

### A1. Artifact Kind

The role of the submitted artifact must be identified before credential-specific analysis.

| Kind | Meaning | Examples |
|---|---|---|
| Credential | Claims issued about one or more subjects | W3C VC, SD-JWT VC, mdoc |
| Presentation | One or more credentials or derived claims presented to a verifier | W3C VP, SD-JWT presentation, mdoc DeviceResponse |
| Disclosure | Data used to reveal a selectively disclosable claim | SD-JWT Disclosure |
| Binding proof | Proof that binds a holder or presenter to a credential or transaction | KB-JWT, VP proof, mdoc DeviceAuth |
| Certificate | Public-key and identity binding artifact | X.509 certificate |

An exchange request, presentation definition, issuance request, or protocol message is not a credential. Those artifacts require separate protocol taxonomies and endpoints.

### A2. Credential Family

This dimension identifies the base credential family independently of its version, encoding, or ecosystem profile. It uses a closed set of family identifiers; profiles must not be represented as families.

| Family | Governing specification or body | Notes |
|---|---|---|
| W3C Verifiable Credential | W3C | Version is recorded under A3 |
| SD-JWT VC | IETF | Applies the SD-JWT VC profile to JWT claims |
| ISO mdoc / mDL | ISO/IEC 18013-5 | CBOR-based mobile document family |
| AnonCreds | Hyperledger AnonCreds | Privacy-preserving credential and proof family using schemas and credential definitions |
| X.509 public-key certificate | ITU-T / IETF | ASN.1 certificate, not a W3C VC |

The controlled values are `w3c_vc`, `sd_jwt_vc`, `iso_mdoc`, `anoncreds`, `x509`, and `unknown`. There is deliberately no `ecosystem_profile`, `other`, or vendor-specific family value. An unrecognized artifact is `unknown`; its exact observed identifiers remain available as evidence.

### A3. Model Version and Credential Profiles

The analyzer should report the family model version and zero or more credential profiles separately. A profile is a versioned constraint set layered on a base family, not a new family. Relevant observations include:

- VCDM version inferred from the first `@context` value;
- credential type declarations;
- SD-JWT VC `vct` value;
- mdoc document type (`docType`);
- AnonCreds schema and credential-definition identifiers;
- profile-specific required claims or namespaces; and
- unknown, ambiguous, or conflicting model declarations.

Each recognized profile is represented by a controlled registry key, profile version, base family, authority, and the exact declaration used as evidence. Initial registry entries are defined in the [Atlas registry](../registry/taxonomy_registry.md). Unknown profiles must preserve their literal `vct`, `docType`, type, context, or schema identifier and use `registry_status: unregistered`; they must not be collapsed into a generic profile value.

Profile recognition is only classification. Profile conformance requires a version-specific C3 validator and must not be inferred from the presence of a type identifier alone.

### A4. Serialization

Serialization describes the concrete encoding of the data before any security envelope is considered.

| Serialization | Characteristics |
|---|---|
| JSON | Plain JSON claim representation |
| JSON-LD | JSON using `@context` for linked-data semantics |
| CBOR | Compact binary object representation |
| AnonCreds JSON | AnonCreds-specific credential and proof structures |
| ASN.1 DER | Binary encoding used by X.509 certificates |

JSON-LD is both JSON syntax and a semantic processing model. An analyzer that only inspects JSON keys must report that generalized JSON-LD processing was not performed.

### A5. Security Envelope and Representation

The security envelope describes how integrity protection is represented around or within the credential data.

| Representation | Payload relationship | Examples |
|---|---|---|
| Unsecured object | No securing mechanism is present | Issuance input, illustrative VCDM example |
| Embedded proof | Proof is contained in the credential object | W3C Data Integrity proof |
| JWS envelope | Signed JWT wraps a JSON payload | VC-JWT, SD-JWT VC issuer-signed JWT |
| COSE envelope | COSE protects a CBOR or JSON payload | VC-COSE, mdoc issuer authentication |
| Derived proof | Presentation contains a proof derived from an issued credential | BBS or ECDSA-SD derived credential |
| ZK credential proof | Proof reveals attributes or predicates without exposing the complete credential | AnonCreds presentation proof |

Two JWT representations must be distinguished:

- **Legacy nested VC-JWT:** JWT registered claims surround a W3C credential under the `vc` claim.
- **Modern W3C VC-JWT:** the VCDM credential is the JWT payload itself, following the W3C JOSE/COSE securing specification.

Supporting one representation does not imply support for the other.

### A6. Subject and Claim Topology

Structural analysis should describe:

- subject count;
- whether subject identifiers are present;
- whether the credential is bearer-oriented;
- top-level and nested claim names;
- relationships among multiple subjects;
- claim value types and cardinality; and
- whether claims occur in credential, presentation, disclosure, or binding artifacts.

An analyzer must not silently reduce a multi-subject credential to its first subject. If only the first subject is analyzed, that limitation must be explicit.

### A7. Lifecycle and External Dependencies

The analyzer should inventory declared lifecycle metadata and references without claiming that referenced resources were evaluated.

- issuance or validity start;
- expiration or validity end;
- credential status declarations;
- credential schemas;
- evidence;
- terms of use;
- refresh services;
- JSON-LD contexts;
- verification methods; and
- related resources and integrity digests.

Time-window analysis should use terms such as `within_declared_time_window`, `before_declared_start`, `after_declared_end`, or `indeterminate`. The word `valid` should be reserved for a clearly scoped validation result.

### A8. Schema and Semantic Definition

The analyzer should classify how claim names, value shapes, and credential types obtain meaning. More than one mechanism can apply to one credential.

| Mechanism | Role | Examples |
|---|---|---|
| JSON-LD context | Maps terms to semantic identifiers | W3C VCDM and extension contexts |
| JSON Schema | Constrains JSON shape and value types | VCDM `credentialSchema` |
| AnonCreds schema | Defines attribute names for an AnonCreds credential | Schema identifier and schema attributes |
| ISO namespace | Defines mdoc data elements | `org.iso.18013.5.1` |
| Credential metadata | Describes an issuer-supported credential configuration | OID4VCI credential configuration |
| Profile specification | Adds domain or ecosystem constraints | EUDI PID, OpenBadges, EBSI profile |
| Proprietary definition | Uses a vendor-specific schema or vocabulary | Private ecosystem profile |
| None detected | No explicit semantic or schema mechanism was found | Ad hoc claims |

The presence of a context, schema identifier, namespace, or metadata reference does not mean it was resolved, integrity-checked, understood, or applied.

### A9. Credential Domain and Intended Purpose

Domain classification can help route profile checks and privacy analysis. Example domains include identity, education, employment, professional licensing, authorization, health, finance, membership, compliance, device or IoT attestation, and supply-chain provenance.

The domain should be reported with its basis and confidence:

- **Declared:** Identified by a recognized type or profile specification.
- **Context-supplied:** Provided by the caller or exchange protocol.
- **Inferred:** Estimated from claim names or other heuristics.
- **Unknown:** Not established from available evidence.

Domain is not fitness for purpose. An education credential, for example, is not automatically acceptable for an employment decision.

## Group B: Declared Capabilities and Mechanisms

These dimensions describe mechanisms that an artifact or profile appears to support. Presence does not prove correct construction, cryptographic validity, or achieved privacy.

### B1. Cryptographic Mechanism

Relevant declarations include:

- proof or envelope type;
- signature or MAC algorithm;
- cryptographic suite;
- key identifier or verification method;
- canonicalization or transformation algorithm; and
- digest algorithm.

Examples include JWS with ECDSA or EdDSA, COSE signatures, W3C Data Integrity cryptosuites, and mdoc issuer authentication. Algorithm recognition is not signature verification.

### B2. Selective Disclosure

Selective disclosure should not be represented as one Boolean capability. The analyzer should distinguish:

| Dimension | Questions |
|---|---|
| Issuance capability | Was the credential issued using a selectively disclosable mechanism? |
| Disclosure mechanism | Salted-hash disclosure, derived proof, namespace disclosure, or another method? |
| Disclosure granularity | Individual claim, nested claim, object, array element, or namespace? |
| Current disclosure | Which claims are disclosed in this submitted artifact? |
| Undisclosed commitments | Are commitments to undisclosed claims present? |
| Unlinkability claim | Does the mechanism claim unlinkable presentations, and under what assumptions? |

Examples include SD-JWT Disclosures, mdoc issuer-signed items, and BBS or ECDSA-SD derived proofs. Selective disclosure does not automatically provide unlinkability.

### B3. Key Discovery and Resolution

Key discovery determines how candidate verification material can be obtained:

- DID URL and DID method resolution;
- JWK or JWK Set discovery;
- X.509 certificate embedded in or referenced by the artifact;
- COSE key material;
- trusted registry lookup; or
- locally configured verification material.

Resolution can locate a key, but it does not prove that the key is authorized for the credential type or accepted by the verifier.

The issuer identifier should also be classified independently where possible, for example as a DID, HTTPS URL, JWK thumbprint, X.509 subject, legal entity identifier, or ecosystem-specific identifier.

### B4. Holder and Presentation Binding

Binding should be decomposed into distinct properties:

| Binding property | Meaning |
|---|---|
| Credential binding | Credential identifies or commits to a holder-controlled key |
| Proof of possession | Presenter demonstrates control of the bound key |
| Presentation binding | Proof covers the presented credential or disclosed claims |
| Audience binding | Proof is intended for a particular verifier |
| Challenge binding | Proof incorporates a verifier nonce or challenge |
| Freshness | Proof is constrained to an acceptable time window or one-time use |

Mechanisms include W3C VP proofs with challenge and domain, VP-JWT audience and nonce claims, SD-JWT Key Binding JWTs, and mdoc DeviceAuth. Detecting binding material is not equivalent to verifying it.

### B5. Status and Revocation Mechanism

The analyzer should classify the declared strategy for determining whether an issued credential remains usable:

| Mechanism | Examples |
|---|---|
| Bitstring status list | W3C Bitstring Status List entry |
| Legacy status list | StatusList2021 entry |
| AnonCreds revocation registry | Accumulator-based non-revocation support |
| Certificate status | CRL or OCSP for X.509-backed credentials |
| Online issuer check | Issuer-specific status endpoint |
| Short-lived only | Brief expiration period with no separate status declaration |
| No mechanism detected | No status declaration and no inferred short-lived strategy |
| Unknown | A declaration exists but its mechanism is unrecognized |

Detecting a mechanism is separate from retrieving, authenticating, and evaluating its current state. `short-lived only` should be inferred only under an explicit profile or configured duration threshold.

### B6. Issuance and Presentation Protocol Context

Protocol context describes how an artifact was issued, requested, or presented. Examples include OID4VCI, OID4VP, DIF Presentation Exchange, DIDComm or Aries protocols, ISO mdoc proximity or online presentation, CHAPI, and proprietary APIs.

This context is generally **extrinsic**: the same credential can be transported by different protocols, and a bare credential usually does not prove which protocol carried it. Proofet should classify protocol context only when it is:

- supplied alongside the credential;
- established by the endpoint receiving a complete protocol message; or
- unambiguously declared by an enclosing artifact.

Protocol analysis belongs in resource-specific exchange endpoints. Credential analysis may report associated protocol metadata but must not infer an issuance or presentation history from credential structure alone.

## Group C: Evaluated Assurance

Evaluated assurance records checks Proofet actually performed. Each result must identify its scope, status, evidence, and limitations.

### C1. Detection and Decoding

Questions include:

- Was the artifact kind recognized?
- Was the serialization decoded successfully?
- Was the expected payload extracted?
- Were disclosures or envelope components parsed?

Successful decoding establishes only that Proofet could interpret the bytes or object structure.

### C2. Structural Analysis

Structural checks examine locally available fields and relationships, such as:

- required property presence;
- value shape and cardinality;
- coherent subject and issuer representations;
- date syntax and ordering;
- envelope and payload consistency; and
- recognized extension shapes.

Structural analysis is not full specification conformance unless every applicable normative requirement is implemented and tested.

### C3. Semantic and Profile Conformance

This stage can evaluate:

- JSON-LD context and vocabulary semantics;
- credential-type schemas;
- profile-specific required claims;
- media-type requirements;
- algorithm and key constraints; and
- normative specification rules.

Results must name the exact specification version and profile tested. Proofet should not make broad conformance claims from a partial ruleset.

### C4. Cryptographic Verification

Cryptographic verification determines whether the selected proof or envelope protects the submitted content using acceptable verification material. It can include:

- signature or MAC verification;
- disclosure digest verification;
- derived-proof verification;
- key authorization for the stated proof purpose; and
- certificate path validation where applicable.

A parsed algorithm name or proof object must be reported as `not_checked` until this stage succeeds.

### C5. Credential Status and Currency

Status evaluation is separate from time-window inspection. It can include:

- declared validity period;
- revocation or suspension status;
- status-list integrity and freshness;
- certificate revocation where applicable; and
- profile-specific lifecycle rules.

An artifact can be within its declared time window and still be revoked, suspended, untrusted, or otherwise unusable.

### C6. Issuer Authority and Trust

Trust evaluation asks whether an authenticated issuer is acceptable for the specific credential type and use. Sources can include:

- local verifier policy;
- trust lists or registries;
- X.509 trust anchors and policy constraints;
- governance frameworks; and
- accreditation or authorization chains.

Key resolution, signature verification, issuer identity, issuer authorization, and verifier trust are separate conclusions.

### C7. Holder and Session Binding Verification

This stage verifies applicable possession, audience, challenge, freshness, and replay protections. A credential by itself often cannot establish holder binding because the required evidence belongs to a presentation or exchange session.

### C8. Privacy and Disclosure Analysis

Privacy analysis can report observations such as:

- claim names and optionally values;
- potentially identifying or sensitive claims;
- stable identifiers and correlation surfaces;
- claims disclosed in the current presentation;
- metadata and signature correlation risks;
- external requests that could enable tracking; and
- disclosure exceeding a supplied policy.

Sensitivity is contextual. Claim-name heuristics should be labeled as heuristics rather than definitive classifications of personal data.

### C9. Fitness for Purpose

Fitness for purpose applies verifier-specific business and legal rules after relevant verification and trust checks. It asks whether the credential is acceptable for a particular transaction, not merely whether it is structurally or cryptographically sound.

This is the highest and most contextual assurance layer. Proofet must not infer it without an explicit policy and the evidence required by that policy.

## Analysis Result Model

Each check should report:

```ts
interface AnalysisCheck {
	id: string;
	category:
		| 'decoding'
		| 'structure'
		| 'conformance'
		| 'cryptography'
		| 'status'
		| 'trust'
		| 'binding'
		| 'privacy'
		| 'fitness_for_purpose';
	status: 'pass' | 'fail' | 'warning' | 'not_checked' | 'not_applicable';
	scope: string;
	evidence: string[];
	detail: string;
}
```

`pass` means only that the named, scoped check was performed and passed. It must not be promoted into a broader statement such as “the credential is valid” unless all requirements for that explicitly defined conclusion were evaluated.

## Engine Architecture

The analysis engine should follow a staged pipeline:

1. Identify artifact kind and detect candidate representation.
2. Decode serialization and security envelope without trusting content.
3. Classify intrinsic dimensions and inventory declared mechanisms.
4. Run bounded structural and privacy checks supported by the selected analyzer version.
5. Run optional conformance, cryptographic, status, trust, and binding modules when explicitly requested and available.
6. Apply fitness-for-purpose policy only when supplied with sufficient verified evidence.
7. Report every skipped assurance stage as `not_checked` or `not_applicable` with a reason.

The fixture catalogue in `catalogue.md` should provide representative positive, negative, and unsupported cases across these dimensions. Catalogue coverage does not itself establish implementation conformance.

## Reference Anchors

This taxonomy is a Proofet synthesis rather than a claim that one universal credential taxonomy exists. Its principal technical anchors are:

- [W3C Verifiable Credentials Data Model 2.0](https://www.w3.org/TR/vc-data-model-2.0/)
- [W3C Verifiable Credentials Data Model 1.1](https://www.w3.org/TR/vc-data-model/)
- [W3C Verifiable Credential Data Integrity 1.0](https://www.w3.org/TR/vc-data-integrity/)
- [W3C Securing Verifiable Credentials using JOSE and COSE](https://www.w3.org/TR/vc-jose-cose/)
- [W3C Decentralized Identifiers 1.0](https://www.w3.org/TR/did-core/)
- [IETF RFC 9901: Selective Disclosure for JWTs](https://www.rfc-editor.org/rfc/rfc9901.html)
- [OpenID for Verifiable Credential Issuance 1.0](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html)
- [OpenID for Verifiable Presentations 1.0](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html)
- [DIF Presentation Exchange](https://identity.foundation/presentation-exchange/)
- [Hyperledger AnonCreds Specification](https://hyperledger.github.io/anoncreds-spec/)
- [EUDI Wallet Architecture and Reference Framework](https://github.com/eu-digital-identity-wallet/eudi-doc-architecture-and-reference-framework)
- ISO/IEC 18013-5 for mdoc and mobile driving licence structures

Registries and extension directories are discovery aids, not substitutes for normative specifications. Entries should be validated against their owning specification and version before Proofet makes conformance claims.

## Version 0.1 Boundary

The current `/v1/credentials/analyze` implementation supports bounded analysis of W3C VC JSON objects and legacy nested VC-JWTs. It does not currently establish:

- generalized JSON-LD semantics;
- modern direct-payload W3C VC-JWT or VC-COSE support;
- SD-JWT VC, mdoc, or AnonCreds decoding;
- complete structural or profile conformance;
- signature or proof validity;
- issuer authorization or trust;
- credential revocation or suspension status;
- holder or session binding; or
- fitness for purpose.

Those boundaries should remain visible in API output even as additional taxonomy dimensions are recognized.