Editorial fixes to media types section.

[msporny]

This PR is meant to be an editorial update to the media types section based on the call today. It is NOT meant to change the meaning of the section. Running this through a PR to make sure I didn't accidentally change some meaning somewhere.

---

Preview | Diff

[brentzundel]

I believe that since the plan is for VC-JWT to follow roughly the same recommendation-track timeframe as VC Data Model v2, we can probably keep the references to it as normative.

Suggested change

	`application/credential+ld+json`. Other specifications, such as [[?VC-JWT]],
	`application/credential+ld+json`. Other specifications, such as [[VC-JWT]],

[msporny]

I guess this is a question of Editorial style. What I prefer to do is make non-normative references to external specifications non-normative. That is, if you're just mentioning another specification in a non-normative way, the reference should be non-normative as well. I try to do this because as text is shuffled to-and-fro within the specification, you want the normative statements to be the ones that make a specification reference normative.

I expect that this is not done consistently in the vc-data-model spec at present (and I was going to do a pass right before CR to clean this up). So, I'd prefer to keep this reference non-normative as we have other references in the spec today, to VC-JWT, that are normative.

All that said, I'm wondering if we want any normative references to VC-JWT or VC-DATA-INTEGRITY. I would expect the WG to say "yes, we do"... but I wonder if that's what is best for the specification. The data model can technically, and debatably, stand on its own without dependence on any "securing" specification. The only place where this might not be true is the Proof Formats section, which some are arguing to remove from the specification.

In any case, just raising that as a consideration. I would prefer to not take this change, but wouldn't be averse if others felt like the reference should be normative (at which point, the editorial rule that we use wrt. normative vs. non-normative references would need to be consistently applied throughout the specification).

Currently, that rule is:

If you are referencing another specification in a normative statement, the reference should be normative. Otherwise, it should be informative.

If we take the change above, the rule would change to:

If you are referencing another specification that is referenced anywhere in the specification in a normative capacity, then the reference is always normative in any normative section, except for when you reference it in an informative section, where the reference is required to be informative (because if you don't do that, ReSpec will throw errors.

Note how the first rule is easier to reason about than the second rule (which is made awkward by ReSpec linting).

[OR13]

I don't think an implementer needs to understand vc-jwt to understand credential+ld+json or any *+ld+json.

I believe the reference should remain informative.

[brentzundel]

makes sense to me.

[iherman]

The issue was discussed in a meeting on 2023-03-08

• no resolutions were taken

View the transcript

2.3. Editorial fixes to media types section. (pr vc-data-model#1062)

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

Manu Sporny: I'm not going to go over old PRs, please take a look at them.
… latest one - 1062, just does editorial fixes to media types section.
… take a look at it, should be just editorial.
… moving quickly - VC Data Integrity - we're adding an algorithm for retrieving the verificationMethod.
… we'll need more people approving, but it seems to be - seems that people want to see this defined.

[OR13]

This PR is editorial, I prefer for it to be merged ASAP, since it blocks addressing several other open PRs that need to add text to this section.

[msporny]

This PR is editorial, I prefer for it to be merged ASAP, since it blocks addressing several other open PRs that need to add text to this section.

I'll merge as soon as @mprorock ok's it. I want to make sure I didn't accidentally butcher something he had in the previous revision.

[TallTed]

LGTM

[OR13]

change the media type to vc+ld+json

[OR13]

Agree with the comment from @Sakurann on the call, the PR should be revised to address the resolution on the call today.

[Sakurann]

I think we should apply the same philosophy to all media types related to this specification that media types describe a secured 'thing' and media type itself does not imply the proofing mechanism. given the base media type is application/vc+ld+json; all extensions of VCDM core spec should use vc+.

happy to file a separate issue, since I think this PR is meant to be editorial...

[msporny]

I opened #1065 to track this issue.

[iherman]

The issue was discussed in a meeting on 2023-03-14

• no resolutions were taken

View the transcript

2.6. Editorial fixes to media types section. (pr vc-data-model#1062)

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

Manu Sporny: This can be merged, I just haven't done it.

Orie Steele: +1 to merging, after the call.

Manu Sporny: I'm concerned that we may be talking past each other. Just to clarify, you mean change the media type to the new one.
… And then we're good to go?

Joe Andrieu: Yes, that's what I meant.

Manu Sporny: Kristina, are you talking about stop talking about "credentials" in the media types?

Kristina Yasuda: There's a sentence in there that needs clarification.

Manu Sporny: In the spec we make a clear distinction, conceptually between credentials and verifiable credentials.
… In theory, we're careful in the spec where we are careful with that — but sometimes we're using the wrong term in the spec.
… We need to go through the spec and clean that up and make it clear where we are talking about a credential vs. a verifiable credential.
… Other people are suggesting that we should stop talking about credentials entirely and we should only talk about verifiable credentials and that's where things get problematic.
… The other issue is that some people have taken issue with the definitions for the two terms and are calling it vague. And talking about those things in terms of securing mechanisms is a new thing in 2.0. There may need to be clarity in terminology definitions. I'm wary, until then, when people say "this should be a credential vs. a verifiable credential".
… I think we need to get to a point where people are happy with the definitions and distinctions and then clean it all up.

Orie Steele: Mostly agree w/ Manu — described the challenges in front of us... people are very confused by text in current spec, and we have to do better in some of the ways Manu said and further discussion on utility of word "credential" is in order. We should improve language around them that there is a meaningful distinction, if there is one, and I remain dubious about it.

Kristina Yasuda: I was reacting to text in PR, editorial PR, happy to open an issue... there is text that says "if you use crednetial vs. verifiable crednetial" — what each of them mean.
… Same philosophy applies to signed thing, we should be consistent, I'll make a comment to that effect.

Phillip Long: +1 kristina.

Brent Zundel: Thanks kristina, thanks everyone, pleasure working with you all, see you all tomorrow!.

---

[msporny]

Editorial, changes requested and made, issues raised, no objections, merging.