OCA presentation layer

[blelump]

Introduction

OCA presentation layer is one of the third fundamental features of OCA. The two remaining are data harmonization (including any third party process to achieve harmonization, ie. transformation) and context preserving data capture. This triple enables everyone to preserve capturing context of the data, have the consistent data and finally present it on the screen if needed. Not every data requires presentation on the screen and usually only this that was captured from humans. In other words if one party fulfilled the form, the other party may want to see it on the screen. When data doesn't need presentation in most cases will be captured by machine, ie. an IoT sensor that measures environmental data. Data captured in such manner will require unified form for further processing/data mining/predictive maintenance, therefore harmonized data is they key to achieve it.

Issues with presentation layer

OCA presentation layer enables to visually see the captured data in the most human friendly way. Either this is mimicking real world cases to digital world (ie. any type of credential) or just a nice way of presenting data on the screen, it is always dependent upon device and the underlying technology used for actual presentation. Being device and technology agnostic in terms of presentation is very difficult to achieve. Many devices and technologies exist for information presentation while none actually enables a unified way of doing so. The presentation problem is known since decades and many tried to unify it in the past. However, the fact is the industry never reached even a standard of how to define information presentation on the screen, not mentioning cross device or cross technology portability. Is this a gap that the industry didn't notice? No, this is a difficult problem to solve.

Any presentation is device and technology dependent. Devices come in various resolutions and screen sizes, usually biased to some particular technology that can be used for presentation. Therefore any approach that would address agnostic-ism to device and technology must be merely about layout, so about spatial orientation or how various pieces are located on the screen (or part of it). A good example of how to think about it is this tree:

Linked from https://docs.flutter.dev/development/ui/layout

Any layout is inherently a tree based structure that consists of elements, that are displaced upon the parent element. A syntactic sugar, so the rows and columns concept enables better spatial orientation. The current layout overlay is implementing this concept as follows:

   ...
  - type: row
    elements:
    - type: col
      elements:
      - type: label
        name: attribute3
   ...

Layout overlay shall provide only spatial orientation of the elements on given area and at the same time stay technology agnostic. The current layout overlay requires css attribute and therefore is not technology agnostic.

Determinism in OCA

Worth to recap the fundamental assumption that all the overlays implement: they are deterministic, actually the whole OCA bundle is. Deterministic OCA bundle is in other words self-encapsulated and nothing can be injected in runtime. In this sense all the overlays are inherently made in stone. Deterministic OCA is crucial characteristic for proper governance.

Presentation layer that is device and technology agnostic

To achieve such kind of agnostic-ism, current layout overlay must remove any technology specific behavior and become template overlay. Where there's a need of technology specific behavior, new type of overlay has to be defined: layout overlay. Assuming ZIP as OCA bundle, the following would be a part of the meta file:

digest: template.credential.<1024.yml # template overlay
digest: template.credential.1024-1280.yml # template overlay
digest: layout.credential.web.<1024.yml # layout overlay that reuses credential.template.<1024.yml
digest: layout.credential.web.>1024-1280.yml # layout overlay that reuses credential.template.1024-1280.yml
digest: layout.credential.flutter.<1024.yml # layout overlay that reuses credential.template.<1024.yml
digest: layout.credential.react-native.<1024.yml # layout overlay that reuses credential.template.<1024.yml

A dependency tree among overlays would look like:

.
├── template.credential.1024-1280.yml
│   └── layout.credential.web.>1024-1280.yml
└── template.credential.<1024.yml
    ├── layout.credential.flutter.<1024.yml
    ├── layout.credential.react-native.<1024.yml
    └── layout.credential.web.<1024.yml

Layout/template overlay metadata consists of:

1. human readable name (ie. credential) [required],
2. applicable platform (ie. react-native) [required],
3. matching resolution pattern (ie. <1024) and driver name (ie. flutter -- only layout) [optional -- if not defined, applied for all cases].

This is a proposal and can be discussed further. What's important is the clear distinction per device and technology.
In all cases YAML is preferred as it is the simplest descriptive language for defining behavior.

Layout overlays merely inherit from template overlays the spatial arrangement and add technology specific flavor that is required to render them properly, using given technology.

These assumptions guarantee flexibility while preserving the determinism. There can be any number of template.xyz.yml as well as layout.xyz.yml, each serving desired purpose or spatial arrangement, including proper logo, background color and so on. This is always finite number of cases(overlays), even across various jurisdictions or countries. Since there are multiple of them, it is up to the client to decide which one to use in given use case (according to device resolution or the underlying technology).

The drivers that are responsible for proper rendering can be implemented externally for given technology. Whether this is Flutter, React Native, PDF or WEB, it is up to the driver to present the layout properly. Presentation, so the driver, is optional to the OCA core and therefore all the rendering drivers are optional.

Update as of 28th of Sep 2022

Template and layout overlay distinction

Template overlay

The template overlay defined above provides only a spatial arrangement. Neither components nor styling are defined on this level. This is only an agreement how assets provided via layout overlay must be arranged within given area.

Layout overlay

Layout overlay adds proper look and feel to the template overlay.

Whether layout overlay is part of OCA bundle is governance dependent. In cases where issuer didn't impose any particular rules of how to present his data, but merely provided minimum amount of assets that shall be used, ie. this case, layout overlay is outside OCA Bundle.

[swcurran]

I don't understand the connection of this to the proposal we made in the Excel sheet for the new tab with the (so called) "Template Overlay". What we're trying to do is move away from device specific issues (screen resolutions, presentation layer technologies) and simply have the OCA Creator say "here are some parameters you can use when displaying this data". That leaves the party that is actually displaying the data to use the parameters (logo, background image, etc.) anyway they want. That means the OCA bundle has less layout information -- vs. the suggestion here, which I interpret as much, much more layout information.

That said -- I'm not against an OCA way of doing layout as you describe above, if others think it is useful. However, we would not be using it, and we still would like an OCA way to do the "Layout Parameters" approach that we have proposed.

[blelump]

Let me elaborate. As said above, one of the fundamental OCA characteristics is determinism. Any OCA related object, so Capture Base or Overlay has to be deterministic. If object is not deterministic, it inherently becomes mutable, so its state can vary upon external factors. It is then not controllable by OCA what can be injected. Actually even if it would, so we limit possibilities like we do in Entry Overlay to a list, ie. background color gets solely supported background colors, similar for logo and so on. Then a combination of such attributes, so you pick ie. logo2 and background color red in runtime is still not deterministic. Any selected combination cannot be verified, ie that this credential shall have logo2 and blue background rather than red. We desire such characteristic in OCA, so to have it consistent. When its state can vary, we cannot have proper governance, because no one knows what state will be injected in runtime.

I see your point of view and where you're heading. Usually it would make sense as it simplifies lower layer (OCA) and delegates presentation-specific tasks to the upper layer. Such approach would then break determinism.

In the case of presentation layer in OCA it becomes even more complex. Presentation on its own is difficult among plenty of devices and various technologies supporting them (or not). To have them deterministic adds even more issues, but it is doable by carefully managing the possibilities. The possibilities for any use case are finite, always.

In your case, it would be then one template overlay and as many layout overlays as you have amount of credentials to support. If you support mobile-only, then it is exactly one template and many layout overlays. If bigger screen sizes are supported as well, either another template overlay is required to define spatial orientation for these screens or the same from mobile can be reused.

[swcurran]

I don't feel we are making much progress. I'm in Europe next week and now will not be able to attend RWoT, so I have some time on my hands. Can we have a meeting of those working on the OCA specification and go over this at some point?

To your last point. We don't want the OCA creator to provide layout. That is the point. We want the OCA Creator (who in our case is usually the issuer) to say "here are some visual elements for use when displaying the data -- use them as you see fit". They can't be swapped for other elements (logo1 for logo2) -- they came from the "trusted party" (the one we want to trust) -- via the overlays they constructed. But at the same time, we don't want that "trusted party" to define how those elements will be used. That is left to the party receiving the data + OCA data.

For a concrete example -- I have created a mobile wallet. My users will receive 100s credentials each into their wallet. I don't want the issuers of each of those 100s of credentials to have full control over how their credential will be displayed in my wallet as each will be completed unique. I want to give the issuers some control, but my wallet will be absolute crap if I let all 100 have complete control over each credential. I will define the specific layout for all credentials, and use the elements that I permit the issuers to provide me to get a balance of a great UX, and reasonable branding for issuers.

I'm do not think it is at all feasible to ask an issuer to provide me 20x (and counting) layouts for different screen sizes. That will never fly, nor ever work.

[blelump]

Hey Stephen,

thanks for comment. As said above, I completely understand your point of view and the way you want to tackle it.

In the DDE concept that I suppose you're familiar with where OCA is one of the foundation components, you never trust, you always verify, everything. Trust is human related while machines don't trust, they verify by utilizing mechanisms derived from cryptography. Therefore we impose solutions that are not about trust, but about the capability of being able to be cryptographically verified.

This issue is about a concept that solves presentation concerns in authentic way. While this is not an easier solution what is proposed here, with proper support of the tooling any amount of desired layouts becomes just a matter of preparing them. If you have ie. 100 different creds that potentially can be presented on a user device, you have at most 100 variations of layouts (including, different logos, fonts, colors, spatial orientation and so on) times amount of screen sizes you want to support (if you don't care it is simply 1). You therefore still need to support these variations, but you're just moving this concern to an upper layer, where it can be programmed by the implementor. Note the problem still persists, but is just addressed somewhere else.

The issuer of any credential is interested of how his credential is being presented. This is in fact the issuer sole interest. Your wallet must not take this responsibility against the issuer. For example when you generate PDF document (you're the issuer) that is later sent to the issuee (the holder). You're absolutely interested of how the issuee will see your document. You actually desire that the issuee will see everything in exactly the same form you see it.

[swcurran]

Sounds like we fundamentally disagree on a path forward. I can't support anything that requires the type of layout you are proposing, and your saying the same about what I would like to see. I don't see any problem with taking the responsibility away from the issuer -- provided they have some reasonable amount of input into the layout.

BTW -- our view is that these are digital credentials that are to be verified digitally -- with cryptography. Our research and input from policy makers is that we don't want the digital credentials to look like their paper equivalents because then verifiers will think they just need to look at the credential for verification -- e.g. they will revert to their paper mental model. As such we will require that the on-screen view of the credential not look like the paper equivalent.

Philosophy aside on how to control the on-screen look of the data we want to present, is there any path forward for us to use OCA for Credential Branding or do we just need to look for another approach? Can we define an overlay that has the data we want in it?

[swcurran]

An idea. Is one option for this to have a "credential_branding" overlay that is specific to Aries deployments, documented in as an OCA Extension and in the Aries RFC called "OCA For Aries" that I'm working on? Then we don't have to agree on the layout question. It would mean that the Excel-to-OCA Bundle tool would have to have an Aries variant, but I'm assuming that is not too difficult.

[blelump]

We introduce template overlay, that is just spatial orientation of components. Everything else can be injected in runtime as you want. Lets take this as example (Designing passes section). You have one template and 5 variations.

The proposal from the first post is exactly the same, except it is immutable. There is then one template overlay and 5 layout overlays. Layout overlays don't need to be part of the bundle, therefore they can be added even at runtime, with the payload defined in your wallet. Does it work for you?

[swcurran]

As I understand it, you are suggesting that the issuer (producer of the data) should control the layout, where as I'm proposing that the holder/verifier (receiver of the data) should control the layout -- with specified declarative inputs from the issuer (logo, color, etc.). Is that accurate?

What we are proposing is much like Apple is saying, here. Apple says, as a pass creator, you give us there parameters to work with, and we'll lay them out like this. Apple (the receiver of the data) defines the layout, the pass creator (producer of the data) does not control the layout, but does provide the parameters (logo, color, etc.).

[blelump]

I think we're on the same page. Let me explain. Lets take this as assets bundle for given credential.

1. Issuer (Apple in this case) defines template overlay for spatial orientation.
2. You construct layout overlay upon template overlay from issuer and inject assets from bundle in runtime. In other words within your wallet you take the assets, create layout overlay with these assets. This is done in runtime via proper interface. Finally your wallet renders the credential. In OCA bundle there's no layout overlay, but there's template overlay.

In the end everything is deterministic, but at the same time you can solve your case.

[swcurran]

I think we are still not connecting.

Apple in our example represents the holder -- they provide the software for the holder. Apple is the same as Aries Mobile Wallets, or Aries Web Apps for holders and/or verifiers. The issuers are everyone that issues a credential to a holder (government, bank, health club, employer, university, etc.) and that goes into the software provided by Apple. The issuers do not provide any layout information -- that is far too complicated. And no OCA layout is created by anyone. The layout is strictly up to the maker of the software displaying the credential -- the recipient of the OCA file.

For the branding: We (the Aries community) defines the branding components that we want issuers to use via OCA (in an RFC that I have almost completed drafting). We define a style guide that says things like, "the icon you use should be 480x480px, 1:1 aspect ratio" and that style guide contains a recommendation to software makers about how to use the elements. The issuers supply, via OCA per credential type, the elements (icon, background image, colour, font colour...). How those elements are used is up to the software makers (those that make mobile wallets and web apps, etc.) to do the actual layout -- how closely to follow the recommendations of the community, and what extra features to support (e.g. dark mode and light mode, reactive layout, etc.).

The result is the following -- showing the same credential with no OCA information, and with OCA information. The OCA data has no impact on the layout, but you can see all the differences between the screenshots to show how OCA information is used.

For me, the only question is what we name the overlay that the issuer will use to provide the data, and if it is an "OCA Core" overlay, or just something we define for Aries / Verifiable Credential use cases. Here are the attributes I expect in the overlay:

• logo_uri - a URI pointing to a logo to display with the credential.
• logo_base64 - an inline logo to display with the credential.
• background_image_uri - a URI pointing to a background image to display under
  the credential data.
• background_image_base64 - - an inline background image to display under the
  credential data.
• header_background_color - an RGB color code for the credential display header
  background color.
• footer_background_color - an RGB color code for the credential display footer
  background color.
• header_font_color - an RGB color code for the credential display header font
  color.
• footer_font_color - an RGB color code for the credential display footer font
  color.
• primary_attribute - the name of the primary capture base attribute to display
  on the credential.
• secondary_attribute - the name of the secondary capture base attribute to
  display on the credential.

[pknowl]

Thanks, Stephen. This work looks excellent.

The final review of the OCA technical specification is nearly complete. I should have the final document finished this week. All being well, we aim to go public on October 14th. The important thing is that the "Layout overlay" is to be deprecated.

Having spoken to you this evening, I believe you have fully understood the "task-specific" nature of the overlay concept. That granularity will enable full interoperability and extensibility as use cases come in.

We're undoubtedly excited to support your branding and credential layout PoCs. I understand that the initial documentation will be in the "OCA for Aries" track.

Apart from "data harmonisation", another core requirement of the Semantic domain is "objectual integrity". That means after a few successful PoCs to demonstrate the presentation layer (and we're collectively happy from a security standpoint), we can migrate the essential pieces into the core OCA spec.

Object presentation is an exciting area of exploration for sure. It'll be fun to see the evolution.

[pknowl]

At RWoT, Andrew Slack and Victor Martinez from SICPA composed three new overlay types for the presentation layer. They look good to me, and I believe they are close to your thinking, Stephen. So I'm dropping the screenshots here to keep the conversation going.

[ajslack]

Thank you for sharing here @pknowl. The draft document they were taken from is here.
There are definite similarities. I want to highlight a few differences in the proposals that have to do with whether overlays operate at attribute level or data-object level.

Presentation Overlay

This seems similar to the 'branding overlay' proposal, defining data-object wide styles, minimum accessibility requirements.
Key:value pairs that can be appropriated by a front-end UI to style the data-object and attributes.

Note: other assistive technology readable data like description and label can be pulled from existing semantic overlays.

Data-Representation Overlay

Provides a way to define attribute specific representations. For example an image aspect-ratio, a specific SSML voice to use when reading an attribute or use of a specific visual style for an attribute. (It is not imagined every attribute would have a unique data-representation but this provides some flexibility to issuers)

Asset Overlay

Defines assets to visually(or other sensory formats) describe attributes. Note this is not data-object presentation assets like a background image for a credential, which should be handled by Presentation Overlay.
As mentioned above there are some contexts in which well-known iconography used to visually describe attributes can lower cognitive burdens for users.

[swcurran]

These go beyond what the "OCA For Overlays" proposal suggests, I think, and oversteps the bounds of what we think should be used by the producers of the data should provide to the consumer.

The presentation overlay is much like our "branding" overlay but gets into areas (minimum-contrast, voice, maximum-line-length, hyphenation) that should be left to the consumer. Again, I come back to the 100 issuers of credentials going into one wallet example, where the wallet supports responsive design to work on all screen sizes. The wallet will have selected values for all of those items as part of it's user interface design and that impact the entire wallet. Then, it has input from 100 other sources, each covering a tiny portion of the overall user interface, that provide different values that it must rationalize.

Again for that same scenario, the asset and data-representation overlays at the data attribute level is difficult because of the use of additional elements for individual attributes that must be used in a responsive design. Will the image look good on all screen sizes? Will it fit with the rest of the user experience of the wallet?

Perhaps these can work for some scenarios, but I don't think they are useful/implementable in the many-to-one scenarios (many data objects displayed by one application) we are dealing with.