Introduce `RenderMethod` for untemplated renderings. #38

BigBlueHat · 2025-11-24T20:12:30Z

Add comments to sections; helps while editing.
Add RenderMethod section; move nfc there.

This is an attempt to address #37 and uses ideas from #32 which could be expanded to the other render method definitions.

Preview | Diff

This is especially useful when folding/collapsing sections in an editor that supports that.

This also introduces the concept of `modality` which may be useful for other types of render methods.

bparth24

@BigBlueHat cc: @dlongley

LGTM at first read.

Additionally, I feel we still need to update nfc example 8 in here https://pr-preview.s3.amazonaws.com/w3c/vc-render-method/pull/38.html#example-usage-of-the-nfc-render-suite - replace payload with template as field name.

Payload name is only for legacy support and should not be used for any new NFC development work. Template field name should be used IIRC from the slack conversation between you, me and Dave Longley.

dlongley · 2025-12-01T16:37:55Z

index.html

+        <h4>RenderMethod</h4>
+
+        <p>
+In situations where templating is not required, an [=issuer=] can provide a
+predetermined payload to be displayed, transmitted, or otherwise rendered.


I don't think we should use what could be the base class for all render methods for this -- specifically because of the payload property, which I'll explain more on below. If we want to do this, we ought to use another name. Maybe PayloadRenderMethod or StaticRenderMethod?

I think it does make sense to define a base class (probably named RenderMethod) for all render methods, but it should only include those properties that are expected to be available/used (and not in conflict) with any derived classes. If we include payload as a property on the base class, it will be in conflict with TemplateRenderMethod which not only does not use it, but uses something else for a similar purpose: template.

Notably, the value of template could already potentially be used to produce a "static" output, which would cover the payload case without the need for yet another render method. We should discuss and decide whether it's worth having a render method just for a single special case of templating.

Presumably, there's some performance benefit to not running a template through a template engine when this is the case. However, I expect that to probably be a fairly minor benefit -- especially when weighed against the aggregate cost of every rendering application in the ecosystem needing to implement a different bit of code for a special case (and the testing, test suite, etc., required).

Also, TemplateRenderMethod may still produce a "static" output anyway even after this. Certainly, IMO, creating an error case and trying to detect whether a template "changed" in its output (and should have been SomethingElseRenderMethod on that basis) is not a good use of effort or resources.

I think many of the properties below make sense to go into a base class: description, name, id, type, modality, etc. I also wonder whether renderProperty should be in the base class. The renderProperty is a declaration by the issuer of what information from the VC will be present in the rendering. This has utility for rendering software regardless of whether the output of filtering a VC (via this property) is used in the output directly or just implicitly.

Another way to do "static" rendering is to use TemplateRenderMethod and specify the template engine as static (as opposed to mustache or whatever else), and specify the template with an appropriate media type.

Presumably, there's some performance benefit to not running a template through a template engine when this is the case.

I think there's also a security consideration here as authors may want to avoid the contents being passed to other processors, and so are providing something with no additional processing expectations.

I agree that RenderMethod can (and probably should be a base class that TemplateRenderMethod extends with templating functionality) and ideally the additional "content" term (i.e. payload or template or whatever) is inherited as well.

Also, TemplateRenderMethod may still produce a "static" output anyway even after this. Certainly, IMO, creating an error case and trying to detect whether a template "changed" in its output (and should have been SomethingElseRenderMethod on that basis) is not a good use of effort or resources.

Not suggesting that at all, just that the author of the credential should have a way to express that they do not want this processed only displayed which the overloading of the template term would not allow--without additional signals as you mention with static as a template engine option.

Either way, authors of credentials should be empowered to provide inert values for display/use (as with the nfc use case).

Useful for signaling what is to be shared via the render method.

The goal is to have a single term for both static and pre-processed content provided in the render method.

dmitrizagidulin · 2025-12-03T15:37:10Z

Additionally, I feel we still need to update nfc example 8 in here https://pr-preview.s3.amazonaws.com/w3c/vc-render-method/pull/38.html#example-usage-of-the-nfc-render-suite - replace payload with template as field name.

I agree, I think the field containing the template should be termed template -- payload is a bit confusing.

dmitrizagidulin

Looks great. (payload field should be renamed to template if at all possible, though.)

dmitrizagidulin · 2025-12-03T15:39:30Z

index.html

              <td>
-A REQUIRED [=string=] that identifies the algorithms that are used for
-generating the concrete rendering.
+A REQUIRED [=string=] that identifies the mode by which the payload will be


I think it might make more sense to make this field OPTIONAL. (or, if missing, default to the value default or something similar)

dmitrizagidulin · 2025-12-03T15:45:58Z

index.html

        </section>

-        <section>
+        <section><!-- pdf-mustache Render Suite -->


I think we should remove the pdf-mustache section. PDF is a binary format, it's not really possible to use Mustache with it.

dmitrizagidulin · 2025-12-03T17:05:02Z

Discussed during Wed Dec 3, 2025 call.

Manu mentioned that we need to be careful about the VC 2.0 Vocab being frozen (and it defines a TemplateRenderMethod class already).
- also, the consensus at VC WG was "we're not going to substantiate the 'abstract' classes" -- do we want to go a different path instead? The alternative would be to create two new subclasses, Templated and Un-Templated.
Dave: It seems that we've come up with a handful of properties that would be useful for many suites (name, description, modality, renderProperty, a payload/template field, and renderSuite). Which means we don't have to mess with the abstract superclass method.
Benjamin: re 'pdf-template' suite -- we don't need a separate type for that, the pdf part can just be handled in the suite media type.

Consensus so far:

Leave the abstract class as is, in the vocab (RenderMethod)
Create (just one to start with) subclass (name tbd)
Switch the rendering logic, as much as possible, through the suite name.

Lets refactor this PR and re-discuss.

TallTed · 2025-12-03T17:16:42Z

index.html

-A REQUIRED [=string=] that identifies the algorithms that are used for
-generating the concrete rendering.
+A REQUIRED [=string=] that identifies the mode by which the payload will be
+transmitted or rendered. Possible examples of modalities may include `nfc`,


Possible, examples, and may are redundant.

Suggested change

transmitted or rendered. Possible examples of modalities may include `nfc`,

transmitted or rendered. Possible modalities include `nfc`,

or

Suggested change

transmitted or rendered. Possible examples of modalities may include `nfc`,

transmitted or rendered. Example modalities include `nfc`,

TallTed · 2025-12-03T17:26:12Z

index.html


          <pre class="example nohighlight"
-          title="Usage of the render property by an issuer">
+               title="Usage of the nfc render suite">


Suggested change

title="Usage of the nfc render suite">

title="Use of the NFC render suite">

TallTed · 2025-12-03T17:26:24Z

index.html

+          </table>
+
+          <pre class="example nohighlight"
+          title="Usage of the renderSuite property by an issuer">


Suggested change

title="Usage of the renderSuite property by an issuer">

title="Use of the renderSuite property by an issuer">

BigBlueHat added 2 commits November 24, 2025 15:09

Add comments to sections; helps while editing.

632ef1a

This is especially useful when folding/collapsing sections in an editor that supports that.

Add RenderMethod section; move nfc there.

da4da74

This also introduces the concept of `modality` which may be useful for other types of render methods.

BigBlueHat requested review from PatStLouis, dmitrizagidulin and msporny as code owners November 24, 2025 20:12

BigBlueHat requested a review from bparth24 November 24, 2025 20:12

BigBlueHat requested review from isaackps and pohhendry as code owners November 24, 2025 20:12

BigBlueHat requested review from dlongley and msporny November 24, 2025 20:12

BigBlueHat changed the title ~~untemplated methods~~ Introduce RenderMethod for untemplated renderings. Nov 24, 2025

bparth24 approved these changes Dec 1, 2025

View reviewed changes

dlongley requested changes Dec 1, 2025

View reviewed changes

BigBlueHat added 4 commits December 2, 2025 11:52

Move RenderMethod up in prep to base class it.

5022ab9

Redescribe RenderMethod in base class terms.

55e583d

Move renderProperty up into base class.

f53a489

Useful for signaling what is to be shared via the render method.

Remove base class properties; use payload.

a477a13

The goal is to have a single term for both static and pre-processed content provided in the render method.

dmitrizagidulin requested changes Dec 3, 2025

View reviewed changes

dmitrizagidulin reviewed Dec 3, 2025

View reviewed changes

TallTed reviewed Dec 3, 2025

View reviewed changes

bparth24 self-requested a review December 4, 2025 17:08

	transmitted or rendered. Possible examples of modalities may include `nfc`,
	transmitted or rendered. Possible modalities include `nfc`,

	transmitted or rendered. Possible examples of modalities may include `nfc`,
	transmitted or rendered. Example modalities include `nfc`,

	title="Usage of the nfc render suite">
	title="Use of the NFC render suite">

	title="Usage of the renderSuite property by an issuer">
	title="Use of the renderSuite property by an issuer">

Introduce RenderMethod for untemplated renderings. #38

Are you sure you want to change the base?

Introduce RenderMethod for untemplated renderings. #38

Conversation

BigBlueHat commented Nov 24, 2025 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bparth24 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dlongley Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmitrizagidulin commented Dec 3, 2025

Uh oh!

dmitrizagidulin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmitrizagidulin commented Dec 3, 2025

Uh oh!

TallTed Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Introduce `RenderMethod` for untemplated renderings. #38

Introduce `RenderMethod` for untemplated renderings. #38

BigBlueHat commented Nov 24, 2025 •

edited by pr-preview bot

Loading

bparth24 left a comment •

edited

Loading

dlongley Dec 1, 2025 •

edited

Loading

TallTed Dec 3, 2025 •

edited

Loading