Allow generic/unwrapped VC/VP and specific media types where appropriate

[filip26]

Hi,
all endpoints mandate application/json, and some allow to return a generic, unwrapped, VC/VP.

Please consider to allow generic representations and media types where appropriate, e.g. application/vc, application/vp.

Candidates to consume/produce generic VC/VP

• Issue Credential
• Get Credential
• Verify Credential
• Verify Presentation
• Create Presentation
• Get Presentation

[msporny]

The group discussed this on the 2025-01-14 telecon:

@dlongley noted that this might define an API that is subtly different from what we are doing. The VC API currently is a JSON API so we can put whatever parameters/options that we need to into the message bodies and responses. Data transferred back and forth is encapsulated. If we use unwrapped VC/VPs, we couldn't provide options or other metadata along w/ API call options. There might be cases where this might work, JSON API could return another URL that speaks "raw" format -- might be other ways to shoehorn it in without reinventing the API shape. Struggling to see the use cases or benefits. @msporny noted that adding six new endpoints would be problematic -- we could use "?raw" as a query parameter, but use case isn't clear for unwrapped VCs/VPs. @dlongley sounds like new API endpoints -- what does it mean to just receive raw data and respond -- those discussions feel like they'd be different for all API endpoints -- this sounds like an alternative API that we'd have to examine on a case-by-case basis for existing API endpoints. Does additional implementation/spec/interop burden make sense? Needs a strong justification from interop perspective that goes beyond needing to put something inside of a wrapper.

@filip26 group would like to understand the use cases that would benefit from the API change as well as some thoughts on the above concerns wrt. extra effort for implementers and interop.

[filip26]

It's not about adding new endpoints, but rather enabling - at the very least, leaving it optional for implementers - to use the Content-Type and Accept headers to control what is sent and preferred to get.

The listed endpoints could be used by multiple actors (verifier, holder, issuer).

Take the "Get a Credential" endpoint, for example. It returns a valid VC as the body, but if the Accept header is set to application/vc, it returns application/json instead.

Similarly, the "Verify Credential" endpoint, which validates the model and verifies a signature, requires a custom object to be passed that wraps a VC and some options (three booleans). It's much simpler and straightforward to pass a VC directly as application/vc, particularly in the most common use case where you don’t need to manipulate the options.

And so on.

[filip26]

Interestingly, neither application/vc nor application/vp is used or allowed by any of the endpoints.

[filip26]

Update /credentials/{{id}} endpoint to return {verifiableCredential} to be consistent with other APIs - #398

[PatStLouis]

Following #458 it seems the group has decided to not return other content-type than application/json. Content negotiation could be left up to the implementation but officially support by the specification.

Maybe a note can be included as an appendix about this?

[msporny]

The group discussed this on the 2025-06-03 call and decided that the specification only specifies the use of application/json. You can do other things, such as what this issue suggests, but we don't want to suggest it as an option as it would lead to less interoperability.

We always encourage experiments in the field, which help guide future work on the specification based on implementation experience.

The group suggested that this be marked pending close and will wait two weeks for feedback from @filip26 before closing.