This document describes the Security Vocabulary, i.e., the vocabulary used to ensure the authenticity and integrity of Verifiable Credentials and similar types of constrained digital documents using cryptography, especially through the use of digital signatures and related mathematical proofs .

Alternate versions of the vocabulary definition exist in Turtle and JSON-LD.

Published:
Version Info:
2.0
See Also: https://www.w3.org/TR/vc-data-integrity/

Comments regarding this document are welcome. Please file issues directly on GitHub, or send them to public-vc-comments@w3.org (subscribe, archives).

Specification of terms

In general, the terms — i.e., the properties and classes — used in the VCDM are formally specified in Recommendation Track documents published by the W3C Verifiable Credentials Working Group or, for some deprecated or reserved terms, in Reports published by the W3C Credentials Community Group. In each case of such external definition, the term's description in this document contains a link to the relevant specification. Additionally, the `rdfs:definedBy` property in the RDFS representation(s) refers to the formal specification.

In some cases, a local explanation is necessary to complement, or to replace, the definition found in an external specification. For instance, this is so when the term is needed to provide a consistent structure to the RDFS vocabulary, such as when the term defines a common supertype for class instances that are used as objects of specific properties, or when RDF Graphs are involved. For such cases, the extra definition is included in the current document (and the `rdfs:comment` property is used to include them in the RDFS representations).

Overview diagram of the vocabulary (without the reserved and deprecated items, error codes, and `xsd` datatypes).
A separate, stand-alone SVG version of the diagram, as well as a textual description, are also available.

Namespaces

This specification makes use of the following namespaces:

sec
https://w3id.org/security#
cred
https://www.w3.org/2018/credentials#
dc
http://purl.org/dc/terms/
dcterms
http://purl.org/dc/terms/
owl
http://www.w3.org/2002/07/owl#
rdf
http://www.w3.org/1999/02/22-rdf-syntax-ns#
rdfs
http://www.w3.org/2000/01/rdf-schema#
xsd
http://www.w3.org/2001/XMLSchema#
vs
http://www.w3.org/2003/06/sw-vocab-status/ns#
schema
http://schema.org/
jsonld
http://www.w3.org/ns/json-ld#

@context files

The following @context files make use of the terms defined in this specification:

Regular terms

Property definitions

The following are property definitions in the sec namespace.

verificationMethod

Verification method

See the formal definition of the term.

See also:
Decentralized Identifiers (DIDs) v1.0
stable
Range:
VerificationMethod
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2,
https://www.w3.org/ns/cid/v1

controller

Controller

See the formal definition of the term.

The property's value should be a URL, i.e., not a literal.

stable
Domain:
Union of:
VerificationMethod
ControlledIdentifierDocument
Relevant @contexts:
https://w3id.org/security/multikey/v1,
https://w3id.org/security/jwk/v1,
https://www.w3.org/ns/did/v1,
https://www.w3.org/ns/cid/v1

proof

Proof sets

See the formal definition of the term.

stable
Range:
ProofGraph
Relevant @contexts:
https://www.w3.org/ns/credentials/v2,
https://w3id.org/security/data-integrity/v2

domain

Domain of a proof

See the formal definition of the term.

stable
Range:
xsd:string
Domain:
Proof
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2

challenge

Challenge of a proof

See the formal definition of the term.

stable
Range:
xsd:string
Domain:
Proof
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2

previousProof

Previous proof

See the formal definition of the term.

stable
Range:
Proof
Domain:
Proof
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2

proofPurpose

Proof purpose

See the formal definition of the term.

stable
Range:
VerificationRelationship
Domain:
Proof
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2

proofValue

Proof value

See the formal definition of the term.

stable
Range:
multibase
Domain:
Proof
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2

created

Proof creation time

See the formal definition of the term.

stable
Range:
xsd:dateTime
Domain:
Proof
Relevant @context:
https://w3id.org/security/data-integrity/v2

expiration

Expiration time for a proof or verification method

See the formal definitions here and here.

Historically, this property has often been expressed using `expires` as a shortened term in JSON-LD. Since this shortened term and its mapping to this property are in significant use in the ecosystem, the inconsistency between the short term name (`expires`) and the property identifier (`...#expiration`) is expected and should not trigger an error.
stable
Range:
xsd:dateTime
Domain:
Union of:
Proof
VerificationMethod
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2,
https://www.w3.org/ns/cid/v1

nonce

Nonce supplied by proof creator

See the formal definition of the term.

stable
Range:
xsd:string
Domain:
Proof
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2

authentication

Authentication method

See the formal definition of the term.

Type
VerificationRelationship
stable
Range:
VerificationMethod
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2,
https://www.w3.org/ns/did/v1,
https://www.w3.org/ns/cid/v1

assertionMethod

Assertion method

See the formal definition of the term.

Type
VerificationRelationship
stable
Range:
VerificationMethod
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2,
https://www.w3.org/ns/did/v1,
https://www.w3.org/ns/cid/v1

capabilityDelegationMethod

Capability delegation method

See the formal definition of the term.

Historically, this property has often been expressed using `capabilityDelegation` as a shortened term in JSON-LD. Since this shortened term and its mapping to this property are in significant use in the ecosystem, the inconsistency between the short term name (`capabilityDelegation`) and the property identifier (`...#capabilityDelegationMethod`) is expected and should not trigger an error.
Type
VerificationRelationship
stable
Range:
VerificationMethod
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2,
https://www.w3.org/ns/did/v1,
https://www.w3.org/ns/cid/v1

capabilityInvocationMethod

Capability invocation method

See the formal definition of the term.

Historically, this property has often been expressed using `capabilityInvocation` as a shortened term in JSON-LD. Since this shortened term and its mapping to this property are in significant use in the ecosystem, the inconsistency between the short term name (`capabilityInvocation`) and the property identifier (`...#capabilityInvocationMethod`) is expected and should not trigger an error.
Type
VerificationRelationship
stable
Range:
VerificationMethod
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2,
https://www.w3.org/ns/did/v1,
https://www.w3.org/ns/cid/v1

keyAgreementMethod

Key agreement protocols

See the formal definition of the term.

Historically, this property has often been expressed using `keyAgreement` as a shortened term in JSON-LD. Since this shortened term and its mapping to this property are in significant use in the ecosystem, the inconsistency between the short term name (`keyAgreement`) and the property identifier (`...#keyAgreementMethod`) is expected and should not trigger an error.
Type
VerificationRelationship
stable
Range:
VerificationMethod
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2,
https://www.w3.org/ns/did/v1,
https://www.w3.org/ns/cid/v1

cryptosuite

Cryptographic suite

See the formal definition of the term.

stable
Range:
cryptosuiteString
Domain:
DataIntegrityProof
Relevant @contexts:
https://w3id.org/security/data-integrity/v2,
https://www.w3.org/ns/credentials/v2

publicKeyMultibase

Public key multibase

See the formal definition of the term.

See also:
multibase
multicodec
stable
Range:
multibase
Domain:
Multikey
Relevant @contexts:
https://w3id.org/security/multikey/v1,
https://www.w3.org/ns/cid/v1

secretKeyMultibase

Secret key multibase

See the formal definition of the term.

See also:
multibase format
multicodec format
stable
Range:
multibase
Domain:
Multikey
Relevant @contexts:
https://w3id.org/security/multikey/v1,
https://www.w3.org/ns/cid/v1

publicKeyJwk

Public key JWK

See the formal definition of the term.

See also:
IANA JOSE
RFC 7517
stable
Range:
rdf:JSON
Domain:
JsonWebKey
Relevant @contexts:
https://w3id.org/security/jwk/v1,
https://www.w3.org/ns/cid/v1

secretKeyJwk

Secret key JWK

See the formal definition of the term.

See also:
IANA JOSE
RFC 7517
stable
Range:
rdf:JSON
Domain:
JsonWebKey
Relevant @contexts:
https://w3id.org/security/jwk/v1,
https://www.w3.org/ns/cid/v1

revoked

Revocation time

See the formal definition of the term.

stable
Range:
xsd:dateTime
Domain:
VerificationMethod
Relevant @contexts:
https://w3id.org/security/jwk/v1,
https://www.w3.org/ns/cid/v1,
https://w3id.org/security/multikey/v1

digestMultibase

Digest multibase

See the formal definition of the term.

(Feature at Risk) The Working Group is currently attempting to determine whether cryptographic hash expression formats can be unified across all of the VCWG core specifications. Candidates for this mechanism include `digestSRI` and `digestMultibase`.
stable
Range:
multibase
Relevant @context:
https://www.w3.org/ns/credentials/v2

Class definitions

The following are class definitions in the sec namespace.

ControlledIdentifierDocument

Controlled Identifier Document

See the formal definition of the term.

stable
In the domain of:
controller

Proof

Digital proof

See the formal definition of the term.

This class represents a digital proof on serialized data.
stable
Range of:
previousProof
Domain of:
domain, challenge, previousProof, proofPurpose, proofValue, created, nonce
In the domain of:
expiration

ProofGraph

An RDF Graph for a digital proof

Instances of this class are RDF Graphs [[RDF11-CONCEPTS]], where each of these graphs must include exactly one Proof instance.
stable
Range of:
proof

VerificationMethod

Verification method

See the formal definition of the term.

Instances of this class must be denoted by URLs, i.e., they cannot be blank nodes.
stable
Range of:
verificationMethod, authentication, assertionMethod, capabilityDelegationMethod, capabilityInvocationMethod, keyAgreementMethod
Domain of:
revoked
In the domain of:
controller, expiration

VerificationRelationship

Verification relationship

See the formal definition of the term.

Instances of this class are verification relationships like, for example, authentication or assertionMethod. These resources can also appear as values of the proofPurpose property.
stable
Subclass of:
rdf:Property
Range of:
proofPurpose

DataIntegrityProof

A Data Integrity Proof

See the formal definition of the term.

stable
Subclass of:
Proof
Domain of:
cryptosuite

Multikey

Multikey Verification Method

See the formal definition of the term.

See also:
EdDSA Cryptosuites
ECDSA Cryptosuites
BBS Cryptosuites
stable
Subclass of:
VerificationMethod
Domain of:
publicKeyMultibase, secretKeyMultibase
Relevant @contexts:
https://w3id.org/security/multikey/v1,
https://www.w3.org/ns/cid/v1

JsonWebKey

JSON Web Key Verification Method

See the formal definition of the term.

stable
Subclass of:
VerificationMethod
Domain of:
publicKeyJwk, secretKeyJwk
Relevant @contexts:
https://w3id.org/security/jwk/v1,
https://www.w3.org/ns/cid/v1

Ed25519VerificationKey2020

ED2559 Verification Key, 2020 version

See the formal definition of the term.

stable
Subclass of:
VerificationMethod

Ed25519Signature2020

Ed25519 Signature Suite, 2020 version

See the formal definition of the term.

stable
Subclass of:
Proof

ProcessingError

Processing error

See the formal definition of the term.

stable

Datatype definitions

The following are datatype definitions in the sec namespace.

cryptosuiteString

Datatype for cryptosuite Identifiers

See the formal definition of the term.

stable
Derived from:
xsd:string
Range of:
cryptosuite
Relevant @context:
https://w3id.org/security/data-integrity/v2

multibase

Datatype for multibase values

See the formal definition of the term.

stable
Derived from:
xsd:string
Range of:
proofValue, publicKeyMultibase, secretKeyMultibase, digestMultibase
Relevant @context:
https://w3id.org/security/multikey/v1

Definitions for individuals

The following are definitions for individuals in the sec namespace.

PROOF_GENERATION_ERROR

Proof generation error

See the formal definition of the term.

stable
Type
ProcessingError

PROOF_VERIFICATION_ERROR

Malformed proof

See the formal definition of the term.

stable
Type
ProcessingError

PROOF_TRANSFORMATION_ERROR

Mismatched proof purpose

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_DOMAIN_ERROR

Invalid proof domain

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_CHALLENGE_ERROR

Invalid challenge

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_VERIFICATION_METHOD_URL

Invalid verification method URL

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_CONTROLLED_IDENTIFIER_DOCUMENT_ID

Invalid controlled identifier document id

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_CONTROLLED_IDENTIFIER_DOCUMENT

Invalid controlled identifier document

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_VERIFICATION_METHOD

Invalid verification method

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_RELATIONSHIP_FOR_VERIFICATION_METHOD

Invalid relationship for verification method

See the formal definition of the term.

stable
Type
ProcessingError

Reserved terms

All terms in this section are reserved. Implementers may use these properties, but should expect them and/or their meanings to change during the process to normatively specify them.

Reserved properties

The following are reserved property definitions in the sec namespace.

allowedAction

Allowed action (reserved)

See the formal definition of the term.

reserved

capabilityChain

Capability chain (reserved)

See the formal definition of the term.

reserved

capabilityAction

Capability action (reserved)

See the formal definition of the term.

reserved

caveat

Caveat (reserved)

See the formal definition of the term.

reserved

delegator

Delegator (reserved)

See the formal definition of the term.

reserved

invocationTarget

Invocation target (reserved)

See the formal definition of the term.

reserved

invoker

Invoker (reserved)

See the formal definition of the term.

reserved

Deprecated terms

All terms in this section are deprecated, and are only kept in this vocabulary for backward compatibility.

New applications should not use them.

Deprecated properties

The following are deprecated property definitions in the sec namespace.

blockchainAccountId

Blockchain account ID (deprecated)

See the formal definition of the term.

deprecatedtrue
Range:
xsd:string

ethereumAddress

Ethereum address (deprecated)

See the formal definition of the term.

See also:
EIP-55
Ethereum Yellow Paper: Ethereum: a secure decentralised generalised transaction ledger
deprecatedtrue
Range:
xsd:string

publicKeyBase58

Base58-encoded Public Key (deprecated)

See the formal definition of the term.

deprecatedtrue
Range:
xsd:string

publicKeyPem

Public key PEM (deprecated)

See the formal definition of the term.

deprecatedtrue
Range:
xsd:string

publicKeyHex

Hex-encoded version of public Key (deprecated)

See the formal definition of the term.

See also:
rfc4648
deprecatedtrue
Range:
xsd:string

jws

Json Web Signature (deprecated)

See the formal definition of the term.

See also:
Detached JSON Web Signature
deprecatedtrue

Deprecated classes

The following are deprecated class definitions in the sec namespace.

Key

Cryptographic key (deprecated)

This class represents a cryptographic key that may be used for encryption, decryption, or digitally signing data. This class serves as a supertype for specific key types.
deprecatedtrue

EcdsaSecp256k1Signature2019

ecdsa-sep256k1, 2019 version (deprecated)

See the formal definition of the term.

deprecatedtrue

EcdsaSecp256k1Signature2020

ecdsa-sep256k1, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

EcdsaSecp256k1VerificationKey2019

ecdsa-secp256k1 verification key, 2019 version (deprecated)

See the formal definition of the term.

deprecatedtrue
Subclass of:
Key

EcdsaSecp256k1RecoverySignature2020

ecdsa-secp256k1 recovery signature, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

EcdsaSecp256k1RecoveryMethod2020

ecdsa-secp256k1 recovery method, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

MerkleProof2019

Merkle Proof (deprecated)

See the formal definition of the term.

deprecatedtrue

X25519KeyAgreementKey2019

X25519 Key Agreement Key, 2019 version (deprecated)

See the formal definition of the term.

deprecatedtrue

Ed25519VerificationKey2018

ED2559 Verification Key, 2018 version (deprecated)

See the formal definition of the term.

deprecatedtrue

JsonWebKey2020

JSON Web Key, 2020 version (deprecated)

See the formal definition of the term.

A linked data proof suite verification method type used with `JsonWebSignature2020`
deprecatedtrue

JsonWebSignature2020

JSON Web Signature, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

BbsBlsSignature2020

BBS Signature, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

BbsBlsSignatureProof2020

BBS Signature Proof, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

Bls12381G1Key2020

BLS 12381 G1 Signature Key, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

Bls12381G2Key2020

BLS 12381 G2 Signature Key, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

Diagram description

Overview diagram of the vocabulary (without the reserved and deprecated items, error codes, and `xsd` datatypes).

The diagram uses boxes, ellipses, and connecting lines with different "styles" (border color, end marker, line type) to differentiate their semantic meaning: "Property", "Class", and "Datatype" are identified by the shape of the graph node (e.g., an ellipse signifies a "Class"); "Superclass", "Domain Of", "Range", "Type", and "Contains" relationships are identified by the style of the connecting line. These style names are used in the explanation text that follows, below.

The diagram is roughly divided into three sections — lower left, lower right, and upper. To make this description easier to understand, these sections will be respectively referred to as the "Proof", "Verification Method", and "Verification Relationship" sections. Shapes in the three sections are connected by lines of different styles; additionally, one box, labeled as "multibase" and shaped as "Datatype", bridges the two lower sections ("Proof" and "Verification Method").

Each of these sections has an ellipse at the top, labeled as "Proof", "VerificationMethod", and "VerificationRelationship", respectively. The Verification Method section includes an additional ellipse, labeled as "ControllerDocument", side-by-side with the ellipse labeled as "VerificationMethod".

Proof Section

The left side of the section contains another ellipse, labeled as "ProofGraph", and connected with a line styled as "Contains" to the "Proof" ellipse. A separate box, styled as "Property" and labeled as "proof", is connected with a line styled as "Range" to the "ProofGraph" ellipse.

There are two more ellipses in this section, labeled as "Ed25519Signature2020" and "DataIntegrityProof", and each connected to the "Proof" ellipse with lines styled as "Superclass". The "DataIntegrityProof" ellipse is also connected to a box, styled as "Property" and labeled as "cryptosuite", with a line styled as "Domain Of". The "cryptosuite" Property box is connected to a shape, styled as "Datatype" and labeled as "cryptosuiteString", with a line styled as "Range".

The right side of the section contains a column of labeled boxes, all styled as "Property". The labels, from top to bottom, are "previousProof", "domain", "challenge", "nonce", "created", and "proofValue". The "Proof" ellipse is connected to all of these boxes with lines styled as "Domain Of". The "previousProof" box is also connected to the "Proof" ellipse, with a line styled as "Range". The "proofValue" box is connected to a shape, styled as "Datatype" and labeled as "multibase", with a line styled as "Range". Finally, the same "multibase" "Datatype" shape is connected to another box, styled as "Property" and labeled as "digestMultibase", with a line styled as "Range".

Verification Method Section

The left side of this section contains a column of three labeled boxes, all styled as "Property". The labels, from top to bottom, are "controller", "expires", and "revoked". Each of these is connected to the "VerificationMethod" ellipse, with a line styled as "Domain Of". The "controller" "Property" box is also connected to the "ControllerDocument" ellipse, while the "expires" "Property" box is also connected to the "Proof" ellipse (in the Proof section); both of these extra connecting lines are styled as "Domain Of".

There is also a distinct box, styled as "Property" and labeled as "verificationMethod". This "verificationMethod" box is connected to the "VerificationMethod" ellipse, with a connecting line styled as "Range".

The middle of this section contains three more ellipses, labeled as "Multikey, "Ed25519VerificationKey2020", and "JsonWebKey". Each of these is connected to the "VerificationMethod" ellipse, with a line styled as "Superclass".

Two boxes, styled as "Property" and labeled as "secretKeyMultibase" and "publicKeyMultibase", are connected to the ellipse labeled as "Multikey" with a line styled as "Domain Of". Each of these boxes is also connected to the "multibase" "Datatype" shape in the Proof section, with lines styled as "Range".

Finally, two boxes, styled as "Property" and labeled as "secretKeyJwk" and "publicKeyJwk", are connected to the "JsonWebKey" ellipse, with a line styled as "Domain Of". Both boxes are also connected to a shape, styled as "Datatype" and labeled as "rdf:JSON", with lines styled as "Range".

Verification Relationship Section

The left side of the section contains a single box, styled as "Property" and labeled as "proofPurpose". This box is connected to the "VerificationRelationship" ellipse, with a line styled as "Range". It is also connected to the "Proof" ellipse in the Proof section, with a line styled as "Domain Of".

The right side of the section contains a column of labeled boxes, all styled as "Property". The labels, from top to bottom, are "verificationMethod", "authentication", "assertionMethod", "capabilityDelegation", "capabilityInvocation", and "keyAgreement". Each of these boxes is connected to the "VerificationMethod" ellipse in the Verification Method section, with a line styled as "Range". Finally, each of these boxes is also connected to the "VerificationRelationship" ellipse, with a line styled as "Type".