Comments (13)
@tsabolov you'll not name
and description
are missing from the documentation you linked to, despite being available (and being protected terms) throughout a Verifiable Credential. That may be a limitation of https://github.com/w3c/yml2vocab which generates that documentation.
@iherman is there a way to "transclude" term definitions from other vocabularies into vocabulary documentation generated by yml2vocab? It's tripped me up before that I'm unable to find all the available terms in this yml2vocab generated content: https://github.com/w3c/yml2vocab
I realize the terms are technically from a different vocabulary than the one being defined there, but given their combined expression in the @context
and their intended use together, it'd be helpful to somehow see them together.
@tsabolov I'd hold off on creating new terminology just for documentation purposes. It's unwise to create "idioms" when there are serviceable global terms available. But we certainly need to make that clearer in the documentation somehow...
from vc-data-model.
Is this behavior intended to enforce strict term protection, or was this an oversight that should allow for redefinition of such terms in extended contexts?
It was a conscious design decision to ensure that the term wouldn't be redefined. You are attempting to re-define the term in your context, which is not allowed (because it would cause confusion with every one else that uses "name" and "description" in VCs to mean something else).
You should be able to just re-use "name" and "description" from the base context without issue. Is there any reason you cannot do this? It seems like your extension doesn't require "name" or "description" to be re-defined.
from vc-data-model.
Thank you for the clarification, Manu. That makes perfect sense. The idea is to have a hosted HTML page where all properties are described, similar to how it is done for VerifiableCredential. For name
and description
, we'd like to have our own documentation to ensure it is more precise for our use case.
from vc-data-model.
@iherman is there a way to "transclude" term definitions from other vocabularies into vocabulary documentation generated by yml2vocab? It's tripped me up before that I'm unable to find all the available terms in this yml2vocab generated content: https://github.com/w3c/yml2vocab
At this moment there isn't. But the two examples in this thread also show why this is not an easy thing to do: these terms are, in fact, schema.org terms that we just re-use in the context! I do not think taking over the schema.org documentation into our document is a good idea 😉
I think what we would need is a different tool, some sort of documentation of the context as opposed to the vocabulary. The context file does a good job in hiding the real URL of a term, but that sometimes stands in the way of understanding things. Ideally, I would imagine a visual tool that takes a JSON-LD term and visually shows the URL (and possibly other characteristics) it maps to. It reminds me of the standard code visualizer in the browser's developer panel, where you can move your cursor to an element in the source, and it will reveal, among other things, the relevant CSS statements for that particular element...
But that is a very different project...
from vc-data-model.
Thank you all for the comments. I just played around with the snippet and realized that there are two pairs of name
and description
. The first pair is at the root level of the VC2.0 context (here) and the other two are within the context of VerifiableCredential
(here and here). The former pair should undoubtedly be protected as they represent the name and description of the entire document. Although the latter pair seems to be more flexible, right? I honestly do not have much experience with JSON-LD, and genuinely couldn't understand why I can redefine e.g. issuer
and proof
but couldn't name
and description
. Please bear with me.
P.S. If you say that it doesn't make much sense to redefine name and description, then okay, I can live with that 😄
from vc-data-model.
FWIW, the entire Verifiable Credential context contents are protected. The lines you referenced are additionally protecting terms used on any document using that context file which also set type
equal to VerifiableCredential
(hence the sub-context used there...with it's own @protected
).
That said, I think what you're looking documentation-wise may be more easily found in the JSON Schema in this repo:
https://github.com/w3c/vc-data-model/blob/main/schema/verifiable-credential/verifiable-credential-schema.json
Here's a handy view of it for easier human parsing. 😃
https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2Fw3c%2Fvc-data-model%2Fmain%2Fschema%2Fverifiable-credential%2Fverifiable-credential-schema.json
Hopefully that helps a bit!
🎩
from vc-data-model.
The issue was discussed in a meeting on 2024-06-12
- no resolutions were taken
View the transcript
3.6. Could not define "name" and "description" as attributes of my type (issue vc-data-model#1500)
See github issue vc-data-model#1500.
Brent Zundel: beautiful! Issue 1500 - "Could not define "name" and "description" as attributes of my type" - question raised by an implementer. may not be a member of our group or even the W3C.
… I believe their question is pretty much answered. this issue is not calling for any changes to the spec. if that read is not correct please correct me.
Ivan Herman: You are not wrong. He did respond but is not happy with our answer. There is a feature in the LD context that has been used extensively. It does not let you define your own term where it has been defined in the document (protected). He wants to make his own spec, and is unhappy he cannot do that.
… the terms in question, however, are not terms that we have defined, but have been defined by schema.org. It is not very wise to re-define these terms anyway. I am not sure what we can answer. Maybe Benjamin has a better answer.
Benjamin Young: yes, this is a common misconception. vocab vs context. what he wants is documentation on what is in our context file. what he is referencing is the new vocab terms unique to the v2 data model--which are not all the terms in the context file. he wants a more complete set of data points around what these fields are.
… this is really what is already in the VCDM spec, but not a handy/quick reference, like what is in the v2 vocab documentation.
… he would have to do this in a different way instead of re-creating terms, which is what he was doing. a bit of a heavy-handed change. it is a common misunderstanding about vocab documentation.
Ivan Herman: we have a more general problem - which is not our problem - but the JSON-LD people - we have no way of properly documenting LD contexts. good documentation here would be very useful. this is not up to this working group to deal with.
Brent Zundel: I am not hearing anyone say we have to change anything here. also not hearing the opener of the issue can walk away satisfied. what can we do?
Benjamin Young: happy to follow up with the issue. I agree there is missing documentation in a 'cheat-sheet' style. the VCDMv2 is kind of that documentation, but not quickly digestible. what can I/not do with it?
… it is a tool that has been attempted by many companies. Spruce has one, YAML to Vocab almost has one (others too). There is not anything actionable for this group to do relative to the data model.
Brent Zundel: thank you and thanks for volunteering.
Dmitri Zagidulin: if the poster's aim is documentation, could we point him to the VC 2.0 JSON Schema? each term has documentation there.
Ivan Herman: yes, great idea.
Brent Zundel: See JSON Schema for VCDM.
Brent Zundel: yes it does exist. not sure if it is the answer but let's suggest it.
… any other comments before we close?
… we have nearly completed all open issues on the data model. we will be in a position where we are ready to go to PR modulo the test suites reporting that there are independent impls of each feature. expect in the coming weeks less focus on the core data model. more focus on controller doc, the only in-flight-spec not yet in CR.
… expect us to talk more about test suites, and impl feedback. at TPAC hoping to move all into PR, or a 2nd CR phase if needed.
… pleasure working with you all - thank you!
from vc-data-model.
That said, I think what you're looking documentation-wise may be more easily found in the JSON Schema in this repo:
https://github.com/w3c/vc-data-model/blob/main/schema/verifiable-credential/verifiable-credential-schema.jsonHere's a handy view of it for easier human parsing. 😃
https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2Fw3c%2Fvc-data-model%2Fmain%2Fschema%2Fverifiable-credential%2Fverifiable-credential-schema.jsonHopefully that helps a bit!
🎩
Neither of those links have any mention of terms discussed - name and description.
from vc-data-model.
I believe there are two issues.
- (Re-)definition of the "name" and "description" terms. @tsabolov said: "P.S. If you say that it doesn't make much sense to redefine name and description, then okay, I can live with that 😄" Yes, personally I do say that. Beyond the "protected" feature used by the VC
@context
, which is largely motivated by security issues, these specific terms are used and defined by schema.org, which has become probably the most widely used vocabulary around. Messing with the formal specification of those is a source of problems in my view. It is of course perfectly fine if in your application's documentation you make some restrictions on the usage of, say, "name" (e.g., you decide to use family names only), but that is not a formal redefinition. - Understanding
@context
files. The discussion highlighted a (in my view, generic) problem with JSON-LD contexts, namely that it is sometimes difficult for humans to understand what happens, what restrictions they impose, what formal vocabularies are used for each term, etc. I would love to see better tools for that purpose, and I hope it is the subject of some good R&D project out there. Personally, when I get messed up, I use the JSON-LD playground, see, e.g., small example, but I definitely do not claim it is an ideal solution.
I hope this helps...
from vc-data-model.
I also noticed this prevents from using https://schema.org as a context value.
from vc-data-model.
The issue was discussed in a meeting on 2024-06-19
- no resolutions were taken
View the transcript
2.3. Could not define "name" and "description" as attributes of my type (issue vc-data-model#1500)
See github issue vc-data-model#1500.
Brent Zundel: Next is 1500. It was a question, last time we talked, we settled on that the question has been answered.
… Not sure what to do with this issue.
… Feels like it would be premature to close it.
… Return to it next week.
from vc-data-model.
Related Issues (20)
- Do we need sha3-512 in the vocabulary tables? HOT 6
- Should we use `Ed25519Signature2020` in the Examples? HOT 4
- Unmatched HTML Tag HOT 3
- Revisit Verifiable Credential media types HOT 21
- consider merging 3.4 and 5.1 as both sections are about the credential lifecycle. HOT 1
- Add issuee definition HOT 18
- Truth (or falsity) is not part of VCDM ecosystem HOT 4
- `credential repository` vs `repository`, and definitions in _1.2 Ecosystem Overview_ vs _2. Terminology_ HOT 6
- Consider explicitly allowing/recommending language maps for use in internationalisation. HOT 9
- Example of Use of renderMethod HOT 3
- Suggest to make explicit reference to the JADES standard HOT 8
- EnvelopedVerifiablePresentation missing in https://www.w3.org/ns/credentials/v2 HOT 3
- VC-JWT examples are out-of-date HOT 6
- Inconsistency between spec and schema HOT 2
- Unify cryptographic hash expression formats HOT 4
- Comments/Suggestions on Privacy Considerations HOT 7
- SD-JWT fields in the v2 context should use `"@type": "@json"` HOT 4
- Ensure reserved terms are in v2 context HOT 2
- Add Security Considerations related to advances in Artificial Intelligence HOT 4
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from vc-data-model.