-
Notifications
You must be signed in to change notification settings - Fork 106
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.
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
Editorial fixes to media types section. #1062
Conversation
index.html
Outdated
interpretation of the syntax of verifiable credentials encoded in the syntax | ||
described by the respective specification. | ||
There is one media type associated with the core data model: | ||
`application/credential+ld+json`. Other specifications, such as [[?VC-JWT]], |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
`application/credential+ld+json`. Other specifications, such as [[?VC-JWT]], | |
`application/credential+ld+json`. Other specifications, such as [[VC-JWT]], |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
makes sense to me.
The issue was discussed in a meeting on 2023-03-08
View the transcript2.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. |
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
change the media type to vc+ld+json
Agree with the comment from @Sakurann on the call, the PR should be revised to address the resolution on the call today. |
index.html
Outdated
Use of the term "credential" in a media type related to a syntax of | ||
<a>verifiable credentials</a> <em>without</em> the corresponding use of | ||
"verifiable" as described above <em>does not</em> imply the presence of a | ||
proof with the <a>credential</a>. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I opened #1065 to track this issue.
The issue was discussed in a meeting on 2023-03-14
View the transcript2.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.
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. 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. 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.
Brent Zundel: Thanks kristina, thanks everyone, pleasure working with you all, see you all tomorrow!. |
Editorial, changes requested and made, issues raised, no objections, merging. |
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