Proposal: `RenderTemplate2024`

[BigBlueHat]

The following proposals aims at a single, template format focused render method--where the content/media type decision becomes secondary (and is expressed separately). The proposed template engine would be Mustache for it's deliberate minimalism (though certainly alternatives could be explored).

The primary aim is to map the credential into a text-based template format (Mustache). The output format itself becomes a secondary concern (for rendering), though perhaps a primary concern for display/use choices.

Below is a proposed expression with inline comments:

"renderMethod": [
  {
  // human facing display name for selection
  "name": "Landscape",
  // media query as defined in https://www.w3.org/TR/mediaqueries-4/
  "mediaQuery": "@media (orientation: landscape)",
  // simplified type which focuses on template language compatibility (vs. "output" type)
  "type": "RenderTemplate2024",
  // inline template field for use cases where remote retrieval of a render method is suboptimal
  "template": "",
  // URL for remotely hosted template
  "url": "https://example.com/iso7810-landscape.svg",
  // content/media type for (possible) conneg on the above URL
  // and certainly for display use
  "mediaType": "image/svg+xml",
  // used for resource integrity and/or validation of the inline `template`
  "digestMultibase": "..."
  },

  // VoiceXML for non-visual use / A11Y (perhaps)
  {
  "name": "Audio",
  "type": "RenderTemplate2024",
  "template": "<?xml version=“1.0” encoding="iso-8859-1"?><vxml version="2.0" xmlns="http://www.w3.org/2001/vxml" xml:lang="en-US">...</vxml>",
  "mediaType": "application/voicexml+xml"
  }
]

Feedback welcome! 🎩

[msporny]

"url": "https://example.com/iso7810-landscape.svg",

Why not use id instead of url?

[msporny]

The VC API group discussed this on a call today and there was no opposition to the general direction. On the call was @jandrieu @Wes-smith @PatStLouis @cxcheng @TallTed and @msporny.

[dmitrizagidulin]

Why not use id instead of url?

I think url would be clearer. (since it's not the ID of the renderMethod config block. it's merely the location of the hosted template file, which is a small component of the overall config).

[msporny]

I think url would be clearer. (since it's not the ID of the renderMethod config block. it's merely the location of the hosted template file, which is a small component of the overall config).

Yes, I can kinda see that argument. The challenge is that digestMultibase (in the example) applies to id, not url... and so the only way that could work is we do this:

  "url": {
    "id": "https://example.com/iso7810-landscape.svg",
    "digestMultibase": "...."

and then if we move digestMultibase in there, we need to move media type in there... hopefully that highlights the problem I'm concerned about? Maybe we move all of this inside template, which could be a string or object?

[dmitrizagidulin]

@msporny I see. Two thoughts, then.

1) Why does the media type need to move in to the url? It belongs to the config, not to the url, no?

2) In that case, how about we do, instead:

"renderMethod": [
  {
    "template": {
      // For hosted templates
      "id": "https://example.com/iso7810-landscape.svg",
      "digestMultibase": "...."
    },
    // ...
  },

  {
    "template": {
      // For inline templates
      "contents": "<template goes here>"
      // "digestMultibase": -- not needed, since the data integrity proof secures embedded templates
    },
    // ...
  }
]

[dlongley]

@dmitrizagidulin, @msporny, please take a look here at the modeling suggestions as perhaps some of this ground has been covered before:

https://github.com/w3c-ccg/vc-render-method/issues/1

A combination of the information there and here might result in both a more correct and versatile data model.

[dlongley]

I think we need to do a slightly better job of separating the render method information from the template itself (or one or more templates potentially) -- and both the information and the template(s) may each potentially include a digest property, depending on whether they are embedded or simply referenced.

[msporny]

A general observation since we went to a "date-less" type for SvgRenderTemplate and then immediately broke backwards compatibility. I'm (unsurprisingly) increasingly of the opinion that we need to version these types as they go through incubation. I'm willing to say that once we go through a standardization process for the types that we can remove the date then, but not before as we keep breaking backwards compat during incubation (and people ARE shipping these broken things into production, no matter how much we plead with them to not to do that).