Usable JSON-LD Security Documentation #21
Comments
Yes, terrible, isn't it. :) It needs to be fixed, so am thankful to you for pushing the need to make this simpler.
+1
I'm fine with this policy. Keep in mind that this policy only works for the Javascript folks and no one else. I guess the hope is that other language developers will follow suit.
+1, also fine with this.
Yes, that is deliberate, and it shouldn't change (because it'll break lots of implementations and make everything more difficult).
Yeah, we should point w3id.org to this repo, which didn't exist at the time the redirection was put in. I think it was because Github didn't support HTTPS at the time for Github pages (and loading a security vocab from a non-HTTPS location was 1) a bad idea and 2) cause browsers loading via CORs to flip out). There were other Github limitations at the time (remember, that some of this work was pre-Github pages existing as a thing)... but now that those are not an issue, +1 to making the redirect point to the right place.
Yep, it should be fixed.
Err, no... we have a project with 10 years of history and a group of individuals that keep getting pulled into doing other things for the community resulting in certain projects languishing for longer than anyone wants. We didn't "use the features of Linked Data and Decentralized Extensibility to make an unusable documentation system" -- we are overworked and the community has prioritized things other than this until now. :)
+1, let's do this after checking to make sure it's not going to break some system that has been deployed into production. /cc @dlongley @davidlehn @mattcollier @dmitrizagidulin
It's not, it's a redirection URL. :)
The first thing you point to is a vocabulary prefix, the second thing you point to is a vocabulary term. Yes, you could turn your head and squint your eyes and you might also see something that could be construed as a registry. Just like a dictionary could be construed as a registry for words... but most people would just say "Dictionary", not "Registry for words".
It's not doing the same thing, even though it may seem like it is at first blush. I do think I understand where you're going with this, so I'm not going to argue against it (yet).
Yes, +1 to this.
No, strong -1 to this.
Yes, I think +1 to this... as long as we don't go overboard and centralize everything into the security context. For example, Bitcoin and Ethereum might need their own security contexts in time. We don't want to have to change the base context every time Bitcoin and Ethereum want to do their own special thing. We should make sure we do the layering correctly.
Err, there are many different types of "documentation for security concepts". So, you need to be more specific here. I expect that we'll end up agreeing, but you're being too loose and vague with your language for me to agree (because we're having a conversation about security, and the details matter).
w3id.org isn't actually defining the namespace. It's redirecting you to wherever the documentation and JSON-LD context lives today. Keep in mind that the security vocab and context that you're referring to has lived in at least 5 totally different domains over the past decade. If we had not used w3id.org, we would have been totally screwed every time we had to move it's home. The reason it'll be easy to migrate to this new repo now is because we have w3id.org in place and it becomes a simple PR to w3id.org.
That vocabulary is useful outside of JSON-LD. It's most likely going to be: https://www.w3.org/TR/ld-security/ or https://www.w3.org/2021/ld-security/
So, imagine that we made that decision during the DVCG days, and we would have splattered the https://w3c-DVCG.github.io/security-vocab/ URL all over the place, and would now have to update it everywhere, which we wouldn't... 'cause who has time to do all that? OR, we could just say, docs are here: https://w3id.org/security/ and context is here https://w3id.org/security/v2 ... and that's it. People are redirected to the proper site always without us having to go around and update everything all over again.
+1 to this.
Yes, and the purpose of w3id.org is to reduce duplication. |
|
Awesome, I agree regarding w3id.org, that makes sense. Also regarding the w3c security vocabulary you suggested:
+1 to this! Sounds like we have almost perfect alignment, I want to pull out the areas for further refinement:
I may need help understanding how best to relate these things. How should we support the concept of:
The thing I am having trouble with is the following: I want to add my signature suite to the security vocab and documentation. I extend the documentLoader, and trick it into using my modified security context, for testing integrations... this results in something like: This implies documentation available: https://w3id.org/security#SuperAwesomeSignature2020 Locally I write all the documentation for these, and I host them in a github repo, so that I get the following documentation URLs: https://example-company-org.github.io/lds-sas2020/#SuperAwesomeSignature2020 Notice now that I have documented everything, I need to open a PR to add my changes to the security-vocab... This is inherently a centralizing action. If we wanted to not have this requirement, we would need some way to add the context of my signature suite to the security vocab context, and then people would be directed through the security context to my domain, which I controlled... This feels like what you are wanting from:
We currently don't have any layering for security contexts. Everything is in https://w3id.org/security/v2 or you need to pretend like it is to use JSON-LD Signatures and VCs... I'd rather see a lot of people extending the security context with URIs, than with property definitions... It sounds like that is what you are wanting as well, however, this makes understanding vocabulary complex, now I have to navigate across many linked web pages, in order to understand all the security vocabulary... If I had to choose between a single centralized security context, or a bunch of linked web pages that are related to the concept of security, I would choose the former 1 million times over. In other words, I don't see the argument for separating security contexts, can you help me understand what you mean by "getting the layers right". What would the right layers look like if you could have it done tomorrow? |
|
This has been mostly fixed.. we should probably note the relationship between this registry and https://github.com/w3c-ccg/security-vocab I will raise a new issue to do so. |
w3c-ccg/lds-ed25519-2018#5
If the human readable and security context definitions are separated, I believe we will need to use code contribution policies to keep them in sync.
Currently we have 4 repos, related to the single concept of
Ed25519Signature2018...https://w3c-ccg.github.io/ld-cryptosuite-registry/#ed25519
https://w3c-ccg.github.io/lds-ed25519-2018/#the-ed25519-2018-signature-suite
https://w3c-ccg.github.io/security-vocab/#LinkedDataSignature2015
https://github.com/web-payments/web-payments.org/blob/master/contexts/security-v1.jsonld#L11
There must be some documentation in the security vocab module, even if its just a pointer to the crypto registry which points to the actual signature suite...
I think its very likely that this structure will continue to yield poor documentation, but making it explicit would undoubtably help.
I suggest we add some policy documentation around defining security vocab:
NPM Module -> Crypto Suite Registry -> Linked Data Signature Suite.
Every property in the security module that does not have a healthy documentation path should be filed as bugged.
Next, we have the issue of the use of w3id...
https://w3id.org/security ... this is used all over the place, including the DID WG...
https://github.com/w3c/did-core/blob/master/contexts/did-v0.11.jsonld#L9
The overlap between:
Is they both point to a set of definitions last updated in 2016, hosted in a WG which AFAIK is not active:
https://w3id.org/security
Becomes:
https://web-payments.org/vocabs/security
Because of:
https://github.com/perma-id/w3id.org/blob/242a8e547aaf33c9164a13b7061296b9c8ec20fa/security/.htaccess
and https://github.com/web-payments/web-payments.org/blob/master/contexts/security-v1.jsonld#L11
... This is pretty terrible.
We've used the features of Linked Data and Decentralized extensibility to make an unusable documentation system for linked data security.
We need convert this graph to a tree.
The root is clearly w3id.org...
It should work like this:
https://w3id.org/security -> https://w3c-ccg.github.io/security-vocab/
https://w3id.org/security/v1 -> https://w3c-ccg.github.io/security-vocab/contexts/security-v1.jsonld
... next is where i believe we disagree @msporny ...
I believe that https://w3id.org/security/v1... is a registry.... which means that security-vocab is a registry, and I submit as proof:
https://github.com/w3c-ccg/security-vocab/blob/master/contexts/security-v1.jsonld#L7
https://github.com/w3c-ccg/security-vocab/blob/master/contexts/security-v1.jsonld#L11
This repo (w3c-ccg/ld-cryptosuite-registry) is confusing, because it appears to be attempting to do the same thing as the security-vocab repo:
https://w3c-ccg.github.io/ld-cryptosuite-registry/#ed25519
Taking off my spec helper hat and putting on my developer hat, the thing I want to never see in security setting, is code duplication or multiple layers of indirection.
Web Payments needs to go away... w3id.org needs to go away...
The security context jsonld needs to exist in a single place, and there needs to be a single place which defines human readable documentation for security concepts.
I don't see the point in a separate registry repo, if w3id.org is what is actually defining the namespace for linked data security concepts...
At the end of this process we should have the following structure.
https://www.w3.org/TR/jsonld/security is the namespace for JSON-LD Security, until its fully a standard, it should point to a W3C WG repo, like: https://w3c-ccg.github.io/security-vocab/ ... if we MUST preserve w3id.org, I'd really like for it to make clear that the contexts and documentation associated with that namespace are hosted here: https://w3c-ccg.github.io/security-vocab/...
https://github.com/w3c-ccg/security-vocab hosts the jsonld context and human readable documentation for JSON-LD security.
I understand the utility of perma-id and redirection services here, but we should ensure that we are minimizing duplication wherever possible.
The text was updated successfully, but these errors were encountered: