Common credential schemas

Edit online

Credential schemas are reusable across multiple credential definitions. This enables the same schema to be instantiated in different credential formats. For example, mso_mdoc and SD-JWT.

Enhancements that are introduced in the v2.0 credential schemas API in IBM® Verify Identity Access Digital Credentials version 25.06 support the reuse capability.

To use this feature, define the credential schema by using the schema attribute. The schema attribute defines the structure in JSON Schema format. Specific attributes can be added to support different use cases, depending on the credential format and protocol requirements.

JSON-LD support with common credential schemas

To use a credential schema with JSON-LD credentials, include the proprietary $linkedData attributes throughout the schema. These attributes define the necessary elements for automatically constructing context values in the resulting JSON-LD credentials.

For example, the top-level $linkedData definition:

"$linkedData": {
        "identifier": "Person",
        "@id": "https://www.mydemo.org/schemas/Person",
        "@vocab": "https://www.mydemo.org/schemas/Person#",
},

For example, attribute-level $linkedData for given_name:

"given_name": {
            "$linkedData": {
                "identifier": "given_name", 
                "@id": "https://www.mydemo.org/schemas/Person#given_name"
            },
            "type":"string",
},

OpenID for Verifiable Credential Issuance (OID4VCI) support with common credential schemas

To support rich Credential Issuer Metadata in the OID4VCI protocol, include the proprietary $oid4vc attributes throughout the schema.

For example, the top-level $oid4vc display metadata:

"$oid4vc": {
        "display": [
            {
                "name": "Person Credential",
                "locale": "en-US",
                "logo": {
                    "uri": "https://www.myexample.org/public/logo.png",
                    "alt_text": "a square logo",
                },
                "background_color": "#12107c",
                "text_color": "#FFFFFF",
            },
        ],
},

For example, attribute-level $oid4vc display metadata for given_name:

"given_name": {
            "$oid4vc": {
                "display": [
                    {
                        "name": "Given Name",
                        "locale": "en-US",
                    },
                    {
                        "name": "名前",
                        "locale": "ja-JP",
                    },
                ],
            },
            "type":"string",
},

SD-JWT selective disclosure support

The SD-JWT credential format supports selective disclosure. An issuer can mandate the disclosure of specific attributes during every credential presentation or delegate that authority to the holder.

To configure this behavior in a credential schema, set the $allowSelectiveDisclosure property on the attribute. If you set this property to false, the attribute is always disclosed to the verifier when the holder presents the credential. If you set it to true, the holder can choose whether to disclose the attribute to the verifier.

If the $allowSelectiveDisclosure property is not specified, the system defaults to true.

For example, attribute-level $allowSelectiveDisclosure for given_name:

"given_name": {
    "$allowSelectiveDisclosure": false,
    "type":"string",
},