Editorial and non editorial changes

[OR13]

Lots of changes in this PR, since the document is in pretty rough shape.

I moved sections around, updated examples, adjusted old text copied from version 1.1, clarified how examples map to resolutions made regarding the core data model, and removed a should requirement for an unregistered and extraneous media type.

---

Preview | Diff

[iherman]

"preview" does not handle respec's includes properly, so it is pretty much useless here. This seems to work:

https://raw.githack.com/w3c/vc-jwt/fixes-and-examples/index.html

[andresuribe87]

I think I understand the intention of this note. But it took me a bit of reading to follow along. Perhaps readers would be better served if we add a more explicit explanation of the directions a developer may want to go. I would recommend to separate in the following fashion:

• From vc+ld+json to vc+jwt. Explicitly say that this is not recommended (I think it isn't, but correct me here if I'm wrong).
• From vc+jwt to vc+ld+json. This is what you added in the appendix.
• From vc+ld+json to vc+ld+jwt. I would add recommendations of when to do this. I think it's important to explicitly describe the relationship between an embedded proof, and the external proof mechanism of jwt.
• From vc+ld+jwt to vc+jwt. Although this is obvious, I think it doesn't hurt to call it out. For this mapping, I also believe it's important to talk any relationship between the proof mechanism.

[OR13]

I agree, we should provide more guidance than saying "it is possible / required by the resolutions of the wg"... however, that guidance is going to be hard to get consensus on.

I will file an issue to discuss first:

#69

[OR13]

@TallTed @andresuribe87 Thank you for your reviews!

[mprorock]

lgtm

[selfissued]

I believe this PR improves the specification.

[iherman]

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

• no resolutions were taken

View the transcript

2. Work Item status updates/PRs.

Brent Zundel: Moving on to work item status updates and PRs.

Manu Sporny: On VC Data Model, there are six PRs that are effectively stuck, that we need to discuss how we get them unstuck.
… Other PRs look fairly straightforward and simple.
… Data integrity spec is fine, nothing stuck there, same for EdDSA and ECDSA.
… Need to do first public working drafts for EdDSA and ECDSA.
… StatusList2021, not a whole not of progress. If folks are looking for work, that would be a good place to start.

Brent Zundel: FPWD is important so that other W3C groups can review and so that patent declaration has time.
… Want to enter FPWD as soon as possible.

See github pull request vc-jwt#68.

Orie Steele: #68 is an open pull request on VC-JWT what we want to merge.
… Document is still close to the format it was in when it was copied out of the core spec.
… Talked to Tobias at IETF about BBS, still in the process of adopting it.
… Happy to do that work.

Manu Sporny: Just a note that I have sent a list of steps to Gabe, who is raising PR on transitioning from CCG to VC-JWT.

Michael Prorock: yep - on the lookout.

[awoie]

Definitely a major improvement to the previous version and supportive of merging this. I suggest merging this PR and creating tickets for upcoming PRs.

[brentzundel]

I'm not challenging the move, but am curious about the reasoning behind moving the transformation to an appendix.

[Sakurann]

I personally think because it is a way to transform (not THE way), it should be in the appendix?

[OR13]

@brentzundel What @Sakurann said, it was also a change request on your original PR.

We feel it is important to be clear that different organizations might want to produce different JSON-LD based on their business use cases, at the face to face, we discussed this in depth, we don't want readers concluding there is "only one way" to map a JWT to a JSON-LD object.

[msporny]

vc+jwt isn't a media type. I don't know what the JWT spec calls this thing, but we can't call it a media type.

[OR13]

vc+jwt is as much a media type as other requested media types... see also:

We are requesting this registration in the spirit of previous registrations:

• https://www.iana.org/assignments/media-types/application/secevent+jwt
• https://www.iana.org/assignments/media-types/application/at+jwt
• https://www.iana.org/assignments/media-types/application/logout+jwt
• https://www.iana.org/assignments/media-types/application/oauth-authz-req+jwt

https://www.rfc-editor.org/rfc/rfc7519#section-5.1

[msporny]

credential-claims-set+json isn't a registered IANA type... where is this value coming from?

[OR13]

its a requested registration, that was merged by here:

• Request media type for 1.1 vc-jwt claim set #40

[msporny]

We clearly need a PR in the main spec to register this media type.

[OR13]

I am happy to do one.

[msporny]

Same question here, is +ld+jwt going to be a registered structured syntax suffix?

[OR13]

same answer as before, we are unsure based on the latest suffixes draft debate.

seeing as the suffixes registrations only require expert review, we are assuming the draft will go to WGLC soon, and then we can ask for the experts to review a family of "multiple suffixes" together including +ld+json

[msporny]

This is the VC-JWT specification, not the VC-CWT specification. This seems to be a change in scope for this specification, with technologies that are not listed in our charter.

How are we going to defend these additions, of COSE and CWT, to the Director and the W3C Membership when our charter doesn't mention these technologies at all?

[OR13]

In practice, once vc+ld+json is registered we should expect it to start showing up in all the places where cty is allowed.

I think it is better to address the alignment between jwt and cwt secured vc+ld+json up front, to avoid the problems we saw in the previous work, where the vc-jwt format was designed without a broader context.

The same "key resolution" problems will occur for COSE and JOSE, and they can both be used to secure application/vc+ld+json, if we don't comment on it, people will just do it... many different ways.

The day 3 resolution also allows for this to be addressed outside the working group with a mapping from vanilla CWT to JSON-LD.

I have not attempted to define that mapping, but perhaps we should for consistency?

[msporny]

This media type feels wrong... I don't understand why it's not application/vc+jwt -- is the reason because "It's JSON-LD"?

[OR13]

Yes, the payload (claimset) is known to be JSON-LD, instead of "just normal JSON, with registered / private claim names".

[msporny]

This needs to refer to the JWT spec for normative guidance on what an encoding should look like.

[OR13]

https://www.iana.org/assignments/media-types/application/at+jwt

^ for example, I think this language should stay but perhaps extra citation should be added.

[msporny]

This should refer to the JWT spec's security considerations.

[OR13]

yes!

[OR13]

added in 76b5c6c

[msporny]

I expect that section runs afoul of a presumption in a resolution made at the most recent VCWG F2F Meeting, namely that "Transformation rules MUST be defined", specifically, I expect that a number of the individuals in the WG presumed that the intent here was to have normative language defined somewhere that was testable. The normative language doesn't have to be the only way "other transformation mechanism MAY be used to translate to the core data model" (understanding that language like that introduces interoperability challenges). Fundamentally, the language in this section isn't normative and therefore won't be tested by the WG.

It is imperative that if the WG is defining transformation rules, that those rules be testable and demonstrated to provide interoperability at some layer. Not providing that assurance (demonstrable interoperability) with a specification being produce by the WG would be a failure of our remit.

https://www.w3.org/2017/vc/WG/Meetings/Minutes/2023-02-16-vcwg#resolution1

This section needs to be something that has normative language, is tested during CR, and results in measurable demonstrations of multi-vendor interoperability.

[OR13]

I am opened this issue to continue this discussion:

#73

[msporny]

Is urn:vc: going to be registered and the syntax for it explained somewhere? For example, defined in this specification and registered here? https://www.iana.org/assignments/urn-namespaces/urn-namespaces.xml

[OR13]

Possibly, I believe it is a requirement that @id / id be valid IRIs, so in the case that you need to map from a "non" IRI to a URN, it seemed necessary to invent... is there a better solution you can think of?

[msporny]

Same refs issue as above.

[OR13]

Thanks, this is copied from the version 1 section, and needs to be cleaned up. I will address in this PR.

[msporny]

There are claims in the IANA registry that don't map well to the concept of a "credential subject"... for example: acr, azp, locale, zoneinfo, auth_time, amr, sip_*, sid, act, scope, sph, and token_introspection.

What is the guidance in those scenarios?

[OR13]

They are automatically mapped by the current transformation rules, see #60

[msporny]

High level comments on this PR:

• It's huge and changes many normative statements simultaneously, please avoid massive PRs like this, it makes it very easy to miss important changes.
• The use of data-include has broken the PR Preview, which means that all examples are not viewable inline and the spec now requires you to download and run it locally to see the updates/changes. I doubt that most of the reviewers are doing this.
• It adds CWT and COSE to the scope of VC-JWT, after feature freeze, which seems to be difficult to reconcile with scope of the VCWG Charter (and could lead to formal objections).
• It defines the 'transformation' algorithm in a way that won't be tested by this WG and thus we won't demonstrate interoperability on the transformation algorithm in this specification.

It took over an hour to review this PR, and I'm still not confident that I understand all of the details that are changing. It's difficult to approve a PR that introduces multiple questionable changes in scope and testing simultaneously under a vague description of "Editorial and non-editorial changes".

I'm a strong +1 to rapidly updating the spec to make it better, so in that vein, I'd be a +1 to merging this, IF 1) issues are raised for all items of concern, and 2) the WG is made aware of the change in scope for VC-JWT and the signal to not test the transformation algorithm in VC-JWT.

[OR13]

@msporny

High level comments on this PR:

• It's huge and changes many normative statements simultaneously, please avoid massive PRs like this, it makes it very easy to miss important changes.

Yes, sadly this document started as a few sections cut out of the v1.1 specification and has received very few "large PRs" like this.... it needs a lot more contribution.

• The use of data-include has broken the PR Preview, which means that all examples are not viewable inline and the spec now requires you to download and run it locally to see the updates/changes. I doubt that most of the reviewers are doing this.

Interesting, do you think we should no use data include moving forward? I thought it was a best practice to use the features of ReSpec, but perhaps this one is not good to use.

• It adds CWT and COSE to the scope of VC-JWT, after feature freeze, which seems to be difficult to reconcile with scope of the VCWG Charter (and could lead to formal objections).

This PR does not add this, it moves the existing section, which was added in:

https://github.com/w3c/vc-jwt/pull/51/files#diff-0eb547304658805aad788d320f10bf1f292797b5e6d745a3bf617584da017051R707

• It defines the 'transformation' algorithm in a way that won't be tested by this WG and thus we won't demonstrate interoperability on the transformation algorithm in this specification.

This PR does not define the transformation, it moves the transformation that was supplied in:

#60

To the appendix, as was requested here:

#60 (comment)

and partially implemented by @brentzundel

It took over an hour to review this PR, and I'm still not confident that I understand all of the details that are changing. It's difficult to approve a PR that introduces multiple questionable changes in scope and testing simultaneously under a vague description of "Editorial and non-editorial changes".

Thank you for your review.

I am sorry the document is not in better shape, it is not yet FPWD, perhaps we should delay FPWD and continue to make improvements to the document cc @brentzundel @Sakurann @selfissued .

If the document is not yet FPWD, is there any change to process that I should be following to help this document catch up in terms of quality?

Recall this documented started as a cut out of version 1.1 and has received relatively few changes since then, as most of our time has been spent discussing how the media types in the core data model interact with it.

I'm a strong +1 to rapidly updating the spec to make it better, so in that vein, I'd be a +1 to merging this, IF 1) issues are raised for all items of concern,

Thanks I think I have captured the major one here:

#73

There are already several open issues that are addressing some of the comments you have left, specifically:

• Update guidance for application/vc+jwt #72
• Update application/vc+ld+jwt #71
• Define how to obtain verification keys for vc-jwt #70
• Add guidance on mapping to the core data model #69

and 2) the WG is made aware of the change in scope for VC-JWT and the signal to not test the transformation algorithm in VC-JWT.

Happy to provide an update on the next call.

[iherman]

The issue was discussed in a meeting on 2023-04-12

• no resolutions were taken

View the transcript

3.4. Editorial and non editorial changes (pr vc-jwt#68)

See github pull request vc-jwt#68.

Orie Steele: for VC JWT request for FPWD made and resolved in a previous meeting. Follow ups to possible objections made but it doesn't appear there will be objections. Go forward and prosper.
… Open pull request for vc-jwt. Some awkward sections cut from ver. 1. Have added around that some vision for enhancements and improvements for securing JSON-LD with JWTs but structure of doc difficult to revise.

Manu Sporny: almost of the opinion to not do a PR for JWT until its in a shape for all to see it in. The specific concerns are the way the transformation algorithm is stated is non-testable. Why are we discussing something that is optional.
… what are we doing with transformation algorithms, are the testable, etc.

Dave Longley: +1 to the idea that there's a lot that needs to change in the VC-JWT document to reach consensus and make something usable, but FPWD can happen first.

Orie Steele: there are many things that need work in the PR. Media type discussion in the vc specs dir, and the securing specs referring to them, etc.

Manu Sporny: I'm not super concerned either way, but would prefer we get it in better shape before FPWD, but we can also do that after FPWD..

Orie Steele: mappings and interpretations of the mapping in the core model and in the spec dir are differing...
… anything that needs done in this context?

Michael Jones: supports the recommendation that Orie prepare it before it becomes a working draft.

Brent Zundel: process info -- publishing as a FWD has patent implications. Working drafts do not represent a consensus of the WG beyond an agreement to work on the topic.
… starts the clock on patent disclosures and says its a tech we as a working group want to pursue.
… encourages folks to look through the PR that Orie has drafted, if something causes concern look for an issue that is already open on it, consider raising it later.

Orie Steele: I agree with JoeAndrieu, its not clear what you want me to do.

Joe Andrieu: Sounds like it's both a working draft and editor's draft.

Dave Longley: +1 to brent's suggestion.

Orie Steele: happy to do whatever..

Manu Sporny: +1 to "Orie go for it, we'll review, then FPWD" -- and time box the review to a week so people can't hold it up..

PhilF: +1 to Orie getting it squared away first.

Brent Zundel: should we ask Orie to finish it and then review the FPWD?
… no objections to Orie shaping the document as an editor and presenting it to the group.

Orie Steele: next time does Orie need to wait 7 days or what?

Brent Zundel: with the work mode proposed Orie should be able raise PRs people think are needed. Concerns can be tracked in the issue.

[OR13]

I have addressed the feedback provided.

Based on the call yesterday, I am merging this PR and will merge directly to main with no PRs until the document is ready to be called for FPWD.

[TallTed]

I am befuddled by the merge a minute after the request for review.

What are you asking @msporny and I to review?

[msporny]

What are you asking @msporny and I to review?

He cleared our request for changes and merged. I don't think there was an expectation that we'd re-review. @OR13 is now operating in a "commit to main" capacity and will notify the WG to do a full review of the spec, including all of his unreviewerd changes, before FPWD.