Request media type for 1.1 vc-jwt claim set #40
Conversation
There was a problem hiding this comment.
The media type (which is a subclass of an unprotected JWT) can be confused w/ a media type for an (unprotected) credential. The media type needs to be more clear about the notion that this is a JOSE structure. Perhaps the JOSE WG should register a structured suffix for that purpose, which would make creating this media type easier.
index.html
Outdated
| <section class="appendix informative"> | ||
| <h2>IANA Considerations</h2> | ||
| <section id="media-type"> | ||
| <h2>The <code>application/credential-1.1+json</code> Media Type</h2> |
There was a problem hiding this comment.
| <h2>The <code>application/credential-1.1+json</code> Media Type</h2> | |
| <h2>The <code>application/credential-1.1+jose+json</code> Media Type</h2> |
If this PR is about JWT claim sets, the media type identifier should contain that information in there somewhere.
Otherwise, people might misunderstand this media type to be THE media type for v1.1 VCs.
IOW, this media type could be seen as squatting on the main spec's media type.
There was a problem hiding this comment.
its a payload type, not a "jose" type... jose currently refers to the entire token....
There was a problem hiding this comment.
Hmm, I'm confused by this. This media type is to identify a specific JWT claims set that has the vc claim in it, right? For example:
{
"vc": {
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": [
"VerifiableCredential",
"UniversityDegreeCredential"
],
"issuer": "https://example.edu/issuers/565049",
"issuanceDate": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
},
"iss": "https://example.edu/issuers/565049",
"nbf": 1262304000,
"jti": "http://example.edu/credentials/3732",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}Is that right? If so, it seems like we should have jwt in the media type somewhere. Perhaps application/credential-1.1+jwt? This would be similar to application/at+jwt -- where the JWT must have access token claims.
This is to be used in the typ claim, right? The cty claim is "NOT RECOMMENDED" per RFC 7519 except for nested signing / encryption (a JWT within a JWT) cases, which I don't think we're talking about here.
There was a problem hiding this comment.
JWS can sign anything - does not have to be a JWT. application/credential-1.1+json would allow signing using JWS a conformant structure which is not necessarily a JWT?
wrt nested JWT, it is a confusing term... it is defined as
A JWT in which nested signing and/or encryption are employed. In
Nested JWTs, a JWT is used as the payload or plaintext value of an
enclosing JWS or JWE structure, respectively.
so JWS(JWT claims) and JWE(JWT claims) are technically nested JWTs (though it is usually used for JWE(JWS(JWT claims)) ) is also a nested JWT so it is kind of in scope...
There was a problem hiding this comment.
application/credential-1.1+jsonwould allow signing using JWS a conformant structure which is not necessarily a JWT?
But this PR says that when application/credential-1.1+json is used then it means the payload is a JWT Claims set ... right?
If not, when one sees application/credential-1.1+json in the cty field, what is the expected payload? What does the JSON look like if it isn't a JWT Claims set? It seems we need to enumerate the possibilities in this PR / change the text if it can be something other than that.
There was a problem hiding this comment.
In my research preparing this PR, I have not seen any example where
claimsetwas present in other use ofcty.
Yes, but I think that's because using cty when the payload is a claim set is recommended against. This is what I've been saying. If the payload is a claim set, you don't use cty -- at least this is what people who follow the RFC have been doing. Using cty in that case would be redundancy, IMO. The payload is assumed to be a claim set unless otherwise specified via cty, like when the content type is jwk+json or a nested JWT.
@selfissued noted that would be redundant on the last call and I agree.
I don't understand how it's redundant (clearly this is a different redundancy from what I said above). Perhaps there's an assumption about where the media type "may appear" -- but media types don't work that way. So, the media type name should properly reflect what it identifies regardless of where it appears.
Furthermore, using cty is a signal that the payload is not a claim set, but, rather, is whatever the media type says it is. This, to me, is an even stronger indication that we need to be clear -- we're using cty where it is advised against by the RFC, we haven't been able to find cases where other people do it (thus far, unless they are using non-claim sets), and the thing we're identifying is not a credential... but there actually is a thing that is a credential that it could be erroneously confused with.
There was a problem hiding this comment.
Can you therefore withdraw the suggestion, @msporny ? Thanks.
The suggestion was to use SOMETHING to denote that the object isn't a VC as defined by the v1.1 data model, but a claim set that wraps a VC. So, we don't have to use +jose literally, but we do have to differentiate this thing vs. the v1.1 data model because the data structures are observably different.
One of the data structures is a claims set that wraps a VC, the other is a VC. Those are two different things.
There was a problem hiding this comment.
@dlongley wrote:
Furthermore, using cty is a signal that the payload is not a claim set, but, rather, is whatever the media type says it is. This, to me, is an even stronger indication that we need to be clear -- we're using cty where it is advised against by the RFC
The definition in the PR explicitly says that it is a media type "identifying a JWT Claims Set conforming to the Verifiable Credentials 1.1 JWT format". So there's no doubt that it's a JWT Claims Set.
As for the JWT spec saying "In the normal case in which nested signing or encryption operations are not employed, the use of this Header Parameter is NOT RECOMMENDED." about cty, as the author of that sentence and an author of the JWT BCP, I can definitively say that explicit typing of objects is now favored by the IETF - which wasn't something we thought of a decade ago as we were developing the JWT spec. Yes, a JWT payload is always a JWT Claims Set, but there are numerous different kinds of JWT Claims Sets - one of which is the one identified by the proposed Media Type. Using cty enables us to use explicit typing to tell the difference between them.
@msporny wrote:
The suggestion was to use SOMETHING to denote that the object isn't a VC as defined by the v1.1 data model, but a claim set that wraps a VC.
The something that indicates that the object isn't a VC is that it's called a credential in the Media Type name. If we were to define Media Types for Verified Credentials, they would have vc (or verifiable-credential) in the name - not just credential - which indicates a yet-to-be-secured credential. The credential becomes verifiable once it's secured.
There was a problem hiding this comment.
The definition in the PR explicitly says that it is a media type "identifying a JWT Claims Set conforming to the Verifiable Credentials 1.1 JWT format". So there's no doubt that it's a JWT Claims Set.
Many people will not read the full description, instead only looking at the media type name.
I don't understand your "redundant" argument since it seems that any name at all would be redundant if we're relying on people always reading the description. But, if you are really ok with the name being anything that isn't "redundant", because you think the description is clear, then let's change the name to address my concern and yours. As I said, I don't know what wouldn't be "redundant" to you, so if you could suggest something new to address both of our concerns, please do.
I'm happy for us to use another name that doesn't include "claim set" in it, so long as it won't be confused with a credential or some other thing this group defines / has defined. I don't think it's ideal for the name to not reflect what it is, but I'm more concerned about basic confusion. My preferences are for avoiding confusion first and then second for good naming hygiene (clearly name things after what they are / refer to).
There was a problem hiding this comment.
@dlongley wrote:
Many people will not read the full description, instead only looking at the media type name.
I'm not sympathetic to arguments based on the premise that people won't read the specification. If one follows that to its logical conclusion, we shouldn't bother writing anything down at all.
As already discussed, using the name credential aligns with the way we describe the data structures this working group has invented - and is distinct from "Verifiable Credential". I think we're good to go as-is.
|
|
No, the
I'd say use https://www.iana.org/assignments/media-type-structured-suffix/media-type-structured-suffix.xhtml but it looks like RFC9068, RFC9101, and RFC8417 already break that guidance when used with So, why can't we use |
|
can we clarify that a credential with this media type in this PR follows the steps defined in section 6.3.1. of v1.1? (and also clarify what transformation logic do credentials with media type in PR #1000 of vc-data-model have to follow..) |
There would never be a "credential" that has this media type. Something with this media type would be "a JWT Claims Set with the "vc" claim that requires transformation per the VCDM 1.1 mapping rules to 'become' a credential". The fact that it's already being read as "a credential with this media type" is the confusion I'm worried about. |
|
The issue was discussed in a meeting on 2023-01-17
View the transcript4. Request media type for 1.1 vc-jwt claim set (pr vc-jwt#40)See github pull request vc-jwt#40. Brent Zundel: Next we will look at VC-JWT PR #40. Orie Steele: Now that we've merged PR #1000, we have a media type describing a credential without a proof.
Orie Steele: These proposals need to be updated to use the new media type.
Manu Sporny: This PR confused me.
Manu Sporny: I looked at other RFCs that defined media types.
Orie Steele: This is for "cty" - not "typ".
Orie Steele: In particular, the instead-of vs. in-addition-to.
Orie Steele: We expect developers to switch on the media type.
Orie Steele: But for sure, they are going to be versioned. Dave Longley: RFC 7519 recommends against using "cty" for a JWT. Orie Steele: I've read that section of the RFC and was similarly confused by it. Michael Prorock: cty is used to actively switch on content.
Michael Prorock: I would not let versioning being imperfect block us from merging this. Michael Jones: I wrote that text in 7519... over a decade ago, different environment. since then, JWTs succeeded. used for all types of things we never imagined. secure caller id, others.
Michael Jones: agree with mprorock. versioning may not be perfect. can refine it. more important to put a stake in the ground, refine something that's versioned. this is a first attempt. shouldn't stand in the way of merging. Brent Zundel: I will note that JWT-VC PR #40 is not in the same position of PR #1000. Manu Sporny: We keep saying that this will only be used with "cty", but that may not be true. Dave Longley: I'd like to see Claims Set in the name. Antony Nadalin: I'm trying to understand if "cty" is going to mandatory. Orie Steele: We don't know yet.
Orie Steele: My gut is that it doesn't need to be required because it's not in current 1.1 VC-JWTs.
Orie Steele: It's OK to uniquely identify the structured data element before we completely describe it.
Orie Steele: Doing it the beginning helps us separate 1.1 and 2.0 ideas. Michael Jones: Very good question from dlongley and others. why not claimset? in the same way we recommend specific content types that are specific as possible for typ. we want to use as specific as possible for cty, for the body, to prevent confusion.
Manu Sporny: That didn't go were I thought Mike was going.
Dave Longley: We're talking about two different JSON data objects: One is a credential - one is a Claims Set.
Dave Longley: Those things don't line up to me.
Dave Longley: If we include in the name that it's a Claims Set, then the confusion goes away.
Dave Longley: You can declare that this is 100% compatible with 1.1 VC-JWT with this cty.
Michael Jones: I'm fine adding the clarifying comments folks are asking for. Only intended for 'cty' and we could add it is a media type for a jwt claim set as defined by 1.1 VC JWT section.
Michael Jones: but am opposed to adding redundant stuff to the name.
Manu Sporny: I'm hearing multiple things being said.
Manu Sporny: I've heard that this isn't just for VC-JWTs. Orie Steele: This media type is intended to define the payload of a VC-JWT 1.1. Brent Zundel: I think this was a very productive call.
Brent Zundel: Please continue conversation in VC-JWT PR #40.
|
Co-authored-by: Mike Prorock <mprorock@users.noreply.github.com>
|
Just to be clear, this is the corner that we're painting ourselves into:
I had to create a decision matrix because the decision process around media types is going to get very complicated for developers... there are 40 possible outcomes to consider when picking a media type (based on the PRs being raised across multiple repos), which is probably going to be too much for developers to get right when designing systems. If you have thoughts on the matrix above, please comment here, I'm sure I'm missing some media types people are expecting to register eventually: https://docs.google.com/spreadsheets/d/1RBsAG2VwbD8Rxi7zwcTT-H2A8F1fIXmWxJLzxKvyvBw/edit#gid=0 |
There was a problem hiding this comment.
The name of this proposed media type needs to be changed to reflect that it does NOT identify a credential in order for me to support this PR.
This media type is intended to identify a JWT Claims Set -- which is NOT a credential, and this group does define a different thing that is a credential. This is unacceptably confusing and the remedy is simple: change the name to avoid the confusion.
Additionally, RFC 7519 unambiguously states that the cty header parameter is NOT RECOMMENDED for the normal case. The cty parameter is used when the content is not an expected JWT Claims Set, but is instead, for example, a Nested JWT (a dotted-base64url string). The author of this RFC stated on a call that we should ignore this advice, but nearly all people will only have access to the RFC and up to ~8 years of experience (since its authorship) of developing or using software that followed the RFC and the reasoning there. Using the cty field against the recommendation in order to signal that the payload is a claim set is likely to confuse people. I do not believe the need to do this to satisfy a use case has been clearly technologically justified nor have the alternative solutions to the use case that were rejected (and why) been clearly explained.
That being said, I will only continue objecting to this PR while the name of the media type suggests that it identifies a credential, which it does not. I'm not here to stop people from contradicting RFC advice by misusing the cty field in a JWT in their use cases somewhere (not that I could do that anyway).
However, I do very much object to this group creating a media type with a name that will create confusion around what is and is not a credential per the specifications we create / have created.
I've offered alternative names for the media type that would remove my objection. Some of these have been called "redundant" without saying why. I've explained that it appears the opposite is true. It is good for the media type name to say it identifies a claim set when this media type will appear in the cty field, a field that the RFC says is for describing payloads other than JWT Claims Sets ("normal case").
Also, even if we were to accept the "redundant argument" against being clear in the media type name, it seems to be based on one specific use of the media type, not all uses. We should certainly not expect people to only use a media type in one place. Therefore, even if this argument held water, it is not a good enough argument not to use another name, especially when the media type name clearly confuses something for a credential that is not a credential.
If people do not want what the media type identifies to be in the name of the media type (I find this troubling), at the very least, it must not be easily confused with something that identifies a credential, which it does not. So other names that don't do this would also be acceptable.
Yes, I put my thoughts here: #40 (review) I want a new media type name that isn't easily confused with a credential as defined in the 1.1 spec, i.e., the media type that identifies something other than a credential as defined in the 1.1 spec SHOULD NOT be I expect that a new name that avoids confusing what this media type identifies with other things this group defines will be acceptable to me. |
@dlongley I completely disagree with this statement, and feel like it is trying to rewrite history. From the VC-1.1 JWT definition (emphasis mine):
It then defines the credential properties that can be stored in the JWT claims. The claims set is absolutely a credential with a specific transformation as defined in the standard. This media type unambiguously registers the credential format for a JWT claims set as defined in 1.1. |
|
You quoted the spec:
This quote is about a verifiable credential that is encoded as a JWT. As I mentioned above, I'd be fine with us defining a media type named |
|
There are a number of comments in this thread that suggest that the commenters are mixing up how media types work.
From top to bottom, each of those must be defined for the next to be valid. Neither The Please, if you've made comments above, review your comment(s). If there is anything there which appears to contradict this comment, and you can't see what to do to resolve that contradiction, please make a new comment highlighting that issue, and I'll try to clarify further. We must have at least this degree of understanding common among us, if we're to hope to come to workable conclusions about the several media types we seem to need to register, based on the length of this thread (among others). |
|
@msporny I appreciate you taking the time to make the matrix. I was thinking of the same thing. The question I'm asking myself is this a corner we're already painted into and just a clarification of the current state of things, or is this also inviting new corner painting? How can we avoid the propagation of endless media types? Should we even attempt to? |
|
just to stir the pot, we could also utilize one approach that overloads the vendor side of mime types to cover version like so: or as I suggested on call: |
|
Note from the call
|
i would suggest we replace |
|
I think that using "credential" for something other than the data model defined in the VCDM as a credential is going to cause significant confusion and lead to improper and insecure use in the marketplace. We already have confusion about the VC as a real-world credential versus VCs that represent a real-world credential. Adding more confusion will not help. |
|
During the VCWG meeting on 2023 01 25 it was resolved to merge this PR after changing the media type to This resolution was made with the objections of two WG participants, whom the minutes will show ultimately decided to not block the proposal, though the rights were retained to wave an |
Here's an update based on some feedback from the group and the most recent meeting:
It's inviting new corner painting. We still have a possibility to reduce the number of media types by, but not if we do a random walk across media types as we need them.
Yes, absolutely, we should try to minimize media types as much as we can because, if we don't, it will almost guarantee that developers will use the wrong media type in the wrong scenario. The decision matrix above is what developers are going to have to consider when working with the VCDM... now, compare that to |
|
The issue was discussed in a meeting on 2023-01-25 List of resolutions:
View the transcript4.11. Request media type for 1.1 vc-jwt claim set (pr vc-jwt#40)See github pull request vc-jwt#40. Michael Jones: would like to discuss extensive review on PR 40. Ted Thibodeau Jr.: I think it needs a bit more than wordsmithing; I'm generally not in favor of merging a thing that needs smithing, since that might never happen. Manu Sporny: I don't think we have consensus here. Orie Steele: I think, like Manu said, there's consensus that this needs to exist.
Orie Steele: and whether or not this is really a credential -- I think in the interpretation of v1.1, this is actually a credential.
Orie Steele: so, I request we file an issue registering that there's no name consensus, but merge this PR.
Michael Jones: I want to agree with something that Ted said, which is - there IS some confusion among some people who commented about how media types are used.
Michael Jones: I think it's time to merge this, so we can strongly type things. and continue bikeshedding.
Dave Longley: I'm a strong -1 to merging this without just changing the name.
Dave Longley: I'm less concerned about that, than I am concerned about calling something jwt 1.1 credential, whereas the spec has it as something different.
Dave Longley: it seems very inconsistent that people will go read /that/ spec, ignore the text, then go read our spec, and listen to it.
Dave Longley: but all that aside. the main concern is with the name that confuses a JWT Claimset, which is very different from a credential in JWT 1.1 format.. Manu Sporny: I find it troubling that we've repeatedly brought up technical issues on this PR, and they're being ignored.
Manu Sporny: one could argue that this is a continuation of the 'make context optional' conversation.
Brent Zundel: I want to run a straw poll, see where consensus lies.
Brent Zundel: so let's see what happens, and iterate.
Brent Zundel: and... people all hate it, wow.
Manu Sporny: it's not about a JWT, it's about a claims set.
Brent Zundel: ok! well, at least we have consensus on that.
Kristina Yasuda: I think you should run the same proposal about application.credential json. Michael Jones: yeah, that's what's in the PR.
Brent Zundel: we have 6 '-1s', which is more opposition than I was hoping. Michael Jones: manu, I don't find it's helpful when you say that technical issues have not been addressed. this is a pattern that you have. if you read the comments, you'll find issues are addressed.
Michael Jones: secondly, if it provides a path forward, it's not the end of the world if we add 'claimset' to the name; I'll run a proposal for that.
Brent Zundel: the proposal is in, is the 1.1. part necessary?.
Brent Zundel: ok, seems to be a feeling that it's critical.
Brent Zundel: all right, in general, this is way more consensus.
Brent Zundel: I'm only seeing one -1 at this point -- Joe, would you like to speak to it?. Joe Andrieu: I think we all know that naming is hard,.
Joe Andrieu: since it seems like I'm a lone voice, I won't block it, but I wish we had a better name.
Ted Thibodeau Jr.: media types rarely if ever include a version number in them, for very good reasons. I dont think it should be included.
Ted Thibodeau Jr.: as I've said here and in the issue, I really want the people who are approving this to demonstrate they understand the technical aspect of how media types work, since I still don't think everyone who is participating/voting has that understanding, which is I think why the naming is not proceeding well.
Brent Zundel: the question for you, Ted, is -- if the issue is raised to continue working on the name, would you still be opposed to the PR.
Ted Thibodeau Jr.: yes, because if the thing we settle on is going to continue to percolate, tracking it down to change it again might be difficult.
Brent Zundel: before we go back to the queue, Ted, I don't appreciate your assertions that those involved do not have the expertise necessary to have the opiniion. Ted Thibodeau Jr.: I'm basing my assertion on the comments in the issue, that demonstrate the lack of understanding. Kristina Yasuda: I'm sorry Brent, I'm still not OK with the language used.... Ted Thibodeau Jr.: that's very different language, and I'm sorry, we should have an offline conversation.
Kristina Yasuda: thank you, yes, let's have it offline. Brent Zundel: we are over time. Orie Steele: I was queued to comment on the specific binding to 1.1.
Dave Longley: just quickly, I appreciate people moving to change the name to address my concern. I''m no longer blocking the PR on those grounds.
Dave Longley: I want to caution people that I made a number of technical arguments quoting different specs, I want to make sure you do the right thing.
Manu Sporny: to echo Dave, I also am no longer blocking the PR.
Manu Sporny: so this is a request to the chairs to maybe have a special topic call on media types.
Manu Sporny: so that we can all get on the same page. Brent Zundel: thank you Manu. Kristina Yasuda: Ted, would you prefer a special topic call before merging. Ted Thibodeau Jr.: no, go ahead and merge, if it goes wrong in deployment, I'll wave my 'told you so' hat.
Brent Zundel: thank you all for attending and for your comments. |
| </tr> | ||
| <tr> | ||
| <td>Subtype name: </td> | ||
| <td>credential-1.1+json</td> |
There was a problem hiding this comment.
This needed to be updated too, if an editor wants to quickly fix it.
editorial, based on #40 (comment)
Preview | Diff