Skip to content
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.

Sign up for GitHub

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

Closed
wants to merge 5 commits into from
Closed

Add rendering property to VC Data Model #1035

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3d360b7
Add initial section on Rendering.
msporny Feb 13, 2023
17e07ef
Add SvgRenderingTemplate2023 data model and example.
msporny Feb 13, 2023
98beb6d
Add SvgRenderingTemplate2023 algorithm.
msporny Feb 13, 2023
e97f7fa
Add that rendering is a feature at risk.
msporny Feb 13, 2023
ee96f98
Fix parenthesis language to braces language.
msporny Feb 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 170 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,18 @@
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}
ol.algorithm {
counter-reset: numsection;
list-style-type: none;
}
ol.algorithm li {
margin: 0.5em 0;
}
ol.algorithm li:before {
font-weight: bold;
counter-increment: numsection;
content: counters(numsection, ".") ") ";
}
</style>
</head>
Expand Down Expand Up @@ -2645,6 +2657,164 @@ <h3>Refreshing</h3>

</section>

<section>
<h3>Rendering</h3>

<p class="issue" title="FEATURE AT RISK: Rendering">
The rendering feature might not be included in the final version 2.0
specification and is thus considered a feature at risk. It is unknown at this
time if there will be enough implementations for the feature. The Working
Group is seeking implementer feedback on whether or not they see this
feature as worth keeping in the final version 2.0 specification.
</p>

<p>
Rendering hints can be used when the <a>issuer</a> has a specific way that
they want to express a <a>verifiable credential</a> to an observer through
a visual, auditory, or haptic mechanism. For example, an <a>issuer</a> of an
employee badge credential might want to include rich imagery of their corporate
logo and specific placement of employee information in specific areas of the
badge. They might also want to provide an audio read out of the important
aspects of the badge for individuals that have accessibility needs related
to their eyesight.
</p>

<dl>
<dt><var>render</var></dt>
<dd>
The value of the <code>render</code> <a>property</a> MUST specify one or
more rendering hints that can be used by software to express the
<a>verifiable credential</a> using a visual, auditory, or haptic mechanism.
Each <code>render</code> value MUST specify its <a>type</a>, for example,
<code>SvgRenderingTemplate2023</code>. The precise contents of each
rendering hint is determined by the specific <code>render</code> <a>type</a>
definition.
</dd>
</dl>

<section>
<h4>SvgRenderingTemplate2023</h4>

<p>
When an <a>issuer</a> desires to specify SVG rendering instructions for a
<a>verifiable credential</a>, they MAY add a `render` property that uses the
data model described below.
</p>

<table class="simple">
<thead>
<tr>
<th style="white-space: nowrap">Property</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>
A URL that dereferences to an SVG image [[SVG]] with an associated
`image/svg+xml` media type.
</td>
</tr>
<tr>
<td>type</td>
<td>
The <code>type</code> property MUST be <code>SvgRenderingTemplate2023</code>.
</td>
</tr>
<tr>
<td>digestMultibase</td>
Copy link
Contributor

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?

Copy link
Member Author

@msporny msporny Feb 17, 2023 •
edited
Loading

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.

<td>
An optional multibase-encoded multihash of the SVG image. The multibase value
MUST be `z` and the multihash value MUST be SHA-2 with 256-bits of output
(`0x12`).
<p class="issue">
The Working Group is seeking feedback related to the mechanism used to express
the cryptographic hash of the SVG image. This property is a placeholder for that
discussion and is not meant to imply a final decision related to the way this
will be done if the feature is accepted in the future.
</p>
</td>
</tr>
</tbody>
</table>

<p>
The data model shown above is expressed in a <a>verifiable credential</a>
in the example below.
</p>

<pre class="example nohighlight"
title="Usage of the render property by an issuer">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"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"
}
},
<span class="highlight">"render": [{
"id": "https://example.edu/credentials/BachelorDegree.svg",
"type": "SvgRenderingTemplate2023",
"digestMultibase": "zQmAPdhyxzznFCwYxAp2dRerWC85Wg6wFl9G270iEu5h6JqW"
}]
</span>
}
</pre>

<p>
In the example above, the <a>issuer</a> has provided an SVG rendering template
for a bachelor's degree that will be filled in with the information in the
<a>verifiable credential</a>.
</p>

<section>
<h5>SvgRenderingTemplate2023 Algorithm</h5>

<p>
The following algorithm is used to transform the SVG image template into the
final SVG image that is displayed. The inputs to the algorithm are the
<a>verifiable credential</a> (`verifiableCredential`) and the SVG image
source code (`svgImage`). The output is a SVG image.
</p>

<ol class="algorithm">
<li>
Generate a map, `replacementMap`, by finding all strings in `svgImage` that
start with `{{` (double open braces) and end with `}}`
Copy link

@gobengo gobengo Mar 10, 2023 •
edited
Loading

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)

Copy link

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)

(double close braces). For each string, `templateKey`, that is found:
<ol class="algorithm">
<li>
Generate another string, `templateValue`, by evaluating the value of
`templateKey` (without the opening or closing braces) using the JSON
Pointer [[RFC6901]] algorithm with the `verifiableCredential` as input to the
algorithm. If the evaluation is `null`, set `templateValue` to the empty string.
</li>
<li>
Set a key in `replacementMap` by using `templateKey` and associate it with
`templateValue`.
</li>
</ol>
</li>
<li>
For every key in `replacementMap`, replace each corresponding
string in `svgImage` that matches the key with the associated value in the
`replacementMap`.
</li>
</ol>
</section>
</section>
</section>

<section>
<h3>Terms of Use</h3>

Expand Down