This document describes the OpenClaiming protocol and the OpenClaim v1 format. OpenClaiming defines a minimal standard for creating, publishing, and verifying cryptographically signed claims.

Overview

An OpenClaim is a signed JSON document representing a statement. The protocol allows any system to create claims, sign them, publish them, and verify claims created by others.

OpenClaims can represent identity assertions, permissions, attestations, or any other verifiable statement.

OpenClaim v1 Format

An OpenClaim is a JSON document with the following structure.

{
  "ocp": 1,
  "iss": "issuer identifier",
  "sub": "subject identifier",
  "stm": { },
  "nbf": 0,
  "exp": 0,
  "nce": "optional nonce",
  "key": "public key reference or array",
  "sig": ["BASE64_SIGNATURE", ...]
}

Field Definitions

Version Field

"ocp": 1

The ocp field identifies the OpenClaim version. Version 1 standardizes JSON canonicalization, SHA-256 hashing, and P-256 signatures. Future versions may support additional algorithms.

Issuer

"iss": "https://example.com/alice"

The issuer identifies who created the claim. Common formats include URLs, domain identifiers, application user IDs, and blockchain addresses.

Subject

"sub": "https://example.com/bob"

The subject identifies the entity the claim refers to. Issuer and subject may be the same.

Statement

The stm field contains the actual statement.

"stm": {
  "member": true,
  "role": "moderator"
}

The contents of stm are application-defined.

Time Fields

Not Before

"nbf": 1712000000

The claim becomes valid at this Unix timestamp.

Expiration

"exp": 1750000000

The claim expires after this timestamp.

Nonce

"nce": "random-string"

Optional nonce used to prevent replay or ensure uniqueness.

Extensions

Extensions are top-level fields that define standardized claim formats for common use cases. They exist alongside core fields such as nbf and exp, and are not part of stm.

While stm remains freeform, extensions ensure interoperability by defining consistent schemas.

Standard Extensions (v1)

Signature

"sig": ["SIGNATURE", ...]

Each signature is computed over the canonicalized JSON document. Before signing: remove the sig field, canonicalize JSON, hash the result, and sign the hash.

Each signature corresponds to the key at the same index. The encoding and verification method of each signature is determined by the corresponding key.

Signature Encodings (v1)

Key Field

Definition

"key": STRING | ARRAY<STRING>

The key field defines how to obtain the public key(s) used for verification. Each key MUST be a string. Supported forms include:

• Data URLs (embedded keys)
• HTTPS URLs (remote key discovery)
• Identifier-based formats (e.g. EIP-712 signers)

"key": [
  "data:key/es256;base64,MIIB...",
  "https://example.com/.well-known/openclaim.json#keys"
]

Key Rules

• Keys MUST be strings
• Keys MUST be sorted lexicographically
• Keys MUST be unique
• If key is an array, it MUST correspond 1:1 with sig
• If key is a string, it applies to all signatures

Key Types

Canonicalization

JSON as the Universal Format

OpenClaiming uses JSON for its universal support and human readability. To ensure consistent signatures across implementations, we use RFC 8785 JSON Canonicalization—guaranteeing identical byte representations regardless of language or library.

Downstream, the claim can be canonicalized, hashed and signed using various standards.

Important: Canonicalization applies only to the claim JSON itself. Resolved keys, fetched data, and external resources MUST NOT affect canonicalization.

ES256 (ECDSA using P-256 and SHA-256)

The default signature type for OpenClaiming is ES256, which uses:

• ECDSA (Elliptic Curve Digital Signature Algorithm)
• P-256 curve (also known as secp256r1 or prime256v1)
• SHA-256 hashing

ES256 is the standard for JSON Web Signatures (JWS) and is supported natively in most cryptographic libraries.

EIP-712 (Separate Signing Profile)

EIP-712 is a separate signing profile and does NOT sign canonical JSON. Instead:

• Claims are converted into typed structured data
• Fields are mapped into fixed structs per extension
• Addresses and numeric values are derived from identifiers

EIP-712 canonicalization is extension-specific and MUST NOT be inferred from arbitrary JSON structure. For complete details, see EVM Blockchains.

Signing Process

1. Create the JSON claim object.
2. Remove the sig field if present.
3. Canonicalize JSON.
4. Compute SHA-256 hash.
5. Sign the hash with the issuer's private key.
6. Encode the signature as Base64.
7. Add the sig field as an array of signatures.

Verification Process

1. Receive claim
2. Canonicalize JSON (without sig)
3. Resolve keys
4. Verify each signature against its corresponding key
5. Check time constraints (nbf, exp)
6. Apply extension-specific logic
7. Accept or reject claim

Identifier Model

Identifiers used in iss, sub, and stm fields are opaque strings interpreted by applications. Recommended format:

<ecosystem>:<chain>:<type>:<value>

Examples:

"iss": "evm:56:address:0xabc..."
"sub": "evm:56:token:0xdef..."

Identifiers are NOT keys and MUST NOT use data URLs.

Design Principle

OpenClaim separates:

• Identity — iss, sub
• Cryptographic verification — key, sig
• Execution semantics — extensions

EIP-712 Support (v1)

OpenClaiming supports EIP-712 as a separate signing profile for on-chain verification. Domain parameters are inferred deterministically from the claim:

No domain or schema needs to be specified explicitly. All values are inferred deterministically from the claim.

Publishing Claims

OpenClaims may be published anywhere.

Well-Known Endpoints

https://example.com/.well-known/openclaim.json

Application APIs

GET /claims/{id}

Distributed Storage

Claims may be stored on IPFS, distributed databases, or peer-to-peer networks.

Blockchains

Claims may be anchored on-chain by storing claim hashes, signatures, or timestamp anchoring.

Key Discovery

Public keys used to verify claims may be discovered via well-known endpoints, key registries, identity profiles, or blockchain smart contracts.

{
  "keys": [
    {
      "id": "key1",
      "type": "P256",
      "public": "BASE64_KEY"
    }
  ]
}

Security Considerations

Implementations should consider replay attacks, key rotation, expiration enforcement, canonicalization correctness, and signature verification failures.

Claims should be rejected if the signature is invalid, required fields are missing, or expiration has passed.

Recommended Algorithms (v1)

Future versions may support Ed25519, Schnorr signatures, multihash, and multisignatures.

Test Vectors

Reference test vectors are provided in the OpenClaiming repository. They include canonicalization tests, signature tests, and verification tests to ensure compatibility across implementations.

Example OpenClaim

Example membership claim:

{
  "ocp": 1,
  "iss": "https://community.example",
  "sub": "https://users.example/alice",
  "stm": {
    "role": "moderator"
  },
  "nbf": 1712000000,
  "key": [
    "data:key/es256;base64,MIIB..."
  ],
  "sig": ["BASE64_SIGNATURE"]
}

Summary

OpenClaim v1 defines:

• Deterministic canonical JSON signing
• Key resolution via URLs and data URLs
• Multi-signature support via key/sig arrays
• Optional extensions using nested claims
• Flexible trust models including revocable and immutable claims

Future Extensions

Future versions may introduce Merkle proof inclusion, claim revocation mechanisms, and claim bundles.

Implementations

Reference implementations are available for JavaScript, Python, Go, Rust, PHP, Java, Kotlin, and Swift.

Each implementation includes canonicalization, signing, verification, and test vectors.

Versioning

OpenClaim uses semantic versioning.

OpenClaim v1

Future versions will remain backwards compatible when possible.

Contributing

The protocol is developed openly. Contributions are welcome for libraries, test vectors, documentation, security analysis, and interoperability testing.

License

OpenClaiming documentation and reference implementations are released under a permissive open source license.