rework credential and batch credential endpoint

[paulbastian]

Closes #93

• [ ] discuss whether proofs array should only contain the key values with the same key type instead of each object containing proof_type
• [x] add issuer metadata for support of proofs in credential endpoint
• [x] agree whether to keep or scrap batch credential endpoint or postpone the discussion

[manecke]

The example in the "Batch Credential Request" section seems to be broken (in the proofs array). There are too many curly braces. The indentation does not seem to be correct either.

[manecke]

The square brackets are also not set correctly. The closing brackets are missing several times.

[manecke]

POST /batch_credential HTTP/1.1
Host: [server.example.com](http://server.example.com/)
Content-Type: application/json
Authorization: BEARER czZCaGRSa3F0MzpnWDFmQmF0M2JW
{
   "credential_requests":[
      {
         "format":"jwt_vc_json",
         "credential_definition":{
            "type":[
               "VerifiableCredential",
               "UniversityDegreeCredential"
            ]
         },
         "proofs":[
            {
               "credential_identifier":"BiologyEngineeringDegree-2023",
               "keys":[
                  {
                     "proof_type":"jwt",
                     "jwt":"eyJ0eXAiOiJvcGVuaWQ0dmNpL...Lb9zioZoipdP-jvh1WlA"
                  },
                  {
                     "proof_type":"jwt",
                     "jwt":"eyJraWQiOiJkaWQ6ZXhhbXBsZ...KPxgihac0aW9EkL1nOzM"
                  }
               ]
            },
            {
               "credential_identifier":"CivilEngineeringDegree-2023",
               "keys":[
                  {
                     "proof_type":"jwt",
                     "jwt":"eyJraWQiOiJkaWQ6ZXhhbXBsZ...KPxgihac0aW9EkL1nOzM"
                  }
               ]
            },
            {
               "credential_identifier":"ElectricalEngineeringDegree-2023",
               "keys":[
                  {
                     "proof_type":"jwt",
                     "jwt":"eyJraWQiOiJkaWQ6ZXhhbXBsZ...KPxgihac0aW9EkL1nOzM"
                  }
               ]
            }
         ]
      }
   ]
}

[paulbastian]

I've corrected the JSON structure.

The example that you posted is substantially different though.

[Sakurann]

if a mechanism to better issue multiple copies of the same credential dataset is added to credential endpoint in a backward compatible manner, I am ok having only one endpoint doing it. though we do need to discuss what it means on the mandatory to implement requirements - 1) we can scrap anything around MTI requirements, 2) say particular request (one credential or copies of the credential or multiple credential) is mandatory, 3) everything in credential endpoint is mandatory.

[paulbastian]

Following up the discussions from DCP Workshop on 19th of April, there are different options how to continue, so therefore please provide feedback/preferences. Please use emoji reaction of your choice to communicate your preferences.

[paulbastian]

A - make a breaking change to the Batch Credential Endpoint (current proposal - only proof[])

[paulbastian]

B - make the Batch Credential Request polymorphic (backwards compatible - proof and proofs[] are allowed)

[paulbastian]

C - make the Credential and Batch Credential Endpoint polymorphic (backwards compatible - proof and proofs[] are allowed)

[Sakurann]

We should add in this PR, credential issuer metadata parameter that the issuer uses to indicate how many credential copies it expects.

[bc-pi]

FWIW I would be in favor of the credential endpoint having a mechanism to issue multiple copies of the same credential dataset (and would be fine with the batch endpoint going away).

[paulbastian]

credential endpoint with proofs[] issuance of multiple credential istances has been tested successfully at IDunion hackathon at 23/24 of April between 4 participants!

[manecke]

Regarding API/DM design, it is crucial to develop the API/DM carefully and test it with as many examples as possible. It is important to avoid breaking changes in software frameworks under any circumstances. Therefore, maintaining backward compatibility is essential.

Many companies have already started implementing draft versions of OpenID4VC. In this case, I believe it is necessary to get rid of any legacy issues as soon as possible and introduce a consistent DM design/API. The OpenID4VC protocols and related data formats and messages are expected to be used across Europe. For this reason, resolving any conflicts with breaking changes should be done promptly. Otherwise, we will have to support poorly developed endpoints in the long term. This resolution should be done immediately considering the LSPs. Currently, there are no live EUDIW cases.

Having an API endpoint for issuing a single credential does not make sense. This can be achieved using the batch endpoint and requesting only one credential. The batch endpoint should always return a list, possibly with only one element. If backward compatibility is desired, the credential endpoint can be marked as deprecated and included.

Additionally, it is important to create a consistent data model. Having JSON arrays with different object types is not logical. It is important to note that a JSON array should only contain JSON objects of the same type. While JSON technically allows different types to be included in an array (valid json), it is not considered best practice.

Also it would also be desirable to provide three examples instead of demonstrating five different things at once in one example (for readablility).

[manecke]

If one were to remove the credential endpoint and retain only the batch endpoint, the URI could be renamed.

[paulbastian]

We should add in this PR, credential issuer metadata parameter that the issuer uses to indicate how many credential copies it expects.

done, please check

[peppelinux]

FWIW I would be in favor of the credential endpoint having a mechanism to issue multiple copies of the same credential dataset (and would be fine with the batch endpoint going away).

Yes, this would be preferable.

[bc-pi]

discuss whether proofs array should only contain the key values with the same key type instead of each object containing proof_type

That seems like it'd be the more intuitive/logical way to model the data but would also make it more cumbersome to reuse the proof/proof_type structure as the PR does now. 🤷

[paulbastian]

@tlodderstedt @Sakurann Reading Torsten's suggestion, I realized there is an inconsistency between proof in Credential Request and Batch Credential Request. Credential Request says its OPTIONAL and then later says this may be required depending on the Issuer metadata. Batch Credential Request says it is REQUIRED if the corresponding parameter was set in metadata. Torsten moved this to a note. What do you prefer?

[paulbastian]

discuss whether proofs array should only contain the key values with the same key type instead of each object containing proof_type

That seems like it'd be the more intuitive/logical way to model the data but would also make it more cumbersome to reuse the proof/proof_type structure as the PR does now. 🤷

@bc-pi I made some suggestion how request could look like. What do you think?

[bc-pi]

discuss whether proofs array should only contain the key values with the same key type instead of each object containing proof_type

That seems like it'd be the more intuitive/logical way to model the data but would also make it more cumbersome to reuse the proof/proof_type structure as the PR does now. 🤷

@bc-pi I made some suggestion how request could look like. What do you think?

In the case of ldp_vp (sigh) would proofs be an array of objects (based on one of the suggestions) or the proofs object have a ldp_vp member with an array of objects (the other suggestion)? As I mentioned before, this kind of thing seems like the right way to model the data but makes it more cumbersome to reuse the proof/proof_type structure or needs more definition of the pieces for the multiple proofs structure(s).

[paulbastian]

Discussions at DCP Call favored this direction:

"proofs": {
   "jwt": [
      "eyJ0eXAiOiJvcGVuaWQ0dmNpL...Lb9zioZoipdP-jvh1WlA",
      "eyJraWQiOiJkaWQ6ZXhhbXBsZ...KPxgihac0aW9EkL1nOzM"
   ]
}

[OR13]

Seems like the JSON could use the media type registrations, and not introduce new json members, like jwt, when you really mean application/jwt or application/vc+jwt, etc...

[paulbastian]

Seems like the JSON could use the media type registrations, and not introduce new json members, like jwt, when you really mean application/jwt or application/vc+jwt, etc...

Kristina asked to move this discussion to a separate Issue on DCP wg call

[paulbastian]

It was agreed last week, that the discussion about removing the batch credential issuance shall be done after merging this PR. Remaining point is on optimizing the proofs array, please check the latest proposal

[paulbastian]

@Sakurann @tlodderstedt and others. This PR is ready for merge from my side, please make a final review

[paulbastian]

Kristina and I resolved most issues and I merged main to get in the recent changes to Batch Credential Encryption. One minor discussion point currently remains: https://github.com/openid/OpenID4VCI/pull/293/files#r1616041792

[paulbastian]

@Sakurann @tlodderstedt @jogu @tplooker all comments resolved. Please take a final look.

[Sakurann]

WG call: tobias, Giuseppe, Christian (maybe Brian) to re-review. will merge once there are 4 approvals - hopefully within the next 1-2 days.

[Sakurann]

will continue the discussion on merging batch/credential endpoints in this issue: https://github.com/openid/OpenID4VCI/issues/18

[tplooker]

Approved on the proviso that my above minor suggestions are incorperated.