-
Notifications
You must be signed in to change notification settings - Fork 110
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
Add rendering property to VC Data Model #1035
Conversation
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.
Explanation talks about "visual, auditory, or haptic mechanism", but the text mainly defines "SvgRenderingTemplate2023" and the Algorithm.
I think we should with "visual mechanisms", but there is more needed "to include rich imagery of their corporate logo and specific placement of employee information in specific areas of the badge" than an SVG image - color for the background, color for the text, passing issuer logo via URL, etc.
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.
(( ))
would be double parentheses.
{{ }}
are double braces.
I am worried to get sidetracked into some complicated specificationndiscussion about templates like the SVG templates in the PR. Wouldn't it be better leave that open, or refer to some existing template languages like Mustache? |
I would pause, from a vocabulary point of view, on the usage of the
Can we simplify our life and use a different term here referring to simply some list (should I use the term 'registry'?) template categorizations? This is a pattern that we use elsewhere in our vocabularies which indeed bloats the formal part, so this may become a discussion on its own right in re-thinking the way we express things in general... |
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 am worried that this is not the right layer to add rendering concerns in. Would it open the door for similar rendering for a presentation, etc?
I'm not supportive or objecting just yet, just contemplating what the right place for this is. I think a separate rendering spec that can be layered in would make more sense.
</td> | ||
</tr> | ||
<tr> | ||
<td>digestMultibase</td> |
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.
... its ok, its non normative right?
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 understand the question. Are you saying "This is ok for now?" or are you asking "Is this a non-normative statement?" -- if so, no, it's a normative statement. Also note the issue marker (below) stating that this is a discussion to be had about the data format.
Please clarify what you're asking here so we can address your question.
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.
If we are going to define this, we better start with boring sha256 hashes like what you get from this:
curl https://raw.githubusercontent.com/Gowee/nyancat-svg/main/nyancat.svg --output some.file
openssl dgst -sha256 some.file
Huge -1 to starting with "digestMultibase".
@Sakurann wrote:
Yes, the text attempts to point out that visual expressions aren't the only ones that can be expressed using this mechanism. If we ONLY provide visual rendering, I expect the feature to fail Accessibility review because we are not providing for renderings that meet the needs of sight impaired individuals. This might mean that we need to also provide at least an audio-based rendering mechanism as well. The SVG rendering template is a concrete placeholder due to the WG's current desire to specify at least one example of a concrete implementation that uses the extension point. We /could/ replace this with an image and still meet that goal (though we'd lose the visual template functionality).
AFAIK, you can do all of the things you listed using an SVG image. That said, the template is a starting point. Improvements we could make include:
Based on the above, what concrete changes would you like to see to this PR, @Sakurann? |
Co-authored-by: Ted Thibodeau Jr <[email protected]>
@decentralgabe wrote:
What layer would be the right layer to capture how an issuer would like a credential to be rendered?
I don't think this is meant for presentations (at this point, anyway). I don't quite know how that would work for a holder to specify how they'd like something rendered (don't know if that makes sense to do?). Organizations that issue credentials tend to want some level of control over the look/feel of the credential. A sofware system can ignore
Yes, I agree that the |
Yes, it would be preferable to use Mustache. The PR started with that approach, but I couldn't figure out how to cite it normatively. What would be the W3C Process argument in favor of doing that? The only thing that I could think of is state the dependency on Mustache in a non-normative fashion and that didn't seem like it would go over well with the WG. |
The guiding principles are in https://www.w3.org/2013/09/normative-references. I do not know whether Mustache would satisfy the requirements, though. |
Hey @msporny, so with Blockcerts we've been dealing with rendering since the inception and we've got quite a complete solution which I believe could easily be replicated, but also leaves quite a lot of flexibility to the issuer in the way they want to render their certificate. At this moment we have support for HTML (SVG would work too), base64 images, base64 pdfs and I'm about to add support for base64 videos (granted, the HTML wrapper for rendering base64 is handled by our frontend component, but as I understand the proposal there would be similar logic involved). Obviously, and as discussed before, base64 comes with the downside of creating heavy certificates, but on the upside it does not rely on forever hosting nor internet to render (we do support hashlinks too to offer the counterpoint there (forever hosting but lightweight)). We don't do magic handlebar rendering, so the HTML is actually generated before issuance. To me that offers the benefit of having the rendering data cryptographically verifiable and not temperable. Anyhow, I wanted to attend RWOT to discuss this with you but couldn't get budget to do so. I'm not if I'm too late to the party, but I'd be happy to discuss with you the intricacies of our solution. |
I am a bit surprised that the only rendering template would be SVG. Nothing against SVG, of course, but using SVG for rendering textual information might be a challenge. SVG does not have the ability to automatically wrap text into a fixed area, which means that displaying textual information properly is always a problematic. This may make it difficult to use SVG as a template in practice. I would have expected to have an HTML template instead (or alongside) rather than SVG. |
Something else we're going to need here is security advice for doing the actual rendering, e.g., run it in a sandboxed container of some sort. This may also place restrictions on what the templates will be able to do that authors will need to understand. |
@msporny wrote:
So I tried to get a little bit deeper in understanding From what I can tell, rendering mode is decided by the user-agent (most likely a browser) and a developer has little control over changing it, and the only other browser solution is setting the I'm by no means an expert at CSP and only worked with it on the surface, but with modern websites that take scripts from CDNs and other third parties you can't have full trust that the rendering content cannot be used for targeted XSS. From limited testing, loading the SVG from an external file as What I'm getting at, is as soon as you are rendering HTML or SVG from an unknown source, you could have a malicious agent sneak in code, and I don't think a secure rendering mode totally alleviates the need for XSS filtering and/or other security measures, especially that secure rendering mode is not available for direct rendering of the SVG tag. With blockcerts we made the choice to sanitize the content before rendering it, and handling it at our component level so that consumers don't have to worry about it, and I don't think this should be seen as a red flag, because that would be in any case the right thing to do as a frontend engineer. |
Yes, that's the idea. The There are two parts to this PR:
One way to address item 2 is to say that there are multiple implementations of the
Yep, agreed that we need a mechanism to do this. On this, I believe we have consensus (so far, in this PR).
Hrm, don't understand this statement above, could you elaborate on it a bit more?
That presumes that Credential Manifest is the way we do things, and I expect objections on that front. All this to say, we can probably all agree that we need a |
There are two parts to this PR: One of the parts seems to have consensus: the establishment of the The other part does not have consensus: That Chairs (@Sakurann and @brentzundel), please schedule either VCWG call time or a special topic call to address @Sakurann's concerns. |
I think that having a straw man in the spec may be helpful, but we should not make it normative. It can also be put as an example in the appendix, for example. |
To be clear, I don't think this has consensus.... It feels like something for the "directory"... not the core data model. |
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.
Prefer to not add rendering to the core data model, seems it belongs in the "directory".
Could you provide the rationale you're using for determining whether you think something belongs in the core data model or the directory? |
@dlongley Everything we add to the core data model increases the complexity of the spec, the burden on implementers, the chances for bugs, security issuers, etc... We should in general avoid adding features to the core data model, especially if the code data mode is based on JSON-LD which supports decentralization through context and RDF type extensions. Features in the core data model should be implemented and relied on by the vast majority of Issuers, otherwise they would be better to be handled with an extension. What percentage of Here are some existing properties of that class to consider:
When implementing "the version 2 standard" an implementer will need to support all of these... or interoperability will be only on the properties that all implementers choose to support. I think many of these would be better addressed via extensions, so that the cost to implement the core data model is minimized, and that extensions can be used to indicate support for interoperability with optional features. |
The purpose of standardizing certain properties / features is so that there's just one way of doing things -- for those people that want to do those things. That doesn't mean everyone has to do every one of those things. It's just that, for any one of those things, if they want to implement, they should do it in a particular way.
A cost is paid in the ecosystem when there is a popular feature that is implemented many different ways. Adding a single way to do it in the core data model (or in another spec that the core spec references) mitigates that cost. Therefore, the idea that we should only put into the core data model the things that everyone in the ecosystem does (which we cannot know) I consider flawed. |
@dlongley Does this not accomplish the exact same goal: {
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2",
"https://example.com/svg/context/v1",
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential", "SvgCredential"],
"issuer": "https://example.edu/issuers/14",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"render": [{
"id": "https://example.edu/credentials/BachelorDegree.svg",
"type": "SvgRenderingTemplate2023",
"sha256": "ac996ae492f9a987c84f109f2118d3f6632e2259455d30c455a9ecd66c3c4959"
}]
} Why do we need to keep adding industry / domain specific credential metadata to the This working group does not need to add support for "render", it would be better to have it defined and experimented with in the
|
I understood your original argument to be (not directly quoting you below, just my understanding):
I disagreed with this (as seen above) and I believe you are now making a different argument that I understand to be:
Is this right? If so, I'm more amenable to the "it's early, let's let the market sort it out first" approach as a valid argument (vs. my view of your original argument, which I did not find compatible with the standards work we're doing here). However, I don't think I really agree ... since we're just potentially standardizing on a single property I'd rather not have to deal with writing code that has to search across N-many properties to find possible rendering information. This situation, to me, seems to be very similar to our decision to standardize |
I think you end up needing to do this anyway, given that Maybe this example makes that even clearer: {
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2",
"https://example.com/svg/context/v1",
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential", "RenderableCredential"], // note the word renderable
"issuer": "https://example.edu/issuers/14",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"render": [{
"id": "https://example.edu/credentials/BachelorDegree.svg",
"type": "SvgRenderingTemplate2023", // note the type agility
"sha256": "ac996ae492f9a987c84f109f2118d3f6632e2259455d30c455a9ecd66c3c4959"
}]
}
There might be formal objections if we do this, we saw similar complaints for Those are all places where we standardized a "predicate" that relied on "non standard" "types" to actually be useful, and it has been argued this harmed interoperability. I agree with those arguments. I think if we standardize a "predicate" we are also on the hook for at least one "type" to demonstrate its use... hence, we are not just standardizing "render"... we are also sorta-sneakily standardizing "SvgRenderingTemplate2023"... similar to how JsonSchemaValidator2018 was introduced in v1.1, it forced us to do a bunch of work on "types" outside of the WG, and with a very fragmented experience that produced poor interoperability. |
The issue was discussed in a meeting on 2023-03-08
View the transcript1.8. 'render' property.
Manu Sporny: question to the group - what do people think about the 'render' property for the core spec.
Manu Sporny: this is not a new work item, it's an extension point.
Manu Sporny: if you want this credential rendered, use this extension point.
Manu Sporny: to be clear, what we'd need to do in the group is just agree to an extension point called 'render'. and then the VC directory would list the various specs.
Manu Sporny: so, just looking for feedback.
See github pull request vc-data-model#1035. Dmitri Zagidulin: Wanted to say +1 to proposal for render extension point, Orie is right, PR to VC context, but also means adding a paragraphs/section to VC spec to say "render" is an extension point, for options go see the directory..
Dmitri Zagidulin: The render proposal was a paper in RWoT, with the proposal takes a look at existing prior art, Open Badges, DIF render, this mechanism adds support for expressing all those options. There was a session at IIW , packed room, on render, lots of interest from many parties. Question to the community, is there support for adding an extension point, then specifics in the directory.. Brent Zundel: from what I see in the chat, folks seem generally favorable, so I encourage to go to the PR.
Orie Steele: the DID Core Manu Sporny: to provide a counter-argument. the reason we define extension points in the spec, is to convey how people SHOULD extend.
Manu Sporny: the danger if we do not specify the property in the spec, is that market will fragment with many terms, renderFoo and renderBlah etc.
Brent Zundel: if you're an editor for one of our work items and want to provide an update, please jump on the queue, then we'll move to PRs. |
<ol class="algorithm"> | ||
<li> | ||
Generate a map, `replacementMap`, by finding all strings in `svgImage` that | ||
start with `{{` (double open braces) and end with `}}` |
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.
Instead of defining a one-off interpolation algorithm, perhaps it would make sense to define this algorithm in terms of svg/xml. e.g. replace <vc-select selection="{jsonpointer}" />
instead of {{jsonpointer}}
(or whatever it is)
I think this would have the nice property of making the SVGRenderingTemplate2023 still be valid svg? svg2 says unknown elements should render as <g />
({{syntax}}
may also be valid svg, but I imagine they'd render ugly)
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.
it might also scale to more complex types of replacements later (e.g. 'selections' with more complex types than just a jsonpointer
)
@OR13 i like that |
@gobengo in JSON-LD, we call "traits" "multiple inherence"...
This enables open world extensibility with semantic term definitions without needing to maintain all the terms in a "single registry" or in a "single specification" : ) |
this PR should be closed when PR #1108 is merged - ie this property is added to the reserved table |
The issue was discussed in a meeting on 2023-05-03
View the transcript3.1. Add rendering property to VC Data Model (pr vc-data-model#1035)See github pull request vc-data-model#1035. Brent Zundel: rendering property.
|
The issue was discussed in a meeting on 2023-05-17
View the transcript3.2. Add rendering property to VC Data Model (pr vc-data-model#1035)See github pull request vc-data-model#1035. Brent Zundel: similar questions here. Manu Sporny: This item did get into the reserve property table.
Manu Sporny: I think we can close this immediately (or after the call).
Manu Sporny: The plan here is that it is in the reserved properties table, there's a work item in CCG. maybe a future version of the group can add it, or after CR. Brent Zundel: alright. unless there's objection... |
I opened this PR, there were no objections to closing it on the call, so I'm closing it now. It lives on in the CCG work item on rendering methods. |
This PR addresses issue #928 by adding a
render
property to the VC Data Model. The feature is marked "at risk" in the spec. It attempts to specify a simple, but concrete solution using:{{VARIABLE}}
.I expect this feature to generate discussion, so we will need more than the 7 day window to discuss... I'll set it at 30 days and see if we can come to consensus by that point.
This PR is based off of work done at Rebooting the Web of Trust:
Preview | Diff