OCA for Aries and OCA for Aries Style Guide RFCs

[swcurran]

Signed-off-by: Stephen Curran [email protected]

[cvarjao]

what is the "primary attribute" and "secondary_attribute"? is that the "Issuer Name" and "Credential Name", respectively?

[swcurran]

The idea is to allow the issuer to suggest to the wallet (display software) the "best" attributes from the credential to display on top of the background image. In other words, if the wallet (or whatever) displays the "card", it could follow the issuers suggestion and put one or both of the primary and secondary values (perhaps with their multilingual labels). They might put those instead of "Issue Date" (which is NOT an attribute in the credential -- it's metadata collected by the wallet), or in addition to "Issue Date". Without some guidance from the issuer, the wallet would have no information to decide which attributes might be helpful to show.

Does that sound useful? I confess that it was an idea of mine that I thought might be useful.

[cvarjao]

Can we assume that the logo_uri and background_image_uri are actually URLs that supports Data URL Scheme (e.g.: data:image/png;base64,...)

[cvarjao]

I think we need to call out allotted image sizes (logo, backgrounds) and how they are scaled up/down

[swcurran]

Updates made to the RFC per the comments received. I still want to add the Credential Branding Guide to this RFC, and to deprecate/archive the existing overlays RFC as part of this PR.

[knguyenBC]

In regards to the primary and secondary attribute, there's a few usability concerns for in-person interactions. In user testing, it's been observed that people instinctively show the digital credential rather than go through the scanning process and there's concerns that adding a primary and secondary attribute to the front facing credential design will encourage this behaviour.

That being said, we've also noted that people prefer to have a recognizable attribute to their credential. For example their student ID should have their name.

Then there's the concern with real estate. The more we add to the credential itself, the more busy it'll look and the focus shouldn't be about the credential.

If the goal is to allow issuers differentiate between credentials of the same type and to help users recognize their credentials, I wonder if there's a different solution for that.

[swcurran]

Significant update to the RFC. AFAIK, other than applying feedback, the only remaining requirement for completing this RFC is the conversion of the Style Guide to Markdown format.

I would definitely appreciate a serious review of this PR by those involved in OCA for Aries. @cvarjao @foxbike Tim B.

[swcurran]

Added the OCA for Aries Style Guide. Changed the "branding" overlay to be a Meta overlay that has the language code "branding". Updated the instructions for creating and maintaining an OCA Source file, and generating an OCA Bundle from the source file.

[swcurran]

@TelegramSam -- I'd like to go over this in an upcoming Aries Working Group meeting if you can add me to the schedule.

[pknowl]

@swcurran - From a data harmonisation perspective, adding anything other than ISO 639 language codes [see link] as values for the "language" attribute won't fly. However, adding branding assets into a language-agnostic schema-level overlay (as opposed to an existing language-specific schema-, attribute-, entry code-, or unit-level overlay) makes sense. Furthermore, as OCA is such an extensible and scalable architecture, there is scope to add several new overlay types without having to shoehorn requirements into existing ones.

The current OCA Technical Specification [see link] shows a delineation of "Semantic", "Inputs", "Transformation", and "Presentation" overlay categories. However, the next version of the spec will likely see that delineation changed to "Collection" (i.e., overlays for capturing metadata to enable data context to be preserved at the point of collection), "Validation" (i.e., overlays for capturing metadata to allow validation checks between format definitions and data inputs), "Transformation" (i.e., overlays for capturing metadata to enable transformation mapping from source to target schemas and datasets), and "Presentation" (i.e., overlays for capturing metadata to allow the strong binding of presentation assets to transient data objects (e.g., forms, credentials, etc.)).

Over the past two months, that reasoning has come about through valuable discussions in the OCA community. It aligns the conceptual modelling of the data management and technology leads.

For some neat noodling on Presentation-type overlays, Andrew Slack from SICPA put forward three new overlay types for review in the following RWoT paper. The naming aside, the methodology is in keeping with pure OCA methodology. In other words, his suggestions refrain from shoehorning required capture requirements into existing overlay types that don't necessarily fit those requirements. Head straight to Appendix B of the paper.

https://github.com/WebOfTrustInfo/rwot11-the-hague/blob/master/final-documents/data-exchange-agreements-with-oca.pdf

In short, we have more freedom than we had initially thought possible. OCA's main task is to ensure data and metadata integrity [see link]. The architecture is robust yet flexible enough to undertake this ambitious mission elegantly.

[swcurran]

Regarding this:

@swcurran - From a data harmonisation perspective, adding anything other than ISO 639 language codes [see link] as values for the "language" attribute won't fly. However, adding branding assets into a language-agnostic schema-level overlay (as opposed to an existing language-specific schema-, attribute-, entry code-, or unit-level overlay) makes sense. Furthermore, as OCA is such an extensible and scalable architecture, there is scope to add several new overlay types without having to shoehorn requirements into existing ones.

Agree that it is a hack. Is there going to an Overlay added to the core spec to do this? Or should we go back to using a "branding" overlay name?

From a practical aspect, we want the OCA Parser tool to support as much of this as possible. For now, we can simply rename the overlay after generation, but it would be nice to have a way to support this WITHOUT changing the tool. For such a minor adjustment, it would be painful to have to fork the OCA Parser.

[swcurran]

Regarding this from @pknowl :

The current OCA Technical Specification [see link] shows a delineation of "Semantic", "Inputs", "Transformation", and "Presentation" overlay categories. However, the next version of the spec will likely see that delineation changed to "Collection" (i.e., overlays for capturing metadata to enable data context to be preserved at the point of collection), "Validation" (i.e., overlays for capturing metadata to allow validation checks between format definitions and data inputs), "Transformation" (i.e., overlays for capturing metadata to enable transformation mapping from source to target schemas and datasets), and "Presentation" (i.e., overlays for capturing metadata to allow the strong binding of presentation assets to transient data objects (e.g., forms, credentials, etc.)).

This is not really overly relevant to this RFC, but my $0.02CDN is that many of the (current) overlays are applicable across categories, so I'm not sure it is very helpful to categorization the overlays. For example, in putting together this RFC, we selected the Overlays that were most helpful to an entity receiving data and an OCA Bundle. The fact that some of those are in the "collection" category and we are using the OCA primarily for presentation is irrelevant. As long as the issuer is providing data matching their overlays, we're happy.

[tbloomfi]

For the meta layer, we might want to consider the following:

• offer_expires - this would allow the wallet to display an offer expiry message on the offer screen. The attribute could also be used to clean up older offers. The controller would enforce the expiry but this could be good for usability. Didcomm v1 has an optional decorator expires_time (in v2 this is part of the message header) that could also be used, but the meaning is not really the same. The V2 spec does include a comment that protocols could "nuance" this header in their respective spec.

• credential_privacy_policy_url - This may also be part of the machine-readable governance or perhaps a specific consent receipt issued as a supplement. Verifiers would also need to share privacy policies. This could be a fallback.

[swcurran]

@tbloomfi -- a group of us talked about your suggestions and have this response:

• offer_expires -- we think that really belongs in the issue-credential protocol. This could be handled by adding support for RFC 0032 Message Timing decorator. Or, it could specifically added to the credential-offer message (although that seems unnecessary). Either way, we don't think it belongs in the OCA Bundle.

• credential_privacy_policy_url -- definitely one that could be added. Would it make sense to expand the context to terms_and_conditions_url, which would encompass the Privacy Policy and any other items the users wants to share?

A caveat on this. As noted in the propose RFC, the use of links in the OCA Bundle could be used as a tracking mechanism. Please see that part of the RFC. Here's a link in the pull request branch. I will expand that section a bit to include links.

[TelegramSam]

I think the concept of the card view is good, but struggle with the header. That header design presumes some things about the overall app layout that may not be true for all current designs, or future designs either. I DO think the concept card layout is likely to be much more tolerant of layout changes etc, and so inflicts fewer opinions on the overall app layout.

[pknowl]

Regarding terms_and_conditions_url idea, I would treat it as a separate OCA bundle. Have a look at the Data Agreement Specification. We could build a data agreement using OCA methodology and then strongly bind that new bundle to the original one.

[tbloomfi]

@swcurran expiry timer seems like a better option. Also terms_ and_conditions_url works. It does not need to be an explicit privacy policy.

A question around problem reports has also come up while working with an issuer that has done a great job documenting corner cases - for example, what happens if the credential offer is accepted after the data has changed or the holder is no longer eligible to receive the credential?

The proposed approach is to use a problem report. Seems simple enough until the translation of the message is considered. In addition, the issuer may want to use error codes which would need to be mapped to user-friendly messages in the wallet. Is there a use case here for OCA to handle error codes and the display of localized error messages?

For two languages the issuer could just include both languages in the message, but not a very clean solution.

[pknowl]

In the Decentralised Semantics WG call on January 26th, one of the agenda topics was ...

What is considered "Metadata" in OCA?

The key takeaways were:

(i.) Metadata (as defined here) is essential for cataloguing but, for the most part, doesn't require new overlay types to capture that information.

(ii.) With OCA, we differentiate between "data" and "metadata" as follows:

• "data" is inputted data into a semantic structure logged at a given moment in time (i.e., event-specific);
• "metadata" is supporting information captured by the semantic structure that brings additional definitional or contextual meaning to "data".

So, what does this mean in practice?

As with any free-form inputted data, OCA enables the flagging of attributes capturing information that describe a parent schema (i.e., descriptive, administrative, or legal information about the parent schema that might be deemed sensitive).

In OCA, associated metadata schemas capture this information as "data" that describes a parent schema. As with any other OCA bundle, you would layer in "metadata" for the attributes in those metadata schemas. In other words, multi-language translations, formatting definitions, etc., can add additional definitional or contextual meaning to the information describing a parent schema.

With that in mind, Human Colossus is working on a semantic engine project with a research institute in Canada, working through their cataloguing requirements, which will inevitably result in us defining a couple of metadata schemas using the categories described in the "Metadata" Wikipedia definition [e.g., Administrative metadata schema, Legal metadata schema, etc.]. Then, once we've got something solid in place, we'll relay our findings back to the DSWG to discuss the inclusion of tabular definitions of the defined metadata schemas as appendices in the next version of the official OCA Technical Specification.

I wanted to inform the OCA for Aries group as I'm sure this information will also be useful for credential object cataloguing.

@swcurran - In an effort to ensure that the words "meta" and "capture" are treated as sacred to the Semantic domain, the current "Meta overlay" will likely be renamed to "Descriptive overlay" in the near future. As per our discussions, I've recommended that we split that overlay type into:
(i.) Descriptive (language-specific) overlay
(ii.) Descriptive (language-agnostic) overlay
See https://wiki.colossi.network/en/Community/Working-Groups/DSWG/Meeting-Notes/2023-01-26

[swcurran]

Discussed on the Aries Working Group call on 2023.06.28 and there was agreement to merge.

We need an approval after some additional updates made:

• Updated the source (The Human Colossus Foundation) of the original RFC 0013 Overlays that is to be retired with this PR.
• Added a Meta Overlay "watermark" item, and meaning -- to be used for putting a Watermark (in multiple languages) over the credential when needed -- especially for use when displaying a non-production version of a credential (e.g., for testing).
• Added the "stacked" view of the credentials.

@TelegramSam @dhh1128 @dbluhm @andrewwhitehead @TimoGlastra -- could I get an approval, please?