OCA for Aries needs in creating an OCA Bundle generation process

[swcurran]

We've done more work on the OCA for Aries RFC for using OCA to "make verifiable credentials beautiful" in Aries agents. This ticket is to express the needs we have in creating OCA Bundles from source for use in Aries.

What we need is a way to manage the OCA Source so that it can be put into version control (e.g., GitHub) such that a CI/CD pipeline task (likely a GitHub Action) can be used to automatically create the OCA Bundle for the given source.

The source needs to come from two places:

• The current OCA Excel Source file is excellent, as it makes the translations and adding languages really easy, and friendly. We are happy to continue to use that as the primary source.
• A second source is required that contains a custom OCA Overlay (aries/overlays/branding/1.0) that includes a series of name/value pairs, some of which are base64 images that are too large for an Excel cell. I'll propose some as generic as possible approaches for this source data.

What is needed is a utility that operates essentially like the current Excel parser, but that includes a generic way to pull in additional overlays before producing a complete, valid OCA Bundle, with all of the SAIDs in the Bundle accurate.

Here are the ideas that I have for managing the second source (or more) overlays:

• (1) Add an option to the parser for loading a JSON file of overlays to the OCA Bundle produced from the Excel file. The JSON should be an array of overlays, with the capture_base and digest fields set to "". On pulling in the file, those two fields would be populated. This is a general purpose utility in that there could be many reasons why some overlays would be in a separate file and need to be merged into an existing OCA Bundle. This is also a minor variation on the current features around --credential-layout, and could even replace that feature by putting the credential-layout into a JSON file, with a YAML field that is processed to produce the appropriate JSON OCA Bundle output.

  • For example: parser parse oca --path ~/tmp/OCA4Aries.xlsx --json-overlays branding.json >OCA4Aries.json

• (2) Add a separate utility that recalculates all of the digests and capture_base values for an OCA Bundle. In our case, we would generate the OCA json from the Excel file, add in our "extra" overlay, and then run the utility. This leaves the creation/management of the overlays to the controller, yet they can always produce the proper SAIDs in the OCA Bundle.

  • For example: parser process oca --path OCA4Aries-Input.json >OCA4Aries.json

• (3) Use the new OCAFile concept (is it available for playing with?) with support for processing an OCA Excel file to produce part of the OCA Bundle. In the OCA for Aries case, we would have an OCAFile that contains:

  • A command to process an Excel file to produce the OCA Bundle
  • A series of commands to add our branding overlay. Since the OCAFile is a separate text file, the size of the data elements for the images would not be an issue.

I suspect the easiest approach would be (2), but (3) might be a good longer term target. Overall, the goals I see are:

• to keep the Excel OCA Source capability, since it is very friendly to the likely creators of multilingual OCA Source data.
• provide a way to add to the Excel data in a coherent way
• ensure that the process can easily be executed as part of a GitHub actions type pipeline

[swcurran]

I have documented the current "recommended" way to generate an OCA Bundle for Aries. The full detail is in this section of the RFC. Here is the short version:

• Get the latest template Excel file from the oca-parser-xls repo
• Fill in the Main tab, and a language tab for each language-country code to be supported.
• Maintain a separate "branding.json" file containing the Aries-specific Branding Overlay. Here is an example file.
• Generate the OCA Bundle from the Excel to a json file (command: parser parse oca --path <OCA Excel File> > <output Excel JSON OCA Bundle>)
• Use jq to merge the Branding Overlay JSON into the Excel JSON to create the final OCA Bundle (command: jq ".[].overlays += $(cat BRANDING-JSON-FILE)" OCA-EXCEL-FILE > OCA-BUNDLE-JSON-FILE). Here is an example output OCA Bundle JSON file.

While this works, the capture_base item in the Branding Overlay must be manually updated each time it changes, and I don't know of a way to update the digest item in the Branding Overlay.

FYI - I experimented with using the saidify command in the keripy CLI to create the Branding Overlay digest, and it seemed to create a different SAID. Any ideas why?