Questions regarding `QueryByExample` structure and handling

[geel9]

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.

[msporny]

The group discussed this issue in the 2024-07-30 telecon:

The group agreed that QueryByExample is under-specified today and the only way to answer the questions asked in this issue is to write one or more PRs that clearly answers each question.

[msporny]

@geel9 wrote:

Are the @context and type fields required or optional?

The @context entry is required. type is optional, but is expected to be heavily used in queries.

What is the datatype of these fields? I am operating under the assumption that they are both string | string[] -- is this fair?

For @context, what is allowed is specified here: https://www.w3.org/TR/vc-data-model-2.0/#contexts

For type, it can either be a string or an array of strings.

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.

Yes, those are safe assumptions to make.

Is credentialSubject limited to only id and name fields, or is it intended for arbitrary key/values to query against the credential's credentialSubject?

It's intended for arbitrary key/values to query against the verifiable credential.

Assuming credentialSubject is not limited to id and name, how is comparison meant to be handled?

Comparison is only to be performed based on the primitive types. Matching string "5" vs. integer 5 is not expected to be performed.

Comparisons of objects is also intuitive -- just recurse.

Yes, correct.

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.

Yes, that is correct.

How should one perform a comparison of arrays?

In general, we've tried to stay away from complex queries such as the ones you suggest because the use cases that most of the community is tackling doesn't require that sort of fine-grained querying. That said, arrays are presumed to be "unordered" so if there is a match, you return the credential (even if items are out of order). IOW, the query you provided would match and the credential should be returned.

The group will try to clarify these items in a future PR.

[TallTed]

@msporny — Please code fence the @context occurrences in the (first and third) quote blocks above. I'm sorry GitHub still hasn't figured out how to preserve codefences when automatically quoting!