Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add section describing use of media types #1055

Merged
merged 8 commits into from
Mar 7, 2023
Merged

Add section describing use of media types #1055

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3c6b8b5
chore: add section describing use of media types with syntaxes
mprorock Mar 1, 2023
b1e0616
correct spelling
mprorock Mar 1, 2023
3bab618
adjust language for clarity
mprorock Mar 1, 2023
7c81bc2
correct line breaks
mprorock Mar 1, 2023
59532a5
Apply suggestions from code review
mprorock Mar 1, 2023
76b1200
correct grammar
mprorock Mar 1, 2023
bda384a
caps for a SHOULD
mprorock Mar 6, 2023
fee2e8c
chore: open issue #1060 to discuss proof in relation to media type
mprorock Mar 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3409,6 +3409,44 @@ <h3>Syntactic Sugar</h3>
</section>

</section>
<section>
<h3>Media Types</h3>

<p>
Media types as defined in [[RFC6838]] serve a useful purpose with verifiable
credentials, especially in regards to identifcation of a particular syntax
mprorock marked this conversation as resolved.
Show resolved Hide resolved
that is in use with a verifiable credential.
</p>
<p>
Syntaxes SHOULD be identified by a media type, and certain conventions as
outlined in this section should be followed when defining or using media types
mprorock marked this conversation as resolved.
Show resolved Hide resolved
mprorock marked this conversation as resolved.
Show resolved Hide resolved
with verifiable credentials.
</p>
<p>
Any media types associated with the core data model are listed in the section on
<a href="#iana-considerations">IANA Considerations</a> for registration with IANA.
</p>
<p>
When defining a media type for use with verifiable credentials, for instance in a
specification that defines a specific syntax, use of the term `verifiable` implies
mprorock marked this conversation as resolved.
Show resolved Hide resolved
the presence of a <a href="#proofs-signatures">proof</a> with the credential.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yikes to this... I might defer this language to a separate PR to avoid blocking this valuable other changes.

proof is NOT required to make a VerifiableCredential... asserting that proof makes a VerifiableCredential implies data integrity proofs as a defacto standard representation / serialization for the core data model.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah - this is one reason why i wanted this as a draft first - we do i think want to note that some cryptographic proof is there, not necessarily that it is in the credential as an embedded proof (as it often is not) but that it should be present according to the securing method in use

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we remove this paragraph on "proof" ? and move it to an issue to discuss?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#1060 opened, paragraph removed to refine language

Copy link
Contributor Author

@mprorock mprorock Mar 1, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
the presence of a <a href="#proofs-signatures">proof</a> with the credential.
the presence of a <a href="#proofs-signatures">proof</a> with the credential either embedded or external to the credential.

@OR13 note that i linked directly to the section that calls out both embedded AND external proofs intentionally here. perhaps some additional language as in this suggestion would help

edit: to quote spec text i linked to At least one proof mechanism, and the details necessary to evaluate that proof, MUST be expressed for a credential or presentation to be a verifiable credential or verifiable presentation; that is, to be verifiable.

Copy link
Contributor

@OR13 OR13 Mar 1, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At least one proof mechanism, and the details necessary to evaluate that proof, MUST be expressed for a credential or presentation to be a verifiable credential or verifiable presentation; that is, to be verifiable.

I feel like this spec text is being disputed by @iherman @TallTed @dlongley @msporny and possibly others.

Media types MAY be registered with more than one suffix appended to
the base subtype name. The suffixes MUST be interpreted as ordered.
Valid media type names containing a structured suffix are built from
right to left (not left to right). Characters on the left-most side
of the left-most "+" in a subtype name specify the base subtype name.
Characters to the right of each "+" in a subtype name denote
additional structured syntax suffixes.

Media types with more than one suffix MUST be registered according to
the procedure defined in [RFC6838]. A new base subtype name MUST
only be registered with suffix combinations that are already
registered in their own right in the Structured Syntax Suffixes
registry (https://www.iana.org/assignments/media-type-structured-suffix/media-type-structured-suffix.xhtml).

While it is possible for a given media type to be assigned additional
names, the use of different names to identify the same media type is
discouraged.

(🔥 let us not register 2 media types that can be used for the "same bytes").

Media types that make use of a named structured syntax SHOULD use the
appropriate registered "+suffix" for that structured syntax when they
are registered. By the same token, media types MUST NOT be given
names incorporating suffixes for structured syntaxes they do not
actually employ. "+suffix" constructs for as-yet unregistered
structured syntaxes SHOULD NOT be used, given the possibility of
conflicts with future suffix definitions.

(🔥 let us make sure things are actually verifiable or credentials).

Based on this comment: #1044 (comment)

VerifiableCredential might contain proof (modified since proof is actually optional in VerifiableCredential.)

VerifiableCredential is a subtype of Credential

processing from right to left...

  • is the credential ... json ?
  • is the credential ... ld+json?
  • is the credential ... verifiable+ld+json? (does this violate the MUST NOT or SHOULD NOT from the RFC?)

Compared to...

  • is the verifiable ... json ?
  • is the verifiable ... ld+json ?
  • is the verifiable ... credential+ld+json ? (does this violate the MUST NOT or SHOULD NOT from the RFC?)

Copy link
Member

@TallTed TallTed Mar 2, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At least one proof mechanism, and the details necessary to evaluate that proof, MUST be expressed for a credential or presentation to be a verifiable credential or verifiable presentation; that is, to be verifiable.

[@OR13] I feel like this spec text is being disputed by @iherman @TallTed @dlongley @msporny and possibly others.

What a strange feeling... as I am not disputing that sentence at all.

I cannot make heads or tails of the remainder of your comment. Maybe try writing full sentences, including what brought you to quote the chunks of draft and ratified RFCs?

A reminder: "Classes" and "Types" do not require Media Types to be defined and useful. A "tiger" is a subtype of "cat", which is a subtype of "mammal", etc. None of these have Media Types, but they are all useful descriptors. A "CompactDisc" is disjoint from "CassetteTape" and both are disjoint from "VinylLP", but all are subtypes of "Audio Recording Media", so all might be considered Media Types ... but this typing is not handled by RFC nor IANA.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@TallTed The line of argument you have here: #1055 (comment)

Regarding proof, is what leads me to believe that you do not see a difference in information between credential and verifiable credential.

Copy link
Contributor

@dlongley dlongley Mar 2, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@OR13,

let us not register 2 media types that can be used for the "same bytes"

This is literally what the + syntax does in media types. You can describe the string {} using either application/json OR application/ld+json today. There are numerous other examples with +xml suffixes and others. This subclassing is done on purpose to enable many different use cases.

@TallTed has done an excellent job in various threads explaining these rules -- but I fear there continue to be some misunderstandings.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given the comment from @TallTed #1055 (comment) , then I would suggest we amend the proposals to be the following:

PROPOSAL: The 1 media type for vc proposal, the working group will register verifiable-credential+ld+json and the working group will not register credential+ld+json.

PROPOSAL: The 2 media type for vc proposal, the working group will register verifiable+credential+ld+json and the working group will register credential+ld+json.

Copy link
Member

@msporny msporny Mar 3, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@OR13 wrote:

let us not register 2 media types that can be used for the "same bytes"

The notion that you can't have two media types used for exactly the same set of bytes is provably wrong.

For example:

application/octet-stream can be used for any binary data that the server can't determine a more specific media type for, such as application/efi. application/xml can be used for any of the roughly 400+ media types that use XML as their serialization mechanism.

In addition, we have the whole concept of structured syntax suffixes. I didn't understand how they worked until just a few years ago, and I can see that others in these threads on media types still don't understand how they work, which is resulting in some unworkable proposals/statements being put forward. Structured Syntax Suffixes are one of those rarely talked about/understood things about media types. They say for EXACTLY THE SAME SET OF BYTES, you can serve and interpret those bytes as:

  • application/verifiable+credential+ld+json
  • application/credential+ld+json
  • application/ld+json
  • application/json

So, four media types can be used for exactly the same set of bytes. This was established at IETF/IANA long ago, and is now being further documented because people are still confused about the point above.

@OR13 wrote:

being disputed [@OR13] #1055 (comment) by @iherman @TallTed @dlongley @msporny and possibly others.
@TallTed wrote:
What a strange feeling... as I am not disputing that sentence at all.

Yeah, I'm not disputing that either. You need a external/embedded proof of some kind for the thing to be a verifiable credential.

I would be a +1 for the first proposal directly above this comment (initially proposed by @OR13 and then refined outlined by @andresuribe87), with the caveat that the name of the media type is vc+ld+json (where the bikeshedding thereof doesn't need to hold up the decision).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@msporny I'm not arguing you can't have different media types for the same bytes.... I am arguing against registered multiple media types for the same bytes with indistinguishable definitions in our spec.

+1 to vc+ld+json

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am arguing against registered multiple media types for the same bytes with indistinguishable definitions in our spec.

The first question should be whether there's value in having the second media type, whether or not it is a supertype of the type we're primarily focused on. If there is such value (as I believe there is), then if it is a supertype (as I believe it is), I think we should register both, or only the supertype. (If it were a subtype, we might not register it, but there would be good reason to speak of it and to suggest a media type for it.)

Remember that media types are not actively restrictive nor actively prescriptive in most applications, but are primarily hints about how to process the bytes within the resource labeled with that media type. In the world of the web, they're helpful for various tools to make known to a web server what form of resource those tools prefer such that the server can provide that, if available. (See RFC2295, among others.) It's perfectly valid for my super app to process resources of every media type in exactly the same way, if users of my super app find value in what my app outputs based on those inputs.

Copy link
Contributor

@OR13 OR13 Mar 3, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@TallTed does this 3rd proposal capture your alternate single registration proposal? :

PROPOSAL: The 1 media type for credential proposal, the working group will register credential+ld+json and the working group will not register verifiable+credential+ld+json.

This is also the case if the term is abbreviated, such as in `vc+ld+json`.
mprorock marked this conversation as resolved.
Show resolved Hide resolved
Use of media type identified as `verifiable` in this way MUST correspond with use
of one or more proofs with the credential.
mprorock marked this conversation as resolved.
Show resolved Hide resolved
</p>
<p>
Use of the term `credential` in a media type related to a syntax of verifiable
credentials without the corresponding use of `verifiable` as noted above does not
imply the presence of a proof with the <a href="#dfn-credential">credential</a>.
mprorock marked this conversation as resolved.
Show resolved Hide resolved
</p>
<p>
At the time of this writing, there are two media types associated with the core data
model: `application/credential+ld+json` and `application/verifiable+credential+ld+json`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Notably, we haven't actually defined the latter one yet, but this is just an informative thing that can be changed as needed.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

exactly - especially given the discussion on #1034 re verifiable-credential vs verifiable+credential this gives us a good way to get aligned

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@msporny has requested to use vc+ld+json elsewhere, which I agree with, but we can leave it like this for now I think.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
model: `application/credential+ld+json` and `application/verifiable+credential+ld+json`.
model: `application/credential+ld+json` .

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I support this change.

Other specifications such as [[VC-JWT]] define additional media types as may be
required to allow for proper interpertation of the syntax of verifiable credentials
mprorock marked this conversation as resolved.
Show resolved Hide resolved
encoded in the respective syntax described by the specification.
mprorock marked this conversation as resolved.
Show resolved Hide resolved
</p>
</section>

<section>
<h3>Proof Formats</h3>
Expand Down