Add OverlayRenderMethod with oca-bundle-v2 render suite

[PatStLouis]

References #15

Summary

Adds OverlayRenderMethod as a sibling to TemplateRenderMethod for linking a verifiable credential to an external overlay package (OCA Bundle) without prescribing a single visual template.

• renderSuite: oca-bundle-v2 — OCA major version is inferred from the suite name (no separate version property)
• bundle — URL or map (id, mediaType, digestMultibase) pointing at the OCA bundle
• Shared shape with template methods: name, description, renderProperty, optional top-level id / digestMultibase
• JSON Pointer paths from VC document root in capture base attributes (RFC 6901)
• Render (OverlayRenderMethod) processing algorithm for oca-bundle-v2
• OCA bibliography entry and examples (VC + bundle structure)
• Rebased on current main (includes HTML render suite, EmbeddedRenderer)

Supersedes the earlier OCABundle type proposed in this PR.

Test plan

• ReSpec preview builds without errors
• WG review: naming (OverlayRenderMethod vs alternatives), bundle REQUIRED semantics
• Align with any follow-up PR for common renderMethod properties

---

Preview | Diff

[msporny]

We need to spend some time trying to unify the approaches to rendering in the spec and decide what should be in v1.0.

[dlongley]

+1 to figure out if this fits in as an extension or if we can fold it into a unified approach with the other render methods.

We also need to work out where the lines are for extensions, what we can unify, and so on. It seems like minimally unifying on "high-level medium type" to start with would be good (visual, audio, tactile) and then for each of these there might be further breakdowns, e.g., visual => HTML, SVG, etc. Alternatively, maybe visual/audio/tactile just slot in and are just categories for understanding covering accessibility in the spec.

[dmitrizagidulin]

@PatStLouis thank you so much for this PR, this is a great start to the conversation.
As discussed on the call, several of the fields in this PR will likely be useful to ALL the render method classes, so we should consider pulling in common fields into the top level extension spec.

[iherman]

This was discussed during the vcwg meeting on 14 November 2025.

View the transcript

w3c/vc-render-method#25 and w3c/vc-render-method#30

dmitriz: those were discussed previously
… a proposal was to introduce in the core spec itself

brent: do you mean the core data model?

dmitriz: no, the render spec
… that will describe a generic render method, then we would have additional specs for specific methods
… let's look at w3c/vc-render-method#30
… the properties it introduces are general purpose (name, digest multibase, version)
… any method will need those
… So I suggest to wait on this one, as well as PR 25

brent: to clarify: this method is introducing things for a specific render method
… what you propose is to create a separate PR introducing them on the generic render method

dmitriz: correct

phila: reminds me of a discussion I had a long time ago with Mark Nottingham
… about registering a link relation type; Mark pointed out that the link relation type does not give you the media type
… a given VC may have several render method
… having an specific OCA method feels wrong

dmitriz: my understanding of the PR is that it proposes a "super class" of OCABundle

phila: that feels right

manu_: the current way the specification is structured is: we have an extension mechanism, called render method
… we are going to define the generic mechanism, and propose a few concrete ways to use it (PDF, SVG...)
… this is an enormous amount of work
… can we at least prioritize the order in which we go into these things?

manu_: I don't want us to take 2 years to get Render Methods 1.0 published

phila: difference between linking to a render method and embedding

JoeAndrieu: we want to get one, to be able to go to CR
… knowing which one is the 1st one is important

dmitriz: this is a good segway to look at PR 36, which emphasized that the spec is an extension mechanism (as manu_ and JoeAndrieu said)
… I love the idea of "let's take one"; agree with JoeAndrieu that this is going to be a difficult conversation

<dmitriz> we've implemented the HTML template, at MIT DCC. (we started with SVG, but ran into line wrapping probems, and switched to HTML)

dmitriz: SVG and HTML are widely applicable, but maybe not the ones with the most implementations

phila: as GS1, we use SVG and would like SVG to be in there
… any opinion across the room?

dmitriz: dare we bring up the dreaded word "registry"?
… We should not prioritize now, but this discussion is related to deciding what to do with those PRs.
… Let's leave 20 and 35 open for the moment.

---

[PatStLouis]

I've missed the meeting again, my apologies. Here's my intention with this PR and response to some of the comments.

For the added terms, the only thing I've added here is the type (OCABundle) and the version property.

I've observed 3 main patterns to "control" type versioning across w3c / w3c-ccg work items, and I'm open to reconsider this approach.

• Have a specific type tied to a version, ex: MyRenderMethodV2, MyRenderMethod2025
• Have the versioning be inferred by the context used, ex: VerifiableCredential
• Have the versioning be explicitly set as a property on the object (the approach of the PR)

I opted for option 3, since OCA has different versions (v1 and v2.rc-0). When it comes to maintainability, version 3 SEEMS to me like the more convenient solution, since its not entirely reliant on external factor and can allow this spec to evolve without requiring any normative changes. An note can be added for a SHOULD on a specific version (ex: implementers SHOULD use version x).

As far as interop / testing goes, I would only test if A) the bundle resolves B) Each attribute (json pointers) actually points to something in the VC. This is IF we consider testing each individual method necessary, or are only concerned with the DataModel of the renderMethod property.

As for the spec, the only thing that are important is:

• Where to get this bundle
• Explaining that when used as a renderMethod, the attributes are to be interpreted as json pointers on the credential itself.

Now for what model this follows (extension or explicit method) I think this needs more conversation. I could see an extension model that explains each extension and says: here's what to include in your context if you want to use this specific extension. This way we don't need to maintain a context for each method type, only some type definition file that can be linked to but still have a means to test implementations.

[msporny]

@PatStLouis do you plan to pursue this PR? If not, we would like to mark it as pending close.

[PatStLouis]

Thanks for the patience on this one — the branch is updated and rebased on current main.

What changed

This PR no longer proposes a standalone OCABundle type. It now adds OverlayRenderMethod as a sibling to TemplateRenderMethod, with:

• renderSuite: oca-bundle-v2 — OCA major version is carried in the suite name (refers to OCA v2.0.0), not a separate version property on the VC
• bundle — URL or { id, mediaType, digestMultibase } for the remote OCA bundle (parallel to template on template methods)
• Shared fields: name, description, renderProperty, optional top-level id / digestMultibase
• Render (OverlayRenderMethod) algorithm for oca-bundle-v2
• Normative JSON Pointer rules: capture base attribute names MUST be JSON Pointers from the VC document root; overlays that reference those attributes MUST use the same paths

A VC may include both OverlayRenderMethod and TemplateRenderMethod (e.g. OCA for labels/i18n/metadata, HTML/SVG for layout).

Rationale

WG feedback noted that several properties might eventually belong on a generic render-method shape, and that an OCA-specific top-level type was narrow. OverlayRenderMethod + oca-bundle-v2 keeps OCA as the first overlay suite while aligning structurally with TemplateRenderMethod / renderSuite (similar to svg-mustache, html, etc.).

Happy to adjust naming or fold common properties if the group prefers a follow-up PR for shared renderMethod fields first.

Preview should reflect the latest commits on add-oca-data-model.

[iherman]

This was discussed during the vcwg meeting on 19 May 2026.

View the transcript

Add OverlayRenderMethod with oca-bundle-v2 render suite by PatStLouis · Pull Request #30 · w3c/vc-render-method · GitHub

Benjamin_Young: Yeah, it'd be great to get Patrick on here.

Benjamin_Young: And there he is.

Manu_Sporny: There he is. Patrick, we are looking at closing the overlay render method. just to give you some context primarily because we're asserting that the HTML render method is capable of running all logic that OCA would need to do the rendering. but would love your thoughts on this. We're trying to close out pull requests that have been open for a very long time now. so over to you Patrick to provide your thoughts…

Manu_Sporny: if you have them.

Patrick_St-Louis: Yeah, sure.

Patrick_St-Louis: Happy to provide my thoughts. definitely. So, what's currently in the spec, they're all template based. So, they're a way to provide a template that people can feed the verifiable credential and display some values. the approach of OCA is really to provide semantic information. So you don't provide a template but you provide rendering hints and instruction through an external bundle and it comes with all the overlay capture architecture features and overlays you can put.

Patrick_St-Louis: So I personally will keep saying that I think it provides a significant different approach than just providing a template and could possibly offer extra capability. But I've not heard the conversation that just had about this being possible with HTML.

Manu_Sporny: So, let me kind of highlight what's possible with the HTML nder So the HTML render method can run arbitrary code over the entire verifiable credential and then render it to HTML which then be exported in the future we're going to add this feature can be exported to an image or a PDF or an SVG. So the entirety of the logic, how OCA can work and be expressed in the HTML. So I think your mental model about what we're doing is template based is out of date, right? Meaning meaning that we have new mechanisms like the HTML render method that can run arbitrary code.

Manu_Sporny: it can take, the verifiable credential as input and then it can do whatever transformations and whatever it wants to render it then to an image format. And the suggestion is we can do that with the HTML render method and OCA can be a subset of that. back over to you Patrick.

Patrick_St-Louis: So I'd be curious just a simple example here. I have a credential and I want to be able to render a HTML page that shows the credential across three different language including labels, descriptions and so on. How would you achieve this with a HTML template without hard- coding all the descriptions and different language in the template itself? duplicating the template or times. For example, if you want to support for language back to you

---