w3c-ccg / vp-request-spec

Specification for a query language to request Verifiable Presentations from wallets etc.

Verifiable Presentation Request Specification

Specification for a query language to request Verifiable Presentations from wallets etc.

We encourage contributions meeting the Contribution Guidelines. While we prefer the creation of issues and Pull Requests in the GitHub repository, discussions often occur on the public-credentials mailing list as well.

vp-request-spec's Issues

Specify how "and" and "or" work with VPR

Top-level queries are "and", so e.g.:

{
  query: [
    // "and"
    {
      type: 'APopularQueryType',
      // query details ...
    },
    // "and"
    {
      type: 'AnotherQueryType',
      // query details ...
    }
  ]
}

And "or" queries are possible within particular query types like this:

{
  "query": [
    // "and"
    {
      "type": "QueryByExample",
      "credentialQuery": [
        // "or"
        { ... },
        // "or"
        { ... }
      ]
    },
    // "and"
    { ... }
  ]
}

Status of the spec

Latest published version:
https://www.w3.org/vp-request-spec/

At the top of the spec it links to the lasted version on w3.org however I can not find Verifiable Presentation Request. What is the status of this spec?

Mediated Presentation clarification

Would it be possible to clarify the meaning of the Mediated Presentation interaction type and how a holder should react to this interaction type?

My understanding is that this interaction type is intended to signal that review of the submitted VP will require mediation, which means that the result of the processing of the submitted VP will may not be available for the HTTP response to the client. My assumption that use of this interaction type could result in a flow like this one:

sequenceDiagram

participant H1 as Holder-1 Client
participant H2 as Holder-2 Service

H1->>H2: submit presentation 
activate H2
  H2-->>H1: reply with "mediation in progress" VP Request
deactivate H2

par review presentation
  H2->>H2: process presentation and store result
and query presentation status
  loop At some polling interval...
    H1->>H2: query presentation review status
    activate H2
    alt presentation is processed
      H2-->>H1: return review result (possibly including VP with VCs)
    else presentation not yet processed
      H2-->>H1: return "mediation in progress" VP Request
    end
    deactivate H2
  end
end

Loading

Is this how others see "Mediated Presentation" as well? If not, is it envisioned that VP Request (and VC API) would support asynchronous presentation review flows (via duplex client-server HTTP) through some other means?

Regarding the flow above,

• What could a "Mediation in progress" VP Request look like? My idea is that it could be a VP Request with an empty credential query and an interact service where the client can query the status of the presentation review
• Could there be some way of signalling to the client what an appropriate polling interval could be?

If I've misunderstood Mediated Presentation, my apologies!

DID Authentication vs. VC Test Suite

The example DID Authentication response is currently invalid according to vc-test-suite, because of not containing a verifiable credential, although this is valid in vc-data-model. Issue on vc-test-suite about this: w3c/vc-test-suite#112; proposed fix: w3c/vc-test-suite#113

Add `acceptedEnvelopes` and `acceptedCryptosuites` examples for `QueryByExample`

For example, these two examples show that the sender will accept a number of cryptosuites or at least one envelope. The second example also highlights that only a limited subset of the VC is requested, so if a selective disclosure mechanism is available and chosen, just that field can be revealed.

{
  "type": "QueryByExample",
  "credentialQuery": {
    "reason": "Please present your PermanentResidentCard or Verifiable Credential(s) to complete the verification process.",
    "example": {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://w3id.org/citizenship/v1"
      ],
      "type": ["PermanentResidentCard"]
    },
    "acceptedCryptosuites": [
      "Ed25519Signature2020",
      "eddsa-rdfc-2022",
      "ecdsa-rdfc-2019",
      "bbs-2023",
      "ecdsa-sd-2023"
    ],
    "acceptedEnvelopes": [
      "application/jwt"
    ]
  }
}

{
  "type": "QueryByExample",
  "credentialQuery": {
    "reason": "Please present your PermanentResidentCard or Verifiable Credential(s) to complete the verification process.",
    "example": {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://w3id.org/citizenship/v1"
      ],
      "type": ["PermanentResidentCard"],
      "credentialSubject": {
        "birthCountry": ""
      }
    },
    "acceptedCryptosuites": [
      "Ed25519Signature2020",
      "eddsa-rdfc-2022",
      "ecdsa-rdfc-2019",
      "bbs-2023",
      "ecdsa-sd-2023"
    ],
    "acceptedEnvelopes": [
      "application/jwt"
    ]
  }
}

Add support for QueryByFrame to allow support of requests with JSON-LD Frames

This query type is being designed with JSON-LD BBS+ Signatures in mind where we want to be able to use a JSON-LD frame to request specific attributes in a query which is provided in the form of a JSON-LD frame.

An example of this query type would look like the following:

{
   "query":[
      {
         "type":"QueryByFrame",
         "credentialQuery":[
            {
               "reason":"Please provide your Passport details.",
               "frame":{
                  "@context":[
                     "https://www.w3.org/2018/credentials/v1",
                     "https://schema.org",
                     "https://w3c-ccg.github.io/ldp-bbs2020/context/v1"
                  ],
                  "type":[
                     "VerifiableCredential",
                     "PassportCredential"
                  ],
                  "credentialSubject":{
                     "@explicit":true,
                     "givenName":{ },
                     "birthDate":{ }
                  }
               },
               "trustedIssuer":[
                  {
                     "issuer":"did:key:zUC7FLNC876WXsNTYP5FaWssvNWpiB5unYwVEXuZgcWCWzUHUCamoVwD7q3MSM84JqEANV5RnjzXsfLx77b4vCV3uEBQbaob1dYk2NtUGhguY7JP64BmvWCfNJ1h9wUgaZtLMNN",
                     "required":true
                  }
               ],
               "required":true
            }
         ]
      }
   ]
}

Are there any sorts of other considerations that we should take into account when adding this query type @dlongley @msporny @dmitrizagidulin ?

What fields should be mandatory in a VPR?

@OR13 wondered what fields should be mandatory in a VPR here: https://github.com/w3c-ccg/vc-api/pull/255/files#r791112933.

Example 2 provides invalid JSON object

In example 2 the addition of the "AnotherQueryType" object falls within the "example" property value. Should this be another example query and should be the second index of the credentialQuery Array property value?

@Liam-Tait

Add a note about protocol limitations being driven by primitives such as URLs

See conversation here: #26 (comment)

Fix indentation on example 2 such that "AnotherQueryType" is under "query"

How to do request queries by reference?

Placeholder for the discussion -
When doing a QueryByExample request, how would you pass in the example by reference? (As opposed to by value, as is currently in the spec.)

Indentation is still off on example 2

https://w3c-ccg.github.io/vp-request-spec/#example-a-query-by-example-query

The trustedIssuer and issuerQuery should be moved one indentation layer back so they aren't in the example section.

Questions regarding `QueryByExample` structure and handling

Hello,

I have some questions regarding the proper handling of QueryByExample objects.

I understand that many of these questions may not yet have answers, but I'd appreciate any insight that can be provided.

1. Are the @context and type fields required or optional?
2. What is the datatype of these fields?
   • I am operating under the assumption that they are both string | string[] -- is this fair?
3. How are the @context and type fields to be handled?
   • I am operating under the assumption that every value in the example @context array (whether it be expressed as an array of strings or a string itself) must be present in the credential's @context array, but additional values may be present in the credential's @context array. Is this fair?
   • I am operating under an equal assumption for the type field.
4. Is credentialSubject limited to only id and name fields, or is it intended for arbitrary key/values to query against the credential's credentialSubject?
   • My intuition tells me that any key/value pairs are valid, but the comment above it in Example 2 states You can request a specific subject id, which implies that that is the only intended usage.
5. Assuming credentialSubject is not limited to id and name, how is comparison meant to be handled?
   • Comparisons of primitives is intuitive, but stringy equality (does 5 match "5"?) should be clarified.
   • Comparisons of objects is also intuitive -- just recurse.
     • I am assuming, however, that all object comparisons (including the top-level example.credentialSubject to credential.credentialSubject comparison itself) are loose in the sense that the object on the credential may have additional fields not specified by the example object.
   • How should one perform a comparison of arrays?
     • See below

Array Comparison in credentialSubject

(This is all assuming that the credentialSubject field in the example query is not restricted to id and name fields)

Given the following query:

{
  "type": "QueryByExample",
  "credentialQuery": {
    "example": {
      "credentialSubject": {
        "primitive_array_one": [0, 1, 2],
        "primitive_array_two": [10, 11, 12],
        "complex_array": [
          {
            "a": 1
          },
          {
            "b": 2
          }
        ]
      }
    }
  }
}

And the following credentialSubject from a VerifiableCredential:

{
  "credentialSubject": {
    "id": "whatever",
    "primitive_array_one": [0, 1, 2, 3],
    "primitive_array_two": [12, 11, 10],
    "complex_array": [
      {
        "a": 1,
        "b": 2,
      },
      {
        "b": 3
      }
    ]
  }
}

It's not entirely clear how to handle this query by example.

• primitive_array_one
  • The credential's primitive_array_one contains all values of the example's primitive_array_one, in the same order and position, but it has additional entries.
• primitive_array_two
  • The credential's primitive_array_two contains all values of the example's primitive_array_two, and has no additional values, but they are not in the same order.
• complex_array
  • The example is looking for an object with an a value equal to 1, and an object with a b value equal to 2.
    • The credential does, in fact, have an object with an a value equal to 1, and an object with a b value equal to 2.
    • However, they're the same object, which likely isn't what the person who wrote the query was intending.

Query By Example vs. VC Data Model

The Query By Example query example contains two properties in the example credential that are not in the VC Data Model or in the JSON-LD contexts of the credential:

• trustedIssuer
• issuerQuery

Should these two properties be moved up a level or two so to be out of the example credential object?

In general, should the credential in the QueryByExample credentialQuery example object be valid according to vc-data-model and/or vc-test-suite? (e.g. must have a issuer URI, issuanceDate, and credentialSubject.) Or is it its own thing that looks like a credential but has these additional properties that we could define? If it is strictly according to vc-data-model, how can it represent allowing one of multiple issuers?

Could an existing standard be used here instead? e.g. JSON Schema. There is also JSON Predicates but that is expired. Or is better to have a custom predicate format for credentials?

Add Presentation Exchange Example

https://github.com/decentralized-identity/presentation-exchange

https://identity.foundation/presentation-exchange/#chapi

essentially, the request query is a special type, and the response is an extended VP...

Examples and cross linking would be helpful.

Example 2 is incorrect

https://w3c-ccg.github.io/vp-request-spec/#example-a-query-by-example-query

The example is meant to show two different queries, one of type QueryByExample and one of type AnotherQueryType, but the nesting is off. It also erroneously shows credentialQuery in QueryByExample using an array value because of this instead of properly using an object.

Add EDU "use case" examples for presentation exchange data model

As requested here: #12 (comment)

"traceability examples are too complicated"...

I don't agree with this comment, but I think they might not be the "best example" to lead with.

This issue is to request a simpler use case to start with.

Mediated Presentation definition

3. Interaction Types it mentions different interactions, in particular:

• MediatedBrowserPresentationService2021
• OpenIdConnectCredentialProviderService2021

However I can not see any definition of these, a further internet search doesn't give anything additional. It appears these types are create in this document but not defined here or anywhere else.

What should the definition be?

Section 3.2

Section 3.2 should probably be updated to OpenID for Verifiable Credentials Issuance Draft