Added presentationSchema

[David-Chadwick]

Added the presentationSchema property for presentations to complement the credentialSchema property for credentials

---

Preview | Diff

[decentralgabe]

is it worth adding an example similar to the one for credentialSchema?

[David-Chadwick]

@decentralgabe . I also thought about adding an example, but I do not think it adds much to the spec in doing so. Rather a better idea, given your prompting, might be to add more text to section 4.10 Presentations and add the presentationSchema property to this along with the example there. So then we will have an example of using this property

[decentralgabe]

agree with that idea

[awoie]

In general I'm ok with adding this feature. One recommendation is to clarify whether the schema applies to the VP only or whether it includes also the included VCs including their properties.

[iherman]

Note to myself, but others should ping if not done: if this PR is merged, the property has to be added to the official VC Data Model vocabulary (v2) as well.

[msporny]

Overall, I'm a +0.5 to this PR (as I understand it)... but I'm not sure how I understand it is how it's intended to be used... I could get to a +1 with a few answers to the questions below.

What's becoming increasingly clear is that there are multiple use cases for credentialSchema and I'm not convinced the VCWG understands all of them, or the differences between them. I know that I'm now not clear of the differences between @decentralgabe's credential schema proposal and @OR13's credential schema proposal. That is, we have two proposals for the use of credentialSchema that differ in ways that are not clear (which is fine for now, but the VCWG needs to understand the differences between the proposals).

Something similar could be said for presentationSchema. For example, here are my initial questions for this feature:

• A Verifier MUST reject a VC that doesn't match the credentialSchema and presentationSchema? If so, is this a form of DRM (Digital Rights Management) that we're introducing into the specification? There's an argument that the answer to that question is "No" for credentialSchema but "Yes" for presentationSchema. Or, is this information only advisory for a Verifier? The reason I bring this up is that the biggest protest at W3C (yes, protest with people outside W3C TPAC wearing Guy Fawkes masks and chanting and signs, had to do with the Encrypted Media Extensions WG and the inclusion of DRM into a W3C specification).
• Can you place credentialSchema or presentationSchema on a presentation? Or is it only supposed to live in the VC and not the VP?
• If a Holder places a presentationSchema on a presentation, and it conflicts with what an issuer provided, what's expected to occur there?
• What should a Verifier do if it can't fetch a presentationSchema?

All this to say, we need clarity around how people intend to use this feature, ideally with concrete use cases added to the Verifiable Credentials Use Cases document and implementation guide. We don't need all of that done for this PR to go through, but the PR could be a dangerous feature if misused/abused, so the details matter here.

I'm "Requesting Changes" to this PR that clarify the items above, and ideally, suggest we have a WG discussion about this to understand this feature more before adding it into the specification.

[iherman]

The issue was discussed in a meeting on 2022-11-30

• no resolutions were taken

View the transcript

2.2. Added presentationSchema (pr vc-data-model#987)

See github pull request vc-data-model#987.

Manu Sporny: 987 adds presentation schema - has a couple of reviews, oliver& manu have questions. Explore at special topic call? Please take a look and add your questions..

Kristina Yasuda: would be better to have an issue for the discussion.

Manu Sporny: See https://github.com/w3c/vc-data-integrity/.

Manu Sporny: no open PRs on data integrity.

Orie Steele: json web signature 2020 - open PR.

[TallTed]

We don't need all of that done for this PR to go through

I agree that all need not be done, as in complete, but I think all needs to be in motion via Issue and/or PR for each, so there's a relatively clear path to TR that will include "all of that".

[David-Chadwick]

@msporny To answer your questions, the proposal is that credentialSchema only applies to the VC and the presentationSchema only applies to the VP. In the latter case the only interaction of the presentationSchema with the VC will be to say that the verifiableCredential property must be present in the VP. It MUST NOT say anything about the contents of the verifiableCredential(s), otherwise obviously there could be conflicts with the credentialSchema. We can make this part of the presentationSchema definition.

Regarding fetching the presentationSchema definition, I would suggest that the Verifier (or RP), knowing which VCs it requires, and knowing which "holder binding methods" it supports, it will also know the presentationSchemas that it supports. So it should not have to fetch them dynamically at run time. Obviously its a local decision what the RP actually does, but we can recommend non-dynamic loading (as we should do for credentialSchema as well)

[OR13]

I'd prefer to see an example for "presentationSchema" included.

[iherman]

The issue was discussed in a meeting on 2022-12-07

• no resolutions were taken

View the transcript

1.2. Added presentationSchema (pr vc-data-model#987)

See github pull request vc-data-model#987.

Manu Sporny: next item: 987; adds presentationSchema, by David Chadwick. good discussion. still some things being asked for. 3 people continuing to request changes. expect David to keep engaging to move it forward. Other than that, no new PRs..

[msporny]

@David-Chadwick is going to generate an example for this in the next week or so.

[iherman]

The issue was discussed in a meeting on 2022-12-14

• no resolutions were taken

View the transcript

3.2. Added presentationSchema (pr vc-data-model#987)

See github pull request vc-data-model#987.

Manu Sporny: PR 987 - request for an example from Orie - re Added PresentationSchema. David to provide an example two shortly.

Ivan Herman: this is a new property to go into the data model?.

David Chadwick: Yes that's correct, only applied to Presentations.

Ivan Herman: has to add this to the vocabulary.

David Chadwick: Property name is fixed, it will be an object with defs, and have a type and ID.

Manu Sporny: One thing everyone doing PR should be aware of there are three places - spec, the vocab, and JSON schema file and JSON-LD schema file.
… four (4) things not 3..

Ivan Herman: for the vocab part would be nicer if the automatic publishing procedure was running. A bit complicated - but should be done in Jan..

Manu Sporny: Yes, it's on the 'todo' list.

Mike: is JSON schema in scope?.

Manu Sporny: Yes, JSON schema added for the specification was added a few weeks ago and needs to be added.

Orie Steele: I agree with selfissued, seems like this is going to be difficult to maintain... might have been nicer to do at the end..

Dave Longley: +1 to freeze until the end.

Michael Prorock: https://github.com/w3c-ccg/traceability-vocab.

Orie Steele: Spruce also has tooling for that purpose..

Dmitri Zagidulin: one way to reduce the complexity adding to 4 places is if we added a toolset to automate this. Orie has more tooling or others may have something..

Michael Prorock: +1.

Dmitri Zagidulin: +1 to freezing, too.

Ted Thibodeau Jr.: if it's frozen, it will need inline notation saying so, else our early adopters will be raising lots of issues (and may do so even with such notice).

Michael Prorock: big fan of doing this once and highly in favor that approach but maintaining both things at once will get things out of sync.

Kristina Yasuda: WG agreed to work on the schemas. Can we document the issues re: generating once and integrate the updates.

Manu Sporny: will create an issue to automate the files we have to maintain so we only one to maintain..

Michael Prorock: +1 mike.

Mike: can someone put a note in the header for the schema that it is out of date and we're not going to maintain it until we do the one point of change to update all..

Michael Prorock: otherwise someone will think it is gospel and create a lot of work to undo.

[David-Chadwick]

Here is a real life example of a VP containing the presentationSchema property.
Note. this example cannot be used in the spec without changing the URLs to example ones.

{
    "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.ngiatlantic.info/w3c-vc/context"
    ],
    "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
    "holder": "did:jwk:123456789",
    "type": [
        "VerifiablePresentation", "OpenID4VP"
    ],
    "nonce": "123456789",
    "audience": "http://rp.example.com",
    "presentationSchema": {
        "id": "https://ngiatlantic.info/schema/V-2022-1/VerifiablePresentation.json",
        "type": "https://json-schema.org/draft/2019-09/schema"
    },
    "verifiableCredential": [{}]
}

The schema itself is live at the id URL above, and dereferencing it you should obtain the following

{
  "$schema" : "https://json-schema.org/draft/2019-09/schema#",
  "$id" : "https://ngiatlantic.info/schema/V-2022-1/VerifiablePresentation.json",
  "title" : "JSON Schema for the VerifiablePresentation class.",
  "description" : "Verifiable Presentations are defined on the W3C Verifiable Credential standard.",
  "type" : "object",
  "properties" : {
    "@context" : {
      "type" : "array",
      "minItems" : 1,
      "items" : {
        "description" : "The value of the `@context` property MUST be an ordered set where the first item is a URI with the value 'https://www.w3.org/2018/credentials/v1', and the second item is a URI with the value 'https://www.ngiatlantic.info/w3c-vc/context'.",
        "$comment" : "Origin: URI (DerivedType); A `NormalizedString` that respresents a Uniform Resource Identifier (URI).",
        "type" : "string",
        "format": "uri"
      }
    },
    "id" : {
      "description" : "Unambiguous reference to the credential.",
      "$comment" : "Origin: URI (DerivedType); A `NormalizedString` that respresents a Uniform Resource Identifier (URI).",
      "type" : "string",
      "format": "uri"
    },
    "type" : {
      "description" : "The value of the type property MUST be an unordered set. One of the items MUST be the URI 'VerifiablePresentation'.",
      "oneOf" : [ {
        "$comment" : "Origin: IRI (DerivedType); A `NormalizedString` that represents an Internationalized Resource Identifier (IRI), which extends the ASCII characters subset of the Uniform Resource Identifier (URI).",
        "type" : "string"
      }, {
        "type" : "array",
        "minItems" : 1,
        "items" : {
          "$comment" : "Origin: IRI (DerivedType); A `NormalizedString` that represents an Internationalized Resource Identifier (IRI), which extends the ASCII characters subset of the Uniform Resource Identifier (URI).",
          "type" : "string"
        }
      } ]
    },
    "holder" : {
      "description" : "The value of the holder property MUST be a URI representing the Holder of the credentials.",
      "$comment" : "Origin: URI (DerivedType); A `NormalizedString` that respresents a Uniform Resource Identifier (URI).",
      "type" : "string",
      "format": "uri"
    },
    "nonce" : {
      "description" : "The purpose of the nonce is to avoid replay attacks on the verification of the VP. It can also be used as a challenge for the Relying Party to recognize the VP matches with its request.",
      "$comment" : "Origin: String (PrimitiveType); Character strings.",
      "type" : "string"
    },
    "audience" : {
      "description" : "The value of the audience property MUST be a URI representing the Audience of the credentials.",
      "$comment" : "Origin: URI (DerivedType); A `NormalizedString` that respresents a Uniform Resource Identifier (URI).",
      "type" : "string",
      "format": "uri"
    },
    "presentationSchema" : {
      "description" : "Identify the type and location of a data schema.",
      "type" : "object",
      "properties" : {
        "id" : {
          "description" : "The value MUST be a URI identifying the schema file. One instance of `PresentationSchema` MUST have an `id` that is the URL of the JSON Schema for this credential defined by this specification.",
          "$comment" : "Origin: URI (DerivedType); A `NormalizedString` that respresents a Uniform Resource Identifier (URI).",
          "type" : "string",
          "format" : "uri"
        },
        "type" : {
          "description" : "The value MUST identify the type of data schema validation. One instance of `PresentationSchema` MUST have a `type` of 'https://json-schema.org/draft/2019-09/schema'.",
          "$comment" : "Origin: IRI (DerivedType); A `NormalizedString` that represents an Internationalized Resource Identifier (IRI), which extends the ASCII characters subset of the Uniform Resource Identifier (URI).",
          "type" : "string",
          "format" : "uri"
        }
      },
      "required" : [ "id", "type" ],
      "additionalProperties" : false
    },
    "verifiableCredential" : {
      "type" : "array"
    },
    "proof": {
      "type": "object"
    }
  },
  "required" : [ "@context", "id", "type", "holder", "nonce", "audience", "verifiableCredential" ],
  "additionalProperties" : false
}

[iherman]

The issue was discussed in a meeting on 2023-01-11

• no resolutions were taken

View the transcript

2.1. Added presentationSchema (pr vc-data-model#987)

See github pull request vc-data-model#987.

Manu Sporny: A lot of topics for today. Asking David Chadwick for PR 987..

David Chadwick: Don't believe anyhting outstanding..

Manu Sporny: Confirmed. Orie to confirm..

[iherman]

The issue was discussed in a meeting on 2023-01-18

• no resolutions were taken

View the transcript

2.1. Added presentationSchema (pr vc-data-model#987)

See github pull request vc-data-model#987.

Manu Sporny: action was to write an example, but there has yet to be responses to what david has provided..
… if you requested changes, please re-review.

[msporny]

Here is a real life example of a VP containing the presentationSchema property.

Ok, got it. Thank you for the example... now for the clarification of the use case.

I don't understand the value of the feature. To be clear, the entity that's creating the presentation is also setting the schema under which that presentation is valid. IOW, why would they create a presentation that's not valid based on their own criteria for creating a presentation? One could argue "well, software can have bugs, and so a presentationSchema is there to detect and prevent bugs... but then, the entity verifying that is the Verifier, not the creator of the presentation.

Please help me understand the use case -- I get that it is technically possible to do this, but why would one do this?

[David-Chadwick]

The use case is a generic one.
Currently the contents of a VP are not fully defined. Furthermore, the type of the VP is not. It may be VerifiablePresentation plus something else. A Verifier which receives a VP could behave in one of two ways:
i) allow "anything goes", so parse the VP, see what it contains and then what ?? process properties it understands and reject ones it does not understand? or reject the whole VP? or something else? OR,
ii) only accept VPs that it already knows and understands. So it looks at the type, to see if understands the additional value(s), and then looks at the presentationSchema to check that all the properties that it expects to be there in the VP are there, and ones that it does not understand/expect are not there. If the VP passes these tests then the verifier knows how to handle the VP and every property that it contains. This is why we need presentationSchema.

[OR13]

The example helps.

This seems like it could create a lot of work for holder's and verifiers...

This pattern has been seen in the while, for example:

• https://docs.snowplow.io/docs/pipeline-components-and-applications/iglu/common-architecture/self-describing-jsons/

[David-Chadwick]

Isn't that refusing to use a feature that's there,

I don't think so. It is only RECOMMENDED that the type URI should be machine processable. It is not a requirement, in the same way the JSON-LD processing is not a requirement. Note, it also is not a requirement to have a credentialSchema property, so in this way the two features have been treated equally.

[OR13]

Clearly a higher bandwidth sync is needed on this. : )

[David-Chadwick]

A verifier could just associated a JSON Schema with objects of type OpenID4VP

You cannot have different verifiers associating different schemas to the same VP type. Some trusted entity has to do this. In the case of issuing and credentialSchema it can be the issuer or an external entity like JFF. In the case of verification it should always be some external trusted entity (and not the holder). But nevertheless both the holder and verifier need to know what this is. Passing it in the VP is an explicit way of confirming this joint knowledge. The amount of schema checking done by the verifier is the same in both cases (whether presentationSchema is passed or not). If we do not define the presentationSchema property it is not clear to me how it is specified and how a common standardised understanding can be reached by the specifier, the holder and the verifier.

[msporny]

@David-Chadwick wrote:

A verifier could just associated a JSON Schema with objects of type OpenID4VP

You cannot have different verifiers associating different schemas to the same VP type. Some trusted entity has to do this.

The Verifier is ultimately responsible for what they allow, they are the first line of "trusted entity". We can't tell them that they cannot associate their own JSON Schemas w/ incoming data of any type or form.

Now, they may defer their authority to some other entity in the space, like an SDO, to express what a valid presentation looks like, but the decision is ultimately theirs to make (not the issuers, not the holders, etc.).

In the case of issuing and credentialSchema it can be the issuer or an external entity like JFF. In the case of verification it should always be some external trusted entity (and not the holder). But nevertheless both the holder and verifier need to know what this is. Passing it in the VP is an explicit way of confirming this joint knowledge.

Ah, good, this was the missing piece. We are much more aligned now than I had previously thought. To reflect back what I think you're saying: "Ultimately, credentialSchema and presentationSchema are signalling mechanisms to say that the issuer or the holder are conforming to some ecosystem standard. For credentialSchema the issuer is saying "I conform to this standard that you, the holder/verifier, should probably know about". For presentationSchema the holder is saying "I conform to this standard that you, the verifier, should probably know about".

We don't say any of the above in the spec today, and I think that we should.

The amount of schema checking done by the verifier is the same in both cases (whether presentationSchema is passed or not).

Hmm, the open question is whether or not checking is mandatory. I expect that it's not, correct? If the holder/verifier chooses to ignore credentialSchema, or if the verifier chooses to ignore presentationSchema, that is a risk that they can choose to take, correct?

I'll also note that linking to this sort of external resource has the same implications a linking to an external @context -- we'll need a good story wrt. content identification such as digestMultibase.

[OR13]

Hmm, the open question is whether or not checking is mandatory. I expect that it's not, correct? If the holder/verifier chooses to ignore credentialSchema, or if the verifier chooses to ignore presentationSchema, that is a risk that they can choose to take, correct?

^ yes, this is the problem with both credentialSchema and presentationSchema... we need to be clear on if they can be ignored when not understood, or if they MUST be understood when present.

[David-Chadwick]

Of course both schemas can be ignored by the recipient. The recipient is the ultimate arbiter of what they will accept. The schema are there to help the recipient should they choose to accept it.

[OR13]

@David-Chadwick let me try to refine what you have said.

Both properties are option and can be ignored by a verifier, regardless of if the verifier understands them or not... is that correct?

[David-Chadwick]

@OR13 What you are saying applies to all the credential metadata properties: ToU, Evidence, validity period, Status etc. So in this respect the schema properties are no different

[OR13]

@David-Chadwick agreed, I filed #1027 to keep your PR clear of debate on this topic.

[iherman]

The issue was discussed in a meeting on 2023-02-01

• no resolutions were taken

View the transcript

3.1. Added presentationSchema (pr vc-data-model#987)

See github pull request vc-data-model#987.

Manu Sporny: Add presentationSchema. Good discussion going in this PR, it would be good for other people to weigh in. David and I have some level of agreement on what's meant by this PR..
… I think Orie is right that we need to have a working group discussion so everybody understands what we are doing here..
… Wanted to make sure WG is aware..
… Request to the chairs to schedule some discussion time for this..

[OR13]

Conflicts exists, we have not made progress on this item, it seems to be stalling out.

[David-Chadwick]

In general I'm ok with adding this feature. One recommendation is to clarify whether the schema applies to the VP only or whether it includes also the included VCs including their properties.

Yes I will add this to the next revision.

[David-Chadwick]

I'd prefer to see an example for "presentationSchema" included.

This has already been done

[brentzundel]

I believe the best course of action is to merge #1108 (which includes presentationSchema) and close this PR.

[David-Chadwick]

@brentzundel If you do as you suggest then you lose all the work that has already been done on the definition of presentationSchema. So we need somewhere to capture this, so that, if 2 independent implementations arise before the VCDM is complete then the text of this PR can be copied into the VCDM. In other words, all the reserved terms that are currently not in the VCDM need to have agreed definitions of them somewhere, so that when 2 implementations of them exist the text is already available to be copied into the VCDMv2

[OR13]

So we need somewhere to capture this,

Why not define presentationSchema in the W3C CCG and register in the vc specs directory?

so that, if 2 independent implementations arise before the VCDM is complete then the text of this PR can be copied into the VCDM.

There needs to be working group consensus to update the document, not just 2 implementations.

In other words, all the reserved terms that are currently not in the VCDM need to have agreed definitions of them somewhere,

I agree with this, but the current PR is making things worse, not better in this regard, better to define things in a place where you are not blocked by the working group, show interop and adoption, then ask the working group to document it, (and they can still say no, if they don't like the idea, or are not convinced it will make things, safer / easier to use / better).

The VCDM is filled with "things people thought would be useful", and we are all paying to maintain them, while acknowledging that nobody is using them currently... this needs to stop for the spec to improve.

I suggest this PR be closed.

[David-Chadwick]

@OR13 Why not define presentationSchema in the W3C CCG and register in the vc specs directory?
good idea, since we already implemented this at Crossword
things people thought would be useful", and we are all paying to maintain them,
which is precisely why I suggested there should be just one extension point, not many extensions of different flavours as now, and then its type will tell you exactly what sort of extension it is. It simplifies the VCDM enormously whilst not impacting on the semantics or implementation of the extension itself.

[iherman]

The issue was discussed in a meeting on 2023-05-17

• no resolutions were taken

View the transcript

3.1. Added presentationSchema (pr vc-data-model#987)

See github pull request vc-data-model#987.

Brent Zundel: open for a while. Three people requesting changes and no one who has approved it.
… The question for this PR is what do we do to move this forward?
… just a brief conversation.

Manu Sporny: There are a couple things we can try, but I'm doubtful we're going to come to consensus.

Michael Prorock: +1 manu.

Manu Sporny: I tried puting this in a PR in the reserved tables and that was objected to.

Orie Steele: +1 Manu.

Manu Sporny: So if we couldn't get consensus there, we probably won't here.
… proposal is to just mark pending close.
… we could try a reserve property thing and CCG spec, but someone would have to lead that work.
… something like what has been done with renderMethod.

Brent Zundel: anyone opposed to pending close.

David Chadwick: I thought we didn't want to lose the conversation to date.

Manu Sporny: to be clear, I suggested moving to CCG as an option.

Brent Zundel: I'll market this as pending close. Which will retain the conversation. Next step would be to transfer to CCG and continue incubating there.
… any opposition to that course?
… great. Marking it pending close.
… Another one to look at 1035.
… Add rendering property to VCDM.

[brentzundel]

No objections raised to closing since being marked pending close, closing.