This document proposes a user experience for generating example credentials.
These credentials can then be "issued" to become [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/).

## The objective

Allow a user to be able to generate an credential, with the help of a TreeLDR file that defines the data that should be in `credentialSubject` property.

An example credential that would be output from the tooling:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    {
      "Device": {
        "@id": "https://vc-context.elia.be/2022/v1/Device",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "brandName": "https://saref.etsi.org/saref4ener/brandName",
          "deviceCode": "https://saref.etsi.org/saref4ener/deviceCode"
        }
      },
      "DeviceInfoCredential": "https://vc-context.elia.be/2022/v1/DeviceInfoCredential"
    }
  ],
  "type": [
    "VerifiableCredential",
    "DeviceInfoCredential"
  ],
  "credentialSubject": {
    "type": "Device",
    "id": "deviceIdScheme:123",
    "brandName": "Device Manufacturer Inc",
    "deviceCode": "device 123"
  }
}

The TreeLDR file for this credential:

base <https://vc-context.elia.be/2022/v1/>;
use <http://www.w3.org/2001/XMLSchema#> as xs;
use <https://saref.etsi.org/saref4ener/> as saref4ener;

property saref4ener:brandName: xs:string;
property saref4ener:deviceCode: xs:string;

type Device {
  saref4ener:brandName,
  saref4ener:deviceCode
}

## Tool Operational Sequence

### 0. The tool starts with credential scaffolding

All (v1) Verifiable Credentials will have `"https://www.w3.org/2018/credentials/v1"` in their context array and will be of type `VerifiableCredential`.
Therefore, the tooling can start with this scaffolding from which to build the credential.

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
  ],
  "type": [
    "VerifiableCredential"
  ]
}

### 1. Generating the credential subject JSON-LD context

To start, the user provides the tooling with a TreeLDR file and the IRI of the subject type.
For example, the user would provide:
1. TreeLDR file path: `device-info.tldr`
2. Type IRI: `https://vc-context.elia.be/2022/v1/DeviceInfo`

From the TreeLDR file, the tool runs the `json-ld` compilation.

Example TreeLDR compiler (`tldrc`) command (which would be run internally by the tool):

tldrc -i device-info.tldr json-ld-context https://vc-context.elia.be/2022/v1/DeviceInfo

In the above, `device-info.tldr` is the TreeLDR file and `https://vc-context.elia.be/2022/v1/Device` is the IRI of the credential subject type.

Given a TreeLDR file as shown previously, the command output would be:

{
  "brandName": "https://saref.etsi.org/saref4ener/brandName",
  "deviceCode": "https://saref.etsi.org/saref4ener/deviceCode"
}

The tool would take the above output and place into the following template JSON:

{
  {{Last fragement of the IRI}}: {
    "@id": {{Subject Type IRI}},
    "@context": {
      "@version": 1.1,
      "@protected": true,
      {{Properties from JSON-LD compilation}}
    }
  }
}

The result for our example would be:

{
  "Device": {
    "@id": "https://vc-context.elia.be/2022/v1/Device",
    "@context": {
      "@version": 1.1,
      "@protected": true,
      "brandName": "https://saref.etsi.org/saref4ener/brandName",
      "deviceCode": "https://saref.etsi.org/saref4ener/deviceCode"
    }
  }
}

The tooling can then add this context to the credential.
For our example, the credential would now be:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    {
      "Device": {
        "@id": "https://vc-context.elia.be/2022/v1/Device",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "brandName": "https://saref.etsi.org/saref4ener/brandName",
          "deviceCode": "https://saref.etsi.org/saref4ener/deviceCode"
        }
      }
    }
  ],
  "type": [
    "VerifiableCredential"
  ]
}

### 2. Generating the credentialSubject data

Currently, there is no way to provide an example value in a TreeLDR file.

Therefore, to get values to populate the `credentialSubject` property, the tooling can prompt the user to enter values that match the JSON schema for the type of the credential subject.

From the TreeLDR file, the tool runs the `json-schema` compilation.

Example TreeLDR compiler (`tldrc`) command (which would be run internally by the tool):

tldrc -i device-info.tldr json-schema https://vc-context.elia.be/2022/v1/Device

This results in the follow JSON schema:

{
  "type": "object",
  "properties": {
    "deviceCode": {
      "$ref": "http://www.w3.org/2001/XMLSchema#string"
    },
    "brandName": {
      "$ref": "http://www.w3.org/2001/XMLSchema#string"
    }
  },
  "$id": "https://vc-context.elia.be/2022/v1/Device",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Device"
}

The tooling can now prompt the user for `deviceCode` & `brandName` and make sure that they are `string`, as per the schema.

Finally, the tooling should prompt the user for the `id` of the `credentialSubject`.

After collecting the values from the user, the tool can now add a `crdentialSubject` property.
The credential would then be:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    {
      "Device": {
        "@id": "https://vc-context.elia.be/2022/v1/Device",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "brandName": "https://saref.etsi.org/saref4ener/brandName",
          "deviceCode": "https://saref.etsi.org/saref4ener/deviceCode"
        }
      }
    }
  ],
  "type": [
    "VerifiableCredential"
  ],
  "credentialSubject": {
    "type": "Device",
    "id": "deviceIdScheme:123",
    "brandName": "Device Manufacturer Inc",
    "deviceCode": "device 123"
  }
}

The `type` of the `credentialSubject` is taken from the previous step.

### 3. Add Credential Type IRI

The tooling prompts the user for an IRI for the credential type.
This IRI can then be put directly in the `type` array or the context array can be used.

If using the context approach, the resulting credential would be:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    {
      "Device": {
        "@id": "https://vc-context.elia.be/2022/v1/Device",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "brandName": "https://saref.etsi.org/saref4ener/brandName",
          "deviceCode": "https://saref.etsi.org/saref4ener/deviceCode"
        }
      },
      "DeviceInfoCredential": "https://vc-context.elia.be/2022/v1/DeviceInfoCredential"
    }
  ],
  "type": [
    "VerifiableCredential",
    "DeviceInfoCredential"
  ],
  "credentialSubject": {
    "type": "Device",
    "id": "deviceIdScheme:123",
    "brandName": "Device Manufacturer Inc",
    "deviceCode": "device 123"
  }
}

The JSON-LD processing of the above credential can be tested using the [JSON-LD Playground](https://json-ld.org/playground/)

## User Interface

A user could interface with the above process in various ways.
For example:
1. A CLI application could be written where the user types in values from a shell
2. A web API could be exposed that takes a TreeLDR file, a subject type IRI, a credential type IRI and a credential subject data file

## Discussion

This approach uses an "in-line" context.
However, it could be possible to rearrange the steps to generate a context file that can be stored externally and then referenced from the credential.