Correct the format property's name/location

Issue #1245 resolved
Daniel Buchner created an issue

The format declarations appear to be outside of the PE Definition object, under a vp_formats property, but does share the same format/alg/proof type syntax now (cheers for interop). Per the current spec, that property resides in the presentation_definition object itself, under a property named format. Is this property name/location something folks would be willing to accept a PR to adjust for interop sake? I just want to make sure it remains compatible with the PE libraries that will be looking for the format values under the specified property name/location where it is supposed to be found.

Comments (22)

  1. Anthony Nadalin

    I don’t understand the request as this specification is not a duplicate of the PE specification, changing the parent would not make it compatible

  2. Daniel Buchner reporter

    The goal is to enable spec-compliant PE use across all credential exchange envelope protocols, including the OIDC SIOP envelope. PE unifies credential requirement evaluation and submission across all envelope protocols, eliminating the vast majority of needlessly duplicative rework devs and implementers have to undertake across the ecosystem. To do that, this property/value should be put in the spec-compliant location.

  3. Torsten Lodderstedt

    Hi Daniel,

    in our interpretation, the format data is not request specific but tied to the capabilities of a certain verifier. In OpenID Connect, such capabilities are handled via client metadata. That’s the reason for moving it there. From an OpenID Connect OPs perspective, it is more effective to have all client metadata in one place instead of having to look into the client metadata and, additionally, the request. Happy do conduct an impact analysis with existing libraries. Can you point me to a library in .NET or Java we could have a look at?

    Moreover, PE does not seem to have a concept for publishing wallet/holder capabilities. So we used the same syntax to allow the wallet to publish its capabilities for the benefit of the verifiers.

  4. David Chadwick

    As I have said previously, I believe PE has adopted the wrong design model by combining the How (presentation format, a protocol issue) with the What (VC claims requirements). So OIDC is correct in separating these concerns, since OIDC has its own protocol for specifying How, and different protocols will specify different Hows. PE should leave the specification of How to the protocol that is carrying the PE requirements. Otherwise there can be a conflict between PE specifying a How that the carrying protocol cannot support.

  5. Daniel Buchner reporter

    @David - not sure what you are talking about when you say “PE specifies How”, given it completely avoids the How. It specifies requirements only, requirements about: format of the credentials, type/schema indicators to identify the correct credential, and content requirements of the credentials. Nowhere in PE does it talk about the outer envelope, where you send objects, what URLs to use, how many hops you should take, the UI presented, request response transport protocols you must use, etc. PE was explicitly designed to allow you to use the same What logic across all these different How protocols, and it already does that across them today. Please point to precisely what you mean by How with a specific spec reference, because I am aware of 0 places in the PE spec that dictate how these envelops must do their connections, transfers, redirects, transports, etc.

  6. David Chadwick

    The Format property specifies How the VC is to be presented, not What its contents are. Format is linked to the protocol for carrying VCs. Without the enhancements to OIDC that you have initiated, the format would have been JWT, as this is what the current OIDC protocol requires. There is no negotiation about this, and no need to specify this. The OIDC protocol specifies What claims are required and the wallet returns them as a JWT (the How). Without the new enhancements to support multiple formats including JSON-LD proofs, none of these enhancements would be needed. Better interworking would have been achieved by everyone using OIDC and producing VCs and VPs in JWT format. So by introducing multiple Hows into the OIDC extensions we are doing a dis-service to interworking. (I know that one of Tony’s criticisms of the W3C VC recommendation was that it did not specify one mandatory to implement proof mechanism, with additional optional ones if people wanted them. So this has led to the multiple Hows problem we have today.)

  7. Daniel Buchner reporter

    @David specifying what format an object is in is definitely not a How, it is a What - let’s use it in a simple sentence to illustrate: “I am telling you What format the data is in that I am sending you“ vs “I am telling you How format the data is in that I am sending you“. The format of a thing is an attribute of What it is, just as vetting the contents of a credential to ensure it contains What is required is also a What. PE is not a How spec, it is a What spec, and can be embedded in any How protocol to provide the exact same What logic across them all.

  8. Kristina Yasuda

    On 2021-06-25 call, we discussed the possibility of putting format property in the request and be compliant with the PE specification, but unanimously agreed that to keep the current choice.

    The Reason is: format element is not credential or presentation specific, it is a static information that applies to all the credentials and presentations that the client requests and OP can handle. In OpenID Connect, Server and Client metadata is typically where such information is being handled. 

    David C. said that this choice is consistent to his implementation experience.

  9. Daniel Buchner reporter

    If this is the course taken, I suppose we will have to add some language to the PE spec to note that when PE is used in OIDC SIOP, it may require including a copy of the format object in this SIOP-specific location (purely to route around any conformance tests), but continue to include the format object that is actually processed within the PE object, as specified. The only thing we can’t do from the PE side is break its processing, because then it breaks cross-envelope code/implementation interop.

    The other option is to simply create two profile that cleanly separate the PE and non-PE options:

    1. An option where the SIOP group does whatever they want - different property names, objects in whatever places, overlapping features, etc.
    2. An option to just use PE as is

    This way we can let devs decide: “Do I want something that works the same across all the envelope-transports I interact with, or do I want to use special case code?“

  10. Torsten Lodderstedt

    As far as I understand, the PE spec is in a review stage. You could also just interpret the way we utilize PE as feedback to your spec and try to accommodate for this style of use as well.

    PE could, for example, state that the format should be in the presentation definition but can be determined between sender and recipient using other platform specific means.

    The format element as specified in PE right now is a declaration of sender capabilities without any relationship to any input descriptor. That might be needed for DIDComm and similar protocols.

    But OIDC has a sophisticated metadata facility on both ends, which helps to determine formats and algorithms supported by the RP and even the formats available at the receiver side (before a request is even send). This helps to avoid error situations (because of incompatible formats) and negotiation messages contributing to the simplicity (and success) of OIDC. The way we utilize your format element integrates PE formats into OIDC seamlessly. That’s good for developers.

    I would see benefit in adding a format element to input descriptors to specify the expected format for a certain credential presentation. I think that would contribute to the robustness of the protocol as the path expressions, for example, are format specific. A clear definition of the format of the expected credential and presentation would reduce ambiguity.


  11. Daniel Buchner reporter

    @Torsten Lodderstedt Presentation Exchange is a fully Ratified specification in DIF: - but as I found out yesterday, it appears some folks had been looking at the Latest Draft (which is just the Main repo reflection of whatever would be coming in vNext, if there is a vNext), located here: The PE v1.0.0 spec was frozen at the end of 2020, and ratified through SC/member review in February after a 30 day open review period, wherein any final blocking comments were solicited via mailing list communications to multiple DIF and non-DIF channels. I realized last night the Latest Draft that shows whatever is in the Main branch did not link to the Ratified v1.0.0, which I immediately corrected to ensure clarity.

    While folks in the WG have been receptive to some of the requested changes (e.g. Tobias' desire to remove the OR ability from the schema/type URI section), which would result in v2-forcing breaking changes almost immediately after v1 was finished, the issue with making it so envelopes can relocate and mutate things that PE objects are expecting in a certain location/shape breaks deterministic transport-envelope agnostic processing of PE objects. This means that, in diametric opposition to the goal/point of PE, developers would return to having to special case code and track N-wise divergences across all transport envelopes. PE is analogous to having a single HTML Document standard (wherein PE ~= an HTML Doc) that has the same expected shape/composition regardless of the browser rendering it (wherein SIOP, DID Comms, CHAPI, VC Request API, etc. ~= different ‘browsers'). If someone says “My browser wants to compose/read HTML differently, and have the <head> element of an HTML Document to reside external to the HTML doc at some other location“, the resulting Kind-of-HTMLish-But-Not-Really Document will not be parsed correctly by any other browser that is expecting the specified shape/composition of objects, properties, and values to correctly processes the payloads deterministically, agnostic of envelope transport.

    I am not clear about your last question/proposal - are you saying that you would want to add a format section to PE Definitions to allow an Issuer to declare what credential formats they accept? If so, that is what the format section in PE Definitions is intended to do. If it’s about the submission side, the format field in PE Submissions is what is used to declare the submitted format of each item to the Verifying party digesting them (to avoid having to sniff/prod them with detection code). Is what you are asking for related to either of these two areas of format declaration, or are you suggesting some additional format information be conveyed for some other purpose?

  12. Anthony Nadalin

    Presentation Exchange is a fully Ratified specification in DIF

    DIF is not a standards body, it’s fine that you have all done some work here but it' nowhere near a standard level.

  13. Kristina Yasuda

    “format“ is optional in DIF PE per

    The Presentation Definition MAY include a format property.

    so looks like putting format in Registration/Discovery metadata in OIDC is technically PE spec compliant.

    People using PE in protocols that do not have metadata exchange mechanisms like in PE should be warned of that difference, and that should probably be brought up in a call on this topic hosted by DIF.

  14. Daniel Buchner reporter

    @Kristina Yasuda the caveat here is that while the format prop is optional in PE, the assumption by conformant PE-centric processors is that if there is no format property present in the PE Definition they don’t need to look elsewhere and code paths that deal with format-based limitations/assessment will not be activated. This may work by happenstance, given they are specified orthogonally, but no PE lib is going to kick out on formatting events/hooks when it doesn’t see them in the intended location.

  15. Kristina Yasuda

    I think this has been solved in a special DIF PE/OIDC call 2 weeks ago, where the group agreed on a “modular” approach, that each protocol can define how to treat optional features of the PE. format is already optional in PE v1, so OIDC4VP passing that information in registration/discovery should not be a problem.

  16. Kristina Yasuda

    We can resolve this in the next SIOP call since the compromise has been reached in PE v2 in the following text, allowing OIDC4VP to keep formats supported by the RP in the registration parameter vp_formats as stated in RP metadata section

    The Presentation Definition MAY include a format property. Some envelope transport protocols may include the value of this property in other locations and use different property names (See the Format Embed Locations section for details), but regardless of whether it resides at the default location (the format property of the presentation_definition object), the value MUST be an object with one or more properties matching the registered Claim Format Designations (e.g., jwtjwt_vcjwt_vp, etc.). The properties inform the Holder of the Claim format configurations the Verifier can process. The value for each claim format property MUST be an object composed as follows:

  17. Kristina Yasuda

    Also worth noting that in DIF-OIDF calls, the agreement has been reached to allow specifying format of each VC being requested, as in the below text of PEv2

    The Input Descriptor Object MAY contain a format property. If present, its value MUST be an object with one or more properties matching the registered Claim Format Designations (e.g., jwtjwt_vcjwt_vp, etc.). This format property is identical in value signature to the top-level format object, but can be used to specifically constrain submission of a single input to a subset of formats or algorithms.

    Probably worth adding a note in the OIDC4VP spec to this regard.

  18. Log in to comment