`renderMethod` data modeling

[davidlehn]

The current (2023-04-28) example looks like this:

  "renderMethod": [{
    "id": "https://example.edu/credentials/BachelorDegree.svg",
    "type": "SvgRenderingTemplate2023",
    "name": "Portrait Mode",
    "css3MediaQuery": "@media (orientation: portrait)",
    "digestMultibase": "zQmAPdhyxzznFCwYxAp2dRerWC85Wg6wFl9G270iEu5h6JqW"
  }]

I think the data modeling here needs some work.

• It doesn't seem a renderMethod should be an SVG itself.
• The properties above don't look like they are for the SVG subject.

I'd propose a few things:

• renderMethod should be a set of *RenderMethod* types.
• Rename method here to SvgTemplateRenderMethod2023.
• The methods would not need to have an explicit id.
• Methods should use some common properties defined here to support the general render mechanism.
• Methods should probably have their own specs, so they can grow independently. While this is early, keep the SVG design here.
• Methods would define their own properties as necessary.
• Move the SVG off to another property, maybe more modeled as a tree.

I'm not sure what the vision is here how the user agents will work. Some issues:

• Given multiple methods, how do you choose which one to use?
• Should this have content-type and accept like semantics with media types and quality params? That could leverage known methods and code to pick how to display things.
• What properties need to be explicit vs implied by a method type?
• Need to consider internationalization here too. Some render methods might be able to handle it internally, others will not.
• This could all add up to a very large JSON blob. It could be all externalized by just having an id to a remote JSON-LD blob, but then you have caching and server request privacy issues. But perhaps some specs could define static blobs to partially avoid the issues.
• The "templates" described are one way to do things. Should design this with idea a Web Component method might be used directly.

With the above, and some extra methods just to show the concept:

  "renderMethod": [{
    "type": "SvgTemplateRenderMethod2023",
    "name": "Graphical Display",
    "contentType": "image/svg+xml",
    "css3MediaQuery": "@media (orientation: portrait)",
    "svgTemplate": {
      "href": "https://example.edu/credentials/BachelorDegree.svg",
      "digestMultibase": "zxSVGdhyxzznFCwYxAp2dRerWC85Wg6wFl9G270iEu5h6JqW"
    }
  }, {
    "type": "HtmlTemplateRenderMethod2023",
    "name": "HTML Display",
    "contentType": "text/html",
    "htmlTemplate": {
      "href": "https://example.edu/credentials/BachelorDegree.html",
      "digestMultibase": "zxHTMLhyxzznFCwYxAp2dRerWC85Wg6wFl9G270iEu5h6JqW"
    }
  }, {
    "type": "WebComponentRenderMethod2023",
    "name": "Web Component Display",
    "contentType": "text/html",
    "htmlTemplate": {
      "href": "https://example.edu/credentials/BachelorDegree.html",
      "digestMultibase": "zxWCPdhyxzznFCwYxAp2dRerWC85Wg6wFl9G270iEu5h6JqW"
    }
  }, {
    "type": "PlainTextRenderMethod2023",
    "name": "Plain Text Display",
    "contentType": "text/plain",
    "textTemplate": {
      "href": "https://example.edu/credentials/BachelorDegree.txt",
      "digestMultibase": "zxplainyxzznFCwYxAp2dRerWC85Wg6wFl9G270iEu5h6JqW"
    }
  }]

If you moved that off to another URL it might collapse to a cachable static file so the VC only as a reference:

  "renderMethod": "https://example.edu/credentials/BachelorDegreeRenderMethod20230428.json"

[lemoustachiste]

Hi,

I just wanted to share what we do with Blockcerts as we've been doing a visual layer since the inception (before VCs where VCs).

From the beginning, the display property as it's called (displayHtml in the earlier versions) was only a HTML string (with inline CSS and base64 encoded images).

In our V3 we have opened support for more than just HTML and we can render images (gif, jpeg, png, bmp) and pdf documents, provided those binary files are base64 encoded).

The property schema is consultable here https://github.com/blockchain-certificates/cert-schema/blob/master/cert_schema/3.1/displaySchema.json

but basically we have:

{
  ... // VC root
  display: {
    content: "<p>Hello World</p>",
    contentMediaType: "text/html",
  }
}

or with a binary file:

{
  ... // VC root
  display: {
    "contentMediaType": "image/png",
    "contentEncoding": "base64",
    "content": "iVBORw0KGgoAAAANSUhEUg..."
  }
}

Then we have a renderer web component which builds the HTML as needed depending on the media type: https://github.com/blockchain-certificates/blockcerts-verifier/blob/master/src/selectors/certificate.ts#L193

I generally agree with the proposal, I like how encapsulated it can be and I like the distant hosting with a digest (I think it is easier than using hashlinks).

However I believe it should allow for self contained data, at the expense of having larger credentials but with the added benefits:

• improved privacy: no phone home possible if all the data is already there
• longer durability: the issuer does not need to host the visual files anywhere, hence the document can live without the issuer even if the latter would for some reason disappear