Could not define "name" and "description" as attributes of my type about vc-data-model

[BigBlueHat]

@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...

[msporny]

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.

[tsabolov]

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.

[iherman]

@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...

[tsabolov]

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 😄

[BigBlueHat]

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!
🎩

[iherman]

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!

[Fak3]

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!
🎩

Neither of those links have any mention of terms discussed - name and description.

[iherman]

I believe there are two issues.

1. (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.
2. 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...

[PatStLouis]

I also noticed this prevents from using https://schema.org as a context value.

[iherman]

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.