Refactor WG inputs and outputs to follow (approved) WebApps Charter style #77
Conversation
msporny
requested review from
mprorock,
iherman,
brentzundel,
kdenhartog,
OR13,
Sakurann and
tplooker
|
I am bit bothered by the new title for 2.2. It could be read as if this WG developed CCG or IETF. recommandations... |
It's the same language that the WebApps group uses. I don't have a strong opinion and was just trying to follow WebApps model as @kdenhartog had requested. I'll try to think of alternate wording that will make it clear that those are potential future inputs from CCG and IETF that may become W3C Recommendations. |
index.html
Outdated
| <p class="milestone"><b>Expected completion:</b> <span class=todo>WG-START+24 months</span></p> | ||
| </dd> | ||
| </dl> | ||
|
|
||
| </section> | ||
|
|
||
| <section id="normative"> | ||
| <h3> | ||
| CCG and IETF Specifications |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
Agree with moving to this structure and will put forth |
|
@kdenhartog wrote:
I thought about doing that in this PR as well, but then was concerned that people might use that as a reason to object to this PR. I'd rather do another round in a PR that builds on top of this one. For example, VPR and VC API should probably be in that list of "things we might want to move to REC if CCG finishes with it"... but then I was concerned that people would object to the PR on those grounds... so I tried to only cover things that people already have in as PRs... and then try to see how far we can take this new structure in a future PR (if/once this one is merged). |
Yup that's what I figured as well so waas going to do in a separate PR that builds on this instead. A small focused PR should be able to get us to hone in on this a bit better |
index.html
Outdated
| verifiable credentials using a number of concrete serializations for each of the | ||
| defined syntaxes. The specific set of concrete serializations included will be | ||
| determined by the Working Group. The following are a non-exhaustive selection | ||
| of expected input documents: |
There was a problem hiding this comment.
I would like to make it clearer what constitutes an input document. What do we do with them? If we are to define how containers/cryptosuites defined in those documents can be used with vc-data-model, I would want these input documents to be "published standards", and I think language below would be clearer:
| of expected input documents: | |
| of expected input documents that are published standards: |
There was a problem hiding this comment.
In W3C, an "input document" is something that isn't a published standard yet. It's just a place from which the WG can start work, and is typically a document that has been incubated in a group that has an IPR policy that is compatible with W3C (such as a W3C community group or IETF group and/or Independent Draft).
There was a problem hiding this comment.
Thank you for clarifying - is there a W3C glossary somewhere?
There was a problem hiding this comment.
Thank you for clarifying - is there a W3C glossary somewhere?
Unfortunately, the initial W3C glossary work, and subsequent glossary work was abandoned in 2010.
Since this is charter stuff, the best reference is the W3C Process document. Even that barely mentions "input" in the sense that it's being used here (mostly because the term only comes up at chartering time and the question only exists for a very brief period of a few weeks before people stop talking about "input documents").
Hope that helps.
| <a href="https://github.com/w3c-ccg/lds-jws2020/">JSON Web Signature</a>, | ||
| <a href="https://w3c-ccg.github.io/lds-ed25519-2020/">EdDSA</a>, | ||
| <a href="https://w3c-ccg.github.io/di-ecdsa-secpr1-2019/">NIST ECDSA</a>, | ||
| <a href="https://w3c-ccg.github.io/lds-ecdsa-secp256k1-2019/">Koblitz ECDSA</a> |
There was a problem hiding this comment.
related to my comment above on input document being published/stable standards, I suggest to move all community drafts from this section to the section below on "produce W3C Recommendations for the following documents"
There was a problem hiding this comment.
reflecting a bit more, I think if we were to add another W3C recommendation in this group, we would need to recharter, and I don't think we want to open another pandora box of producing unpredictable number of additional recommendations. So if this WG wants to take over from CCG and work on data integrity 1.0, we would want to state so explicitly, instead of saying we would potentially turn a CCG draft into a recommendation.
There was a problem hiding this comment.
I would suggesting moving this comment to an issue, and accepting this PR as is.
There was a problem hiding this comment.
Note the comment about what an "input document" at W3C means: https://github.com/w3c/vc-wg-charter/pull/77/files#r812415276
There was a problem hiding this comment.
Input document can be a standard that is published by another standards body that has been accepted by the W3C.
There was a problem hiding this comment.
IMO, we should avoid trying to do too much in 1 PR... it makes the comments and intention of the PR unreadable. This PR is about matching the web app sec wg style, suggested changes to input items should be moved to issues, so we don't forget to address them when merging a PR that does restructuring.
There was a problem hiding this comment.
ok, I opened an issue #88 to discuss input document content.
| </tr> | ||
| <tr> | ||
| <td> | ||
| <a href="https://w3c-ccg.github.io/ldp-bbs2020/">BBS+ Cryptosuite</a> |
There was a problem hiding this comment.
I think for BBS+, we are not potentially producing W3C recommendation, but using it as an input document once it is published in IETF, so suggest to move it to a section above with a caveat (once it is publised in IETF)
There was a problem hiding this comment.
I would suggesting moving this comment to an issue, and accepting this PR as is.
There was a problem hiding this comment.
I think there is confusion over what an "input document" is. An W3C input document is never an IETF RFC. An input document is some incubated specification that is intended to become a W3C Recommendation. In that sense, our input document for the BBS+ Cryptosuite is expected to be https://w3c-ccg.github.io/ldp-bbs2020/, since we have no other input document to point to at present.
There was a problem hiding this comment.
than VC-JWT (already a W3C recommendation) cannot be an input document. How is VC-JWT and JWS (IETF RFC) should be referred to if not as an "input document" in a W3C sense?
There was a problem hiding this comment.
than VC-JWT (already a W3C recommendation) cannot be an input document. How is VC-JWT and JWS (IETF RFC) should be referred to if not as an "input document" in a W3C sense?
Yes, this is true that the term "input document" might not fit. One could argue that this is the VC 2.0 WG, and we are taking VC 1.0 work as input... I'll admit that's a bit of a weak argument, but is the reasoning behind the current category. We could move it further up in the document and call it out specifically as "in scope refinements", but it might stick out more than we want it to if we do so.
VC-JWT is a bit of an odd duck in that we defined it in the core spec in the VC 1.0 WG, and we should probably make it a stand-alone REC in the VC 2.0 WG. Ultimately, it probably doesn't matter -- it's a detail that most reading the charter will fail to grasp, and the VCWG will do whatever we have consensus to do, which could be one of: 1) leave it in the VCDM spec, 2) break it out into it's own standalone spec that can evolve at its own pace, 3) something else that gets consensus in the WG.
I think the reason we're listing it specifically is that we're trying to call out that people really want to work on and refine the VC-JWT encoding. By default, anything in the VC 1.0 spec is up for discussion/debate/refinement in the VC 2.0 work... so, we could not mention VC-JWT at all and still be fine. However, people wanted to very specifically call it out as something that they were expecting to work on, which is why it shows up in this list.
There was a problem hiding this comment.
I may be missing the point on what needs to be referenced here but the underlying cryptographic algorithm definition for BBS in the form of an IETF draft (currently incubated at DIF) is available here, the intent is to propose this as a work item to the CFRG. However I do agree with manu that, there still needs to be another document that defines the proof suite in the context of a framework like linked data integrity also e.g (https://w3c-ccg.github.io/ldp-bbs2020/)
There was a problem hiding this comment.
Apologies a more accurate link to the actual hosted spec is https://identity.foundation/bbs-signature/draft-bbs-signatures.html
There was a problem hiding this comment.
I may be missing the point on what needs to be referenced here
The document that needs to be referenced is the document that will be the basis of the W3C VCWG specification (the "input document to the VCWG"). This document: https://identity.foundation/bbs-signature/draft-bbs-signatures.html will be headed to IETF, thus is definitely not the document we should reference. Instead, it would be good for https://w3c-ccg.github.io/ldp-bbs2020/ to reference https://identity.foundation/bbs-signature/draft-bbs-signatures.html.
index.html
Outdated
| <p class="milestone"><b>Expected completion:</b> <span class=todo>WG-START+24 months</span></p> | ||
| </dd> | ||
| </dl> | ||
|
|
||
| </section> | ||
|
|
||
| <section id="normative"> | ||
| <h3> | ||
| CCG and IETF Specifications |
There was a problem hiding this comment.
I am concerned of putting CCG and IETF at the same level. One is a community group that does not produce binding standards with in W3C and the other is the entire SDO that mainly produces binding standards.
also, it does not make sense to be to "produce W3C Recommendations" of the IETF drafts.
Instead of having a separate section CCG and IETF Specifications, I suggest we just simplify data integrity 1.0 deliverable description and classify input documents into three categories: those that are already published, those being worked on in another SDO like IETF and those that maybe worked on in this WG to produce W3C Recommendations (like data integrity).
those three categories might make the scope charter clearer than layering - we could clarify layer of each input document separately, like JWP (container).
There was a problem hiding this comment.
I agree in principle, however I think the fastest path to where we need to be is merging PRs a bit quicker and opening a PR if you have changes you want to see, and less requesting other folks implement your changes in walls of text.
There was a problem hiding this comment.
classify input documents into three categories
Ah, I think I see where the miscommunication is happening. Let me try and do the mapping based on what you wrote:
- those that are already published - these are "normative documents that will be referenced from a W3C Recommendation track document".
- those being worked on in another SDO like IETF - these are "normative documents that will be referenced from a W3C Recommendation track document once they become RFCs".
- those that maybe worked on in this WG to produce W3C Recommendations (like data integrity) - these are "input documents"
@Sakurann, does that help clarify where the miscommunication is happening?
There was a problem hiding this comment.
In my view, the last thing we need at this point is sweeping rewrites of major blocks of charter text. Trying to get working group agreement on things that are wholly rewritten will likely set us back by weeks and possibly months.
I would request that you break this up into bite-sized chunks, with each chunk making exactly one simple, easily reviewable improvement to the charter text. Many simple PRs to review will give us a much more straightforward path to progress that proposing wholesale changes.
If you want an example of what I mean, PR #70 added one bullet item, immediately achieved working group consensus because it clearly improved on what was there, and was merged on the next call. Please aim for that kind of simplicity in your PRs to replace this one. Thank you.
| <a href="https://w3c-ccg.github.io/lds-ecdsa-secp256k1-2019/">Secp256k1 Cryptosuite</a>, | ||
| <a href="https://w3c-ccg.github.io/ldp-bbs2020/">BBS+ Cryptosuite</a>, | ||
| <a href="https://github.com/w3c-ccg/lds-jws2020/">JSON Web Signature 2020</a> | ||
| <a href="https://w3c-ccg.github.io/data-integrity-spec/">Data Integrity</a> |
There was a problem hiding this comment.
@OR13, this PR introduces a new section that matches the way the WebApps WG structured their charter (which has been repeatedly approved by W3C AC):
https://www.w3.org/2019/05/webapps-charter.html#deliverables
Their charter lists two classes of deliverables:
- Normative deliverables that they definitely plan to deliver.
- Deliverables that they intend to become normative IF the incubation group / external dependency is done on a reasonable timeframe.
For our charter, the VC-JWP stuff falls into the second category, and is why it's listed down there instead of here. If we put it in this list, we're saying we intend to take something normative that has no finalized spec at IETF to build upon.
For that reason, I can't take this change request. Can you either 1) retract it, or 2) provide justification for putting VC-JWP in "we're definitely going to do this" normative scope when the IETF work hasn't been completed?
| </tr> | ||
| <tr> | ||
| <td> | ||
| <a href="https://w3c-ccg.github.io/ldp-bbs2020/">BBS+ Cryptosuite</a> |
There was a problem hiding this comment.
I think there is confusion over what an "input document" is. An W3C input document is never an IETF RFC. An input document is some incubated specification that is intended to become a W3C Recommendation. In that sense, our input document for the BBS+ Cryptosuite is expected to be https://w3c-ccg.github.io/ldp-bbs2020/, since we have no other input document to point to at present.
index.html
Outdated
| <p class="milestone"><b>Expected completion:</b> <span class=todo>WG-START+24 months</span></p> | ||
| </dd> | ||
| </dl> | ||
|
|
||
| </section> | ||
|
|
||
| <section id="normative"> | ||
| <h3> | ||
| CCG and IETF Specifications |
There was a problem hiding this comment.
classify input documents into three categories
Ah, I think I see where the miscommunication is happening. Let me try and do the mapping based on what you wrote:
- those that are already published - these are "normative documents that will be referenced from a W3C Recommendation track document".
- those being worked on in another SDO like IETF - these are "normative documents that will be referenced from a W3C Recommendation track document once they become RFCs".
- those that maybe worked on in this WG to produce W3C Recommendations (like data integrity) - these are "input documents"
@Sakurann, does that help clarify where the miscommunication is happening?
| <a href="https://github.com/w3c-ccg/lds-jws2020/">JSON Web Signature</a>, | ||
| <a href="https://w3c-ccg.github.io/lds-ed25519-2020/">EdDSA</a>, | ||
| <a href="https://w3c-ccg.github.io/di-ecdsa-secpr1-2019/">NIST ECDSA</a>, | ||
| <a href="https://w3c-ccg.github.io/lds-ecdsa-secp256k1-2019/">Koblitz ECDSA</a> |
There was a problem hiding this comment.
Note the comment about what an "input document" at W3C means: https://github.com/w3c/vc-wg-charter/pull/77/files#r812415276
index.html
Outdated
| <a href="https://w3c-ccg.github.io/data-integrity-spec/">Data Integrity</a> | ||
| </p> | ||
| <p class="input-documents"><b>Cryptosuites:</b> | ||
| <a href="https://github.com/w3c-ccg/lds-jws2020/">JSON Web Signature</a>, |
There was a problem hiding this comment.
please change the name of the document to Linked Data Signatures for JWS, calling it JSON Web Signature is misleading.
There was a problem hiding this comment.
Linked Data Signatures
The new moniker for that work is "Data Integrity" of which "Data Integrity Proofs" and "Data Integrity Signatures" can also be used to be more precise.
The change to "Data Integrity" was made to ensure that people understood that the specification isn't purely about "Linked Data". You can do Json Canonicalization Scheme on input data and sign via JWS -- which has nothing to do with Linked Data.
Ultimately, this is @OR13's call since he's the lead Editor of that spec. We can always make this change in a future PR.
There was a problem hiding this comment.
Don't attempt to change the names of input documents, while attempting the reorg the section... I am holding off making any PRs until this is merged, happy to fix the labels after we get a better structure, but the current work item title it correct.
There was a problem hiding this comment.
actually its called JSON Web Signature 2020 I will suggest that change.
|
The issue was discussed in a meeting on 2022-02-23
View the transcript4.6. Refactor WG inputs and outputs to follow (approved) WebApps Charter style (pr vc-wg-charter#77)See github pull request vc-wg-charter#77. Brent Zundel: normally we would move to the next topic, but we are actually merging PRs. Manu Sporny: let me explain where this PR is coming from. Kristina Yasuda: I understand the logic. Manu Sporny: excellent questions..... Oliver Terbu: can we say its not the intention of the group to produce an exhaustive list?. Brent Zundel: we are intending for it to be non exhaustive list of input documents. Oliver Terbu: is it the intention of the final specification to be an exhaustive list?.
Oliver Terbu: in other words, can we keep using other suites that are not listed. Brent Zundel: the charter does not disallow that.
Kristina Yasuda: confused regarding CG Drafts and their ability to seek standards track. Ted Thibodeau Jr.: CGs produce reports... those reports look like specs, but they are not, thats why they take them to WGs.
|
Co-authored-by: Kristina <[email protected]>
msporny
force-pushed
the
msporny-refactor-inputs
branch
from
4d68c64
to
f937003
Compare
|
This PR has been rebased on top of all of the merges we did this week during the WG call. It's ready to be merged during the call next week if we have no objections. |
Co-authored-by: Orie Steele <[email protected]>
| <p class="milestone"><b>Expected completion:</b> <span class=todo>WG-START+24 months</span></p> | ||
| </dd> | ||
| </dl> | ||
|
|
||
| </section> | ||
|
|
||
| <section id="normative"> | ||
| <h3> | ||
| Conditional Normative Specifications |
There was a problem hiding this comment.
We would need to define how these non-W3C document will be used with data-integrity, they on its own do not do that:
| Conditional Normative Specifications | |
| Conditional Normative Features |
There was a problem hiding this comment.
VC-JWP isn't a feature, it's a full blown specification. The same could be argued for the other two cryptosuites. Cryptosuites being an extension mechanism and thus typically contained in a separate specification. I can see how we could view these as "Features", but I'm concerned that by doing so, some might argue that they need to be shoved into "existing specifications" or "they don't fit into any of the specifications we're working on". Given that it's the right of the WG to format all of their specifications (combine/split) in whatever way we feel is necessary, I'd rather call these "specifications" to give us maximum flexibility to decide what to do with them in the WG.
For that reason, I'm a -1 on applying this change request.
Co-authored-by: Kristina <[email protected]>
|
Both chairs have approved this PR, other changes have been requested and made. Other approvals are in place. |
Blerg, looks like this was squash-merged, which makes it difficult to fix the conflicts elsewhere... When merging, please follow this general practice:
^^^ Those rules are good rules to follow for any Github repository and can be applied to most (if not all) Github repositories. What happened here was:
Just trying to document what happened so we can avoid it happening in the future. I'm working on it now. |
This PR builds on PR #76, #73, #66, #63, #51, and #50 and refactors them in a way that other WGs have found success wrt. charter approval. It also addresses @Sakurann's request to categorize the layering, and @selfissued's request to put the JWP work back in scope (if adequate progress has been made at IETF).
Preview | Diff