Web Identity Schemas

TypeScript types and validation schemas for Web Identity and JOSE standards, including:

- Decentralized Identifiers (DID)
- Verifiable Credentials (VC) v1.1 and v2.0, with StatusList2021, Bitstring Status List
- Verifiable Presentations (VP)
- JSON Web Tokens (JWT)
- JSON Web Keys (JWK)
- JSON Web Signatures (JWS)
- See the full list

This library provides both Valibot and Zod (v4) validation implementations with comprehensive type safety.

Installation

``bash
npm install web-identity-schemas
`

Quick Start

$3

`typescript
import * as v from "valibot"
import {
DidSchema,
JwkSchema,
VerifiableCredentialSchema
} from "web-identity-schemas/valibot"

// Validate a DID
const validDid = v.parse(DidSchema, "did:example:123456789abcdefghi")

// Validate a Verifiable Credential
const validVc = v.parse(VerifiableCredentialSchema, {
"@context": "https://www.w3.org/2018/credentials/v1",
type: "VerifiableCredential",
issuer: "did:example:issuer",
issuanceDate: "2023-01-01T00:00:00Z",
credentialSubject: {
id: "did:example:subject",
degree: "Bachelor of Science"
}
})

// Validate cryptographic keys
const validKey = v.parse(JsonWebKeySchema, {
kty: "EC",
crv: "P-256",
x: "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
y: "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"
})
`

$3

`typescript
import * as z from "zod"
import {
DidSchema,
JwkSchema,
VerifiableCredentialSchema
} from "web-identity-schemas/zod"

// Validate a DID
const validDid = DidSchema.parse("did:example:123456789abcdefghi")

// Validate a Verifiable Credential
const validVc = VerifiableCredentialSchema.parse({
"@context": "https://www.w3.org/2018/credentials/v1",
type: "VerifiableCredential",
issuer: "did:example:issuer",
issuanceDate: "2023-01-01T00:00:00Z",
credentialSubject: {
id: "did:example:subject",
degree: "Bachelor of Science"
}
})

// Validate cryptographic keys
const validKey = JsonWebKeySchema.parse({
kty: "EC",
crv: "P-256",
x: "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
y: "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"
})
`

Type Safety

All types are also available as Typescript types at the root of the package, and in each schema export

`typescript
import type { Did, DidDocument, JwtString } from "web-identity-schemas"
// or from "web-identity-schemas/valibot"
// or from "web-identity-schemas/zod"

const jwt: JwtString = "..."

const did: Did = "did:method:something"
const didWeb: Did<"web"> = "did:web:example.com"

const didDocument: DidDocument = {
// ...
}
`

Available Schemas

This library exports comprehensive schemas for Web Identity and JOSE standards. All schemas are available in both Valibot and Zod implementations, with corresponding TypeScript types.

$3

#### Decentralized Identifiers (DIDs)

- DidSchema - Validates DID strings (e.g., did:example:123)
- Types | Valibot | Zod
- DidUrlSchema - Validates DID URLs with paths/queries/fragments
- Types | Valibot | Zod
- DidDocumentSchema - Validates DID Documents
- Types | Valibot | Zod
- VerificationMethodSchema - Validates verification methods in DID Documents
- Types | Valibot | Zod
- ServiceSchema - Validates service endpoints in DID Documents
- Types | Valibot | Zod

#### Verifiable Credentials (VCs)

- VerifiableCredentialSchema - Universal VC validator (v1.1 and v2.0)
- Types | Valibot | Zod
- VerifiableCredentialV1Schema - Specific v1.1 VC validator
- Types | Valibot | Zod
- VerifiableCredentialV2Schema - Specific v2.0 VC validator
- Types | Valibot | Zod
- VerifiablePresentationSchema - Validates verifiable presentations
- Types | Valibot | Zod

#### JSON Web Tokens (JWTs)

- JwtObjectSchema - Validates JWT objects (header + payload)
- Types | Valibot | Zod
- JwtStringSchema - Validates JWT strings in compact format
- Types | Valibot | Zod
- JwtHeaderSignedSchema - Validates JWT headers for signed tokens
- Types | Valibot | Zod
- JwtPayloadSchema - Validates JWT payloads
- Types | Valibot | Zod

#### JSON Web Keys (JWKs)

- JsonWebKeySchema - Universal JWK validator (all key types)
- Types | Valibot | Zod
- JsonWebKeySetSchema - Validates JWK Sets
- Types | Valibot | Zod

$3

#### Specific JWK Types

- RsaJwkSchema - RSA keys (kty: "RSA")
- Types | Valibot | Zod
- EcJwkSchema - Elliptic Curve keys (kty: "EC")
- Types | Valibot | Zod
- OctJwkSchema - Symmetric keys (kty: "oct")
- Types | Valibot | Zod
- OkpJwkSchema - Octet Key Pair keys (kty: "OKP")
- Types | Valibot | Zod

#### Cryptographic Curves

- EllipticCurveSchema - Elliptic curve names (P-256, P-384, etc.)
- Types | Valibot | Zod
- OctetKeyPairCurveSchema - OKP curve names (Ed25519, X25519)
- Types | Valibot | Zod

$3

#### JSON Web Signatures (JWS)

- JwsObjectSchema - JWS in object format
- Types | Valibot | Zod
- JwsStringSchema - JWS in compact string format
- Types | Valibot | Zod
- JwsJsonSerializationSchema - JWS JSON General Serialization
- Types | Valibot | Zod
- JwsFlattenedJsonSerializationSchema - JWS JSON Flattened Serialization
- Types | Valibot | Zod

#### JSON Web Encryption (JWE)

- JweObjectSchema - JWE in object format
- Types | Valibot | Zod
- JweStringSchema - JWE in compact string format
- Types | Valibot | Zod
- JweJsonSerializationSchema - JWE JSON General Serialization
- Types | Valibot | Zod
- JweFlattenedJsonSerializationSchema - JWE JSON Flattened Serialization
- Types | Valibot | Zod

#### JOSE Algorithms

- JoseAlgorithmSchema - All JOSE algorithms
- Types | Valibot | Zod
- JoseSignatureAlgorithmSchema - Signature algorithms (RS256, ES256, etc.)
- Types | Valibot | Zod
- JweContentEncryptionAlgorithmSchema - Content encryption algorithms
- Types | Valibot | Zod
- JweKeyManagementAlgorithmSchema - Key management algorithms
- Types | Valibot | Zod

$3

#### Credential Status

- StatusList2021CredentialSchema - StatusList2021 credentials
- Types | Valibot | Zod
- BitstringStatusListCredentialSchema - Bitstring status credentials
- Types | Valibot | Zod

#### Proof Systems

- ProofSchema - Cryptographic proof objects
- Types | Valibot | Zod

$3

#### Common Formats

- UriSchema - URI format validation
- Types | Valibot | Zod
- Base64UrlSchema - Base64url encoded strings
- Types | Valibot | Zod
- Base64Schema - Base64 encoded strings
- Types | Valibot | Zod
- DateTimeStampSchema - ISO 8601 datetime strings
- Types | Valibot | Zod

Contributing

Contributions are welcome.

This library maintains strict type safety and comprehensive test coverage. Both Valibot and Zod implementations must pass identical test suites to ensure consistency.

See CLAUDE.md for detailed development guidelines and schema patterns.

License (MIT)

Copyright (c) 2025 Catena Labs, Inc. See LICENSE` for details.