Consider ways to improve UI as it pertains to `requiredPaymentDetails`

mistermoe commented 6 months ago

requiredPaymentDetails is part of the PaymentMethod type used for Offering.payinMethods and Offering.payoutMethods. the value of requiredPaymentDetails is a JSON Schema that's used to convey the properties that need to be collected from Alice and submitted as part of an RFQ.

One of the original motivating factors behind selecting JSON Schema for requiredPaymentDetails was so that client apps could dynamically render the schema as a form to be populated by Alice. Being able to do this effortlessly while remaining confident that the minbar UI is at least considered "usable" is especially important given that tbDEX aims to remove the burden associated with n bespoke payment API integrations.

The properties included within JSON Schema will likely be snake cased or camel cased and not intended to be rendered on screen as-is. We should think through how to surface UI friendly field names & descriptions in addition to an answer for internationalization.

Three approaches come to mind and they all have trade-offs:

JSON Schema Annotations

JSON Schema has the concept of annotations which are described as keywords, that aren't strictly used for validation, but are used to describe parts of a schema. The specification includes title and description as annotations. We could include spec text that suggests using title if present as the field name to render on screen in addition to description. Unclear whether this approach makes internationalization easier or harder.

Metadata

Another approach that comes to mind is to change the structure of requiredPaymentDetails to something like:

{
    schema: <json schema>,
    metadata: <details abt fields in schema>
}

The structure of metadata could be something like:

{
  <propertyName>: {
    title: "Property Name",
    description: "Some helpful description to render"
  }
}

<propertyName> is the name of the property in the JSON schema.

Benefits

decouples rendering metadata from json schema
allows us to add additional properties in the future
relatively easy logic wrt form rendering

Drawbacks

the above structure is bespoke. wondering if there's prior art or pre-existing standards we can lean on here instead of coming up with our own

Presentation Definition Approach

Presentation Definition Input Descriptors from the Presentation Exchange specification address a similar problem with the input_descriptors[*].fields[] type where each field element contains an optional name, description, type and filter. filter is its very own json schema. If we took this approach we'd change requiredPaymentDetails from a JSON schema to an array of field-like elements. Instinctively, not the biggest fan of n json schemas, one per field, but it does work

ethan-tbd commented 6 months ago

discussed with @jiyoontbd and came to the conclusion that sticking with JSON schema with annotations is the best solution here. only change needed would be to update the spec to suggest using title and description for each field.

as a note, we are not currently using description in client applications (only title is used as the label for each field)

selfissued commented 6 months ago

Internationalization considerations are the most important thing to deal with here, as I see it. In general, whenever you include text strings intended for display for human consumption, the there has to be a way of specifying them for all the languages that matter for your use cases.

Such solutions normally employ BCP 47 [RFC5646] language tags. For instance, see how https://www.rfc-editor.org/rfc/rfc7591#section-2.2 uses them using a fragment-like syntax added to property names. See this example:

For example, a client could represent its name in English as "client_name#en": "My Client" and its name in Japanese as "client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D" within the same registration request.

For what it's worth, this approach was invented by OpenID Connect, and is described at https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts .

The internationalization would have to be applied to any of the three syntaxes described above. I personally think the metadata approach is closer to what other specs are doing, and so I'd favor it, but I'm open to a broader discussion on the possible choices.

decentralgabe commented 6 months ago

I prefer the metadata approach and agree this is a useful construct for localization, which should be considered before we stamp a first version of the spec.

KendallWeihe commented 6 months ago

Original intuition is to use existing functionality, so towards the JSON Schema Annotations

But defer to the wisdom above about internationalization, and how that doesn't fit into Annotations

Proposal: rename metadata to markup as to make it clear this is scoped to presentation in a GUI

TBD54566975 / tbdex