This specification describes mechanisms to apply the Overlays Capture Architecture to Verifiable Credentials as a Render Method.

This is an experimental specification and is undergoing regular revisions. It is not fit for production deployment.

Introduction

Terminology

A conforming render method is any concrete expression of the data model that complies with the normative statements in this specification. Specifically, all relevant normative statements in Sections and of this document MUST be enforced.

A conforming processor is any algorithm realized as software and/or hardware that generates or consumes a conforming render method. Conforming processors MUST produce errors when non-conforming documents are consumed.

This document also contains examples that contain JSON and JSON-LD content. Some of these examples contain characters that are invalid JSON, such as inline comments (`//`) and the use of ellipsis (`...`) to denote information that adds little value to the example. Implementers are cautioned to remove this content if they desire to use the information as valid JSON or JSON-LD.

Data Model

The following sections outline the data model that is used by this specification for rendering methods

OverlaysCaptureBundle Entry

When an issuer desires to specify an OCA Bundle for a verifiable credential, they MAY add a `renderMethod` property that uses the data model described below.

Property Description
id A URL that dereferences to an JSON document [[JSON]] with a valid SAID file name.
type The type property MUST be OverlaysCaptureBundle.
bundleVersion The bundle version provided by the issuer used to define OCA Object types.
overlayNames The overlay names provided by the issuer. These strings MUST map to an overlay's type after pairing it with the version like so "spec/overlays/{overlayName}/{version}".
supportedLanguages The language support provided by the issuer. These values can be used to querry the desired OCA Objects. The following OCA Object names support language: information, label, meta and entry

An entry of the data model shown above is expressed in a renderMethod section in the example below. 

{
  "renderMethod": [
    {
      "id": "https://oca.opsec.id/bundles/EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis.json",
      "type": "OverlaysCaptureBundle",
      "bundleVersion": "1.0",
      "overlayNames": [ "information", "label", "cardinality", "mapping" ],
      "supportedLanguages": [ "en", "fr" ]
    }
  ]
}

In the example above, the issuer has provided an OCA Bundle for a bachelor's degree that will provide additional information to the verifiable credential.

OverlaysCaptureBundle Object

An OCA bundle consists of a Capture Base and a series of cryptographically bound Overlays.

Capture Base

{
   "type":"spec/capture_base/1.0",
   "classification":"",
   "attributes":{
	"$.credentialSubject.degree.type": "Array[Text]",
	"$.credentialSubject.degree.name": "Text"
   },
   "flagged_attributes":[]
}

Bound Overlays

{
   "capture_base":"EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis",
   "type":"spec/overlays/information/1.0",
   "language":"en",
   "attribute_information":{
	"$.credentialSubject.degree.name": "The name of the degree."
   }
}

{
  "capture_base":"Ev_RaB-gIOn8VAB3sg40mINxjiYRxdLVQrgce0aZbFcc",
  "type":"spec/overlays/cardinality/1.0",
  "attr_cardinality":{
    "$.credentialSubject.degree.type":"1"
  }
}

{
  "capture_base":"Ev_RaB-gIOn8VAB3sg40mINxjiYRxdLVQrgce0aZbFcc",
  "type":"spec/overlays/mapping/1.0",
  "attribute_mapping":{
    "$.credentialSubject.degree.name":"degreeName"
  }
}

Algorythms

These algorythms instruct how to apply an OCA bundle to a Verifiable Credential.

Creating an OCA Bundle

Get JSON path array from VC

Define the Capture Base attributes

Create desired overlays

Publish OCA Bundle

Add entry to Verifiable Credential

Applying an OCA Bundle

Get JSON path array from VC

An implementer MAY ignore the @context of the VC when genereting the array or remove the corresponding paths.

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2",
    "https://w3id.org/vc/render-method/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "UniversityDegreeCredential"
  ],
  "issuer": "https://example.edu/issuers/14",
  "validFrom": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  },
  "renderMethod": [
    {
      "id": "https://oca.opsec.id/bundles/EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis.json",
      "type": "OverlaysCaptureBundle",
      "bundleVersion": "1.0",
      "overlayNames": [ "information", "label", "cardinality", "mapping" ],
      "supportedLanguages": [ "en", "fr" ]
    }
  ]
}

$.id
$.type
$.type[0]
$.type[1]
$.issuer
$.validFrom
$.credentialSubject
$.credentialSubject.id
$.credentialSubject.degree
$.credentialSubject.degree.type
$.credentialSubject.degree.name
$.renderMethod
$.renderMethod[0]
$.renderMethod[0].id
$.renderMethod[0].type
$.renderMethod[0].overlayType
$.renderMethod[0].overlayType[0]
$.renderMethod[0].language
$.renderMethod[0].language[0]
$.renderMethod[0].language[1]

Resolve Bundle Object

Do a GET request on the id to fetch the OCA Bundle Object.

{
  "type": "spec/capture_base/1.0",
  "classification": "",
  "attributes": {
    "$.credentialSubject.degree.type": "Array[Text]",
    "$.credentialSubject.degree.name": "Text"
  },
  "flagged_attributes": [],
  "overlays": [
    {
      "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis",
      "type": "spec/overlays/information/1.0",
      "language": "en",
      "attribute_information": {
        "$.credentialSubject.degree.name": "The name of the degree obtained by the subject."
      }
    },
    {
      "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis",
      "type": "spec/overlays/information/1.0",
      "language": "fr",
      "attribute_information": {
        "$.credentialSubject.degree.name": "Le nom du Diplôme obtenu par le sujet."
      }
    },
    {
      "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis",
      "type": "spec/overlays/label/1.0",
      "language": "en",
      "attribute_labels": {
        "$.credentialSubject.degree.name": "Degree Name"
      }
    },
    {
      "capture_base": "EVyoqPYxoPiZOneM84MN-7D0oOR03vCr5gg1hf3pxnis",
      "type": "spec/overlays/label/1.0",
      "language": "fr",
      "attribute_labels": {
        "$.credentialSubject.degree.name": "Nom du diplôme"
      }
    },
    {
      "capture_base": "Ev_RaB-gIOn8VAB3sg40mINxjiYRxdLVQrgce0aZbFcc",
      "type": "spec/overlays/cardinality/1.0",
      "attr_cardinality": {
        "$.credentialSubject.degree.type": "1"
      }
    },
    {
      "capture_base": "Ev_RaB-gIOn8VAB3sg40mINxjiYRxdLVQrgce0aZbFcc",
      "type": "spec/overlays/mapping/1.0",
      "attribute_mapping": {
        "$.credentialSubject.degree.name": "degreeName"
      }
    }
  ]
}

Validate Capture Base

Verify the integrity with the SAID component of the URL.

Query Overlays

Query the available overlays with the desired language, overlay name and JSON path.

Security Considerations

Self-Addressing IDentifier (SAID)

SAID are used as a cryptographic integrity mechanism for OCA Objects.

Privacy Considerations

Flagged Attributes

The Capture Base can flag sensitive attributes.

Application Use Cases

The complete list of applications can be found here. Below is an overview.

Data transformation

Object presentation

Internationalisation