Add media type registration request

[OR13]

Addresses #978 (comment)

---

Preview | Diff

[msporny]

The media type name won't survive review, please change to credential to vc. The change controller should be the VCWG. I've requested clarification on the purpose of the profile parameter as well as the equivalence statement, which seems off.

[msporny]

Suggested change

	<h2>The <code>application/credential+json</code> Media Type</h2>
	<h2>The <code>application/vc+json</code> Media Type</h2>

I'm on the IETF mediatype mailing list as a reviewer -- I expect that claiming "application/credential" will be frowned upon -- if I saw this come across, that's the feedback I intend to provide.

I expect we'll be asked to change it to "application/verifiable-credential" or just "application/vc" as the base string (with +whatever after it) to ensure we're not stomping on any other type of "credentials".

[OR13]

I don't think I can accept this change, because the intention is to define the media type for the "data model" not the "secured data model".... unless we say that a "verifiable credential" can be "unsecured" similar to how "alg: none" is used...

In other words, proof is not a required member of application/vc+json... and likely would be a forbidden.

If thats ok, I am happy to accept this change, see the proposals on the mailing lists for the intended use of this cty with COSE and JOSE.

[OR13]

• https://lists.w3.org/Archives/Public/public-vc-wg/2022Nov/0034.html (use with JWS)
• https://lists.w3.org/Archives/Public/public-vc-wg/2022Dec/0011.html (use with COSE Sign 1)

[Sakurann]

definitions of the JOSE header parameters are very clear that

cty which is used to declare the media type of the secured content (the payload) , should be credential+xxx and not verifiable-credential+xxx.

typ which is used to declare the media type of this complete JWS should be verifiable-credential+xxx.

the ship that vc-data-model spec defined credential in a different way than identity industry used to define/use it has sailed. with credential term being more and more accepted as it is defined in vc-data-model spec, with good arguments, registration of credential+xxx should be possible.

[msporny]

with credential term being more and more accepted as it is defined in vc-data-model spec, with good arguments, registration of credential+xxx should be possible.

Alright, if the VCWG is going to get behind that argument, it might be doable. We'll have to see what the media types list says. It helps that there isn't a single registered media type that has the word "credential" in it today, we might find out why when we try to register it. :)

[iherman]

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

• no resolutions were taken

View the transcript

2.3. Add media type registration request (pr vc-data-model#1000)

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

Manu Sporny: Next PR 1000 is about media types registration..

Michael Jones: There is an important distinction between the type that is signed versus the type that is the entire thing..

Manu Sporny: https://datatracker.ietf.org/doc/html/draft-ietf-mediaman-suffixes.

Manu Sporny: Mike's comments will be useful input to the PR. Mike will provide more info in writing..

Michael Jones: IETF may need multiple plus signs..

Manu Sporny: This will have impact on the W3C VC efforts as well..
… We need more reviewers what to do to with this..

[TallTed]

This PR has a LOT of disconnected discussion of application/credential+... vs application/vc+... vs application/verifiable-credential+.... I would feel better if all that were brought into an issue, discussed there in detail, and then the results applied to this PR and our media type registration request(s)...

[msporny]

@TallTed wrote:

I would feel better if all that were brought into an issue, discussed there in detail, and then the results applied to this PR and our media type registration request(s)...

Yes, agreed. The discussions include:

1. Does the group want to have a different media type for an unverifiable credential vs. a verifiable credential?
2. Are we going to follow IETF IANA guidance on structured syntax suffixes for media types, or is the base data format implied via the media type?
3. How many different serializations and media types are we envisioning for VCs and how does this PR fit into that vision?

There seem to be multiple parallel discussions going on here, with some suggestions that we're going to have even more media types in the future. At present, given this PR, I can't tell which one of these media types are going to eventually be a valid media type for things associated with this specification:

• application/credential (presumably a JSON-LD document w/o any sort of proof? or with one?)
• application/credential+json (given that we haven't resolved Make the usage of @context optional #947, this is still a possibility?)
• application/credential+ld+json (Is this protected or not?)
• application/credential+jwt (Is this a VC-JWT? Or a VC-JOSE/VC-COSE media type?)
• application/verifiable-credential (presumably a JSON-LD document w/ a proof?)
• application/verifiable-credential+json (given that we haven't resolved Make the usage of @context optional #947, this is still a possibility?)
• application/verifiable-credential+ld+json (protected JSON-LD, I presume?)
• application/verifiable-credential+jwt (Is it this one or the one above?)

It's hard to understand where the current proposal fits in the options above, and it's not clear that making the distinction between a "credential" and "verifiable credential" via the media type really buys us enough value. I can see a future where we have the following media types (/cc @gkellogg):

• application/vc+ld+json (for data integrity protected and unprotected payloads)
• application/vc+jwt (for JWT-protected payloads -- utilizing the +jwt structured syntax suffix)
• application/vc+cwt (for CWT-protected payloads -- though there is not +cwt structured media types suffix registered -- don't know why that wasn't registered via IANA, it's worth looking into)
• application/vc+ld+cbor (for data integrity protected and unprotected payloads encoded as CBOR-LD, presuming a +ld+cbor structured suffix)
• application/vc+ld+yaml (for data integrity protected and unprotected payloads encoded as YAML-LD, presuming a +ld+yaml structured suffix)

@OR13, what's the plan here -- which one of the above are you intending as options? Are there more?

[OR13]

@msporny the intention is implemented in the PR, the proposals here explain one potential use of this type in JOSE and COSE:

#1000 (comment)

Looking forward to discussing on a special topic call.

[mprorock]

@msporny the intention is implemented in the PR, the proposals here explain one potential use of this type in JOSE and COSE:

#1000 (comment)

Looking forward to discussing on a special topic call.

this should be a good discussion, and hopefully productive. I don't think we need to have all answers in at once, especially as we are in "work in progress" mode. concern from my side that we might make "perfect" the enemy of the good here and prevent forward progress by trying to define every possible case in advance, rather than moving forward with one or two items we know we need, and then hashing out details as we go on the other items

[OR13]

@mprorock Agree mike, this topic has already been discussed a lot.

There are a lot of places where credential and not verifiable-credential show up... and because of the security differences it is critical they be identified as unambiguously as possible.

[msporny]

@OR13 wrote:

There are a lot of places where credential and not verifiable-credential show up... and because of the security differences it is critical they be identified as unambiguously as possible.

I'm on board with the concept of having two different media types, and also dubious that developers will use them properly for the same reason that did:web is recommending that the DID Document can be served as application/json. We know developers get this stuff wrong, and the more media types we have, the higher the chances are that they'll pick the wrong media type.

I don't think we need to have all answers in at once

Neither do I, but I do think that we have to have a better understanding of the path forward than what we have right now. We don't want to paint ourselves into a corner either. My hope is that we can get to that plan in the upcoming Special Topic call.

rather than moving forward with one or two items we know we need, and then hashing out details as we go on the other items

Yes, you can make iterative progress that way... and it's also how one paints themselves into a corner. That's the concern here.

All that said, here's a cut at a unified philosophy for doing media type processing:

1. There will be at least two media types, one for unsecured credentials and another for secured credentials.
2. The unsecured credential media type will be application/credential+json, which will be equivalent to application/ld+json with a profile set to https://www.w3.org/ns/credentials.
3. The secured credential media type will be application/verifiable-credential+json, which will be equivalent to application/ld+json with a profile set to https://www.w3.org/ns/credentials.

Once we define these media types, we'll have to talk about what happens when things go wrong, such as:

1. What happens when the client just requests application/json for a known good application/credential+json resource?
2. What happens when the client requests application/credential+json but the server responds with application/json?
3. Same questions above, but for application/ld+json instead of application/json?
4. What is the content type for a data integrity protected application/credential+json? A JWT-protected one? A JWS-protected one? A CWT-protected one?

I suggest the answers to the questions above are:

1. Return the same content as for application/credential+json using the IANA Media Type Structured Suffix algorithm.
2. Use rules (yet to be written) to do deterministic content sniffing on the payload (look for @context with specific values (for v1 and v2) in the first array element).
3. Same as answer to 2 above.
4. application/verifiable-credential+json, application/verifiable-credential+jwt, application/verifiable-credential+jws, and application/verifiable-credential+cwt, respectively.

Thoughts?

[OR13]

Yes (I think) to 1, and 4... maybe 2 and 3... I think we should cover negotiation and the Accept parameter separately from defining Content-Type.

[dlongley]

Cross-posting this here from #978:

Also, if people want to publish VCs in web pages, which media type should they use? Is it going to make things more challenging for this use case if we have extra media types that mean the same thing? People publish structured data using application/ld+json today and it's consumed by major search engines.

[dlongley]

For JOSE (JWS-secured) containers, it seems one could do application/jose / application/jose+json with a cty for the unsecured payload being application/ld+json with a profile of https://www.w3.org/ns/credentials -- this means no new core media types would need to be invented. If there's a need for something new (and we should be clear about what it would accomplish and what the trade offs would be for the added complexity), it seems the unified processing model @msporny proposed could be explored as a potential solution.

[OR13]

@dlongley I would guess that both application/credential+ld+json and application/verifiable-credential+ld+json would be compatible with application/ld+json... and application/json...

Indeed, your comment about using application/ld+json in a cty is exactly why we request the registration of application/credential+ld+json... Implementers want to be able to switch on cty when processing JOSE headers.

And they like the ability to be as specific as possible.

[OR13]

Suggested change

	This specification registers the <code>application/credential+json</code> MIME Media Type specifically for
	This specification registers the <code>application/credential+ld+json</code> MIME Media Type specifically for

[selfissued]

Yes, please apply this correction.

[msporny]

Having had a discussion with @OR13 about this, I understand that this PR is quite focused in what it's attempting to achieve and I agree with what this PR is attempting to achieve, which is at least one registered media type that can be used in cty, there may be others that the group registers in the future and those should go in separate PRs.

[msporny]

Normative, multiple reviews, changes requested and made, no objections, merging.

[OR13]

For folks wondering how to use this new media type, here is an example:

• https://github.com/transmute-industries/vc-jws/pull/5/files
• https://transmute-industries.github.io/vc-jws/

[OR13]

Here is the media type in use with cose sign 1:

• https://github.com/transmute-industries/vc-cose/pull/10/files
• https://transmute-industries.github.io/vc-cose/

[iherman]

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

• no resolutions were taken

View the transcript

1. Add media type registration request (pr data-model#1000)

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

Orie Steele: Any objections to merging PR #1000?.

Phillip Long: +1 for merging.

Kristina Yasuda: I think we should merge it..

Dave Longley: +1 to merging.

Orie Steele: There are more approvals than I've seen on any PR since we resumed working..
… There were change requests that were accepted, which became approvals..

Brent Zundel: Please give us a summary.

Kerri Lemoie: Yes - overview would be helpful..

Brent Zundel: If there are no objections, I believe it would be appropriate to merge it.

Orie Steele: A credential becomes a Verifiable Credential when it contains an embedded or external proof.
… The media type describes this core data model type without or possibly with a proof.
… We can take a step closer to resolving ambiguity in the specification.
… We can use this content-type to describe the content that is secured in the specification.
… There are two proof formats in the spec: embedded and external.
… Data integrity proofs use embedded, VC-JWTs use external.
… The purpose of this PR is to describe the thing that we're securing.
… It can become a Verifiable Credential by securing it.
… Having a media type gives us a way to talk about what it is.

Michael Jones: Merge it.

Manu Sporny: The only thing that prevents divergence is talking to one another across the specs.

Michael Prorock: +1 manu - editor comms, working group eyes - same as any other media type or external pointer (e.g. to alg combinations).

Manu Sporny: It's always possible to register too many media types or create non-interoperability.
… We need to talk to one another.
… When there are other media types, we need to ensure that they're aligned with our philosophy across the specifications.
… If they diverge, they need to do so for very good reasons.

Michael Prorock: There's an important lesson from this PR. The quickness of its approval indicates that this was needed..
… If things get fuzzy later, at that point we can step back.
… For this one, we quickly got to something useful.

Brent Zundel: At this stage, we first wanted to talk about PR 1000.
… We have a lot of approvals. It would be entirely appropriate to merge it..

Manu Sporny: Please provide something for the disposition comments when you merge things..
… I will add the disposition comments.

Brent Zundel: Can the associated issues be closed?.

[mwherman2000]

Can someone add or point to what the definition/purpose/goals of a "media type" is/are to this conversation?

The above discussion is quite abstract if it isn't anchored in an agreed upon definition/purpose/goals of what a media type is.

UPDATE: Is this an agreeable definition? https://developer.mozilla.org/en-US/docs/Glossary/MIME_type

If so, then the chosen credential media types need to specifically reflect the physical format/structure/serialization of each type of credential. ...and by implication, "application/credential" should never be acceptable (as a standalone media type) because it is too general.

The media type naming pattern also needs to be naturally extendable to allow for additional credential types in the future.

For example, https://youtu.be/uo4RuT__IXw?t=2685s suggests some dimensions to consider when designing a credential media type "namespace".

From https://en.wikipedia.org/wiki/Media_type

The +xml suffix has been defined since January 2001 (RFC 3023[13]), and was formally included in the initial contents of the Structured Syntax Suffix Registry along with +json, +ber, +der, +fastinfoset, +wbxml, and +zip in January 2013 (RFC 6839). Subsequent additions include +gzip, +cbor, +json-seq, and +cbor-seq.[14]

Per https://en.wikipedia.org/wiki/Media_type, perhaps "credential" should be advocated as a top-level media type ...a peer to "application" and "text".

(Go big or go home 😉🙂 ...after all we are designing the future Internet.)

[mwherman2000]

For example, something like the following...