Discussion for proposal 0002 - OCA attribute ordering overlay

[blelump]

As a part of the review process, anyone willing to provide his comments or insights to OCA attribute ordering overlay, please share it in this thread.

[blelump]

Hey @pknowl @ryanbnl . Below is the review of the ordering overlay proposal done by the tech team, namely @olichwiruk, @mitfik, and @blelump .

Presentation, so the spatial orientation of elements on the screen has always been challenging. Until now, no common standard has emerged to address this, and various providers serving user interfaces approach it in their way. Portability in this field does not exist.

Presentation is closely related to cognition, so the "mental action or process of acquiring knowledge and understanding through thought, experience, and the senses"[wiki]. The presentation comprises activities that are solely human-related. In essence, how a human, using a device with a screen, can benefit from digitalized information or enhance it. Here, the presentation branches to:

1. ability to add new digital information,
2. ability to read digital information.

In 2023, for adding new digital information, we still use forms to capture it from humans. Forms, while still serving their job, are pretty primitive in the sense of how machines could assist humans with intent digitalization that is expressed using words.

The process of form fulfillment expects clear and structured and often categorized answers from the form filler. Its mechanics also depend on how the form elements are arranged within the rectangular area of a device that displays them on the screen. In other words, the arrangement of form elements and their spatial orientation within the available area is often device-dependent or screen size-dependent. No common standard defines how form elements should be displayed on the screen. Depending on the form's complexity and structure (i.e., potential relationships between elements), a columnar approach is widely used where each column serves as the rectangular area for a cohesive part of the form. In many cases, simple/medium complexity forms use one-column approach, where form elements display one after another vertically.

We discussed the side of the capture part of the presentation. However, once the information is captured, several possible approaches exist to display it on the screen for further review or analysis. The spatial arrangement of the information on the screen fundamentally depends on the cognition that is the most "digestable" capability to understand the information. Cognition involves user experience (UX) and user interface (UI) to achieve the most digestable level of information consumability. For digital information that consists of multiple records, tabular representation might be best fit. On the other hand, a single record that expresses a well-known concept from physical space, i.e., a capability like a driving license, digitally can be expressed much like its physical counterpart. Both approaches could apply to the same information but in different contexts. For example, driver's license management might demand tabular representation for a person who manages them. However, for an individual who is the license holder, it is expressed using more visual techniques.

The proposal for ordering OCA attributes is solely a presentation layer concern, so how to display them on the screen. As said above, presentation, so the spatial arrangement of elements within an area, is a difficult topic on its own. The proposal assumes one-dimensional ordering and focuses solely on the read part of the digital information. It furthermore does not explain how it eventually converges with layouts and the overall arrangement of elements on the screen that express digital information. In essence, what is the big picture for the general presentation problem as it heavily impacts arrangement and, therefore, also ordering.

Leaving unsolved the arrangement and ordering current and future relationships, it is inevitable to further segregate the overlays according to their belongingness. On the one hand, to isolate and protect what is already there and on the other, to keep smaller cohesive parts responsible for one thing. Therefore, a clear separation of OCA Core (Data Capture Language) from OCA Presentation (Data Presentation Language) is a must-have.

What is also clear is that ordering, as a part of the presentation, shall not become a part of the core. We recommend opening a new family of presentation-related overlays that reflect Data Presentation Language. We also recommend introducing explicit ordering by utilizing vectors, where the order of elements in a vector is the canonical order. It primarily simplifies the reading and makes it unambiguous. A hash map, on the other hand, leaves space for ambiguities, i.e.:
{"lastName": "1", "emailAddress":"3", "phoneNumber": "2"}
vs.
{"emailAddress":"3", "phoneNumber": "2", "lastName": "1"}.

Unless explicitly told, hashes do not preserve the keys' ordering. In the above example, while the end product computed by a machine is the same, it challenges human perception.

We furthermore leave for open discussion a new concept: container. Container is a concept borrowed from UI, encompassing part of the screen, and is embedded into a higher-level concept (row, column, widget -- the name fluctuates across frameworks). Containers address the requirements of arrangement by introducing cohesive parts of elements that are ordered. Containers are an abstract concept and require further work (see below) to dismiss the end-user from manual intervention of how to consume them. Containers also leave space for future enhancements/work related to the overall presentation.

Final example

{
   "capture_base":"E6dVEHR0obA673USLKJpuvv6qZ9pKnKd-iSCHrsHBue4",
   "type":"spec/overlays/<role> (presentation)/ordering/1.0",
   "containers": {
       "<container label>": [
          "customerID", "firstName", "lastName", "emailAddress", "phoneNumber"
       ],
       "<another container label...>": [ "..." ]
   }
   
}

Fig. Ordering overlay equipped with the recommendations

Further related work

• Currently, the label overlay contains categories that serve as N-th-level deep sections. These sections are part of the overall arrangement that constitutes the spatial organization of information. Inevitably, a template that is about a spatial arrangement emerges from these considerations. The template splits all available areas into N-th-level deep sections, each displaying a container that preserves the ordering of a cohesive subpart.
• Introduce presentation base that look as follows:

  {
    d: "digest",
    bd: "oca bundle digest",
    c: [// containers 
        "container-name-1",
        "container-name-2",
        ...
    ]
  }
  

  By adding a presentation base, we properly segregate responsibilities and introduce containers that, by presentation overlays, will get additional characteristics, much like attributes get their characteristics via core overlays.

[pknowl]

The DSWG has discussed the technical proposal suggested above. Separating presentation requirements from collection requirements aligns with our thinking. [Check out the draft "Presentation Overlays User Guide" DSWG members were noodling on over the Summer [link]].

Moving forward. Will the Technology Council create an official RFC for the suggested proposal?

Note @ryanbnl 's comment below regarding the recommendation, "We also recommend introducing explicit ordering by utilizing vectors, where the order of elements in a vector is the canonical order."

[ryanbnl]

The issue I have with using vectors is based on experience implementing sort for different cultures. You'll never completely avoid that (tooling will implement it how they wish) but we should not specify "use a vector", but "we will rely on implicit ordering implemented using algorithm xyz". Then implementations can use the Collection implementations in their language which support that ordering, or implement a custom ordering/comparitor.

[blelump]

There is yet another angle that we should have discussed in the review. This is:

digest({"lastName": "1", "emailAddress":"3", "phoneNumber": "2"}) 

is different than

digest({{"emailAddress":"3", "phoneNumber": "2", "lastName": "1"}})

In other words, to ensure proper serialization ordering, we inevitably enforced the order of tuples in the representation. We, in fact, imposed a comparator that is also implementation-dependent. The implementation guidelines must appear in any way to adequately address the canonical form of the Bundle upon what we calculate the digests. The canonical form imposes the ordering, among other things. These guidelines shall not be part of the spec because they are too specific. Currently, it is not addressed anywhere.

To sum it up, due to the additional requirements imposed on any map-based collection to enforce the ordering, an iterable slice in memory that can be represented as an array of elements is cheaper and easier to read if represented, i.e., in JSON. What type of "iterable slice in memory" is in use is implementation-dependent. We impose that it does preserve the order, and all languages have such types.

[ryanbnl]

Agreed, we need to formalize the specification for the serialization and comparison in more detail. Should we make an issue in this repo to track that or somewhere else?

[carlyh-micb]

Where will work be done on the presentation overlays? My users have a significant need for this and I would like to contribute. Thank you, Carly ----------------------------------------- Carly Huitema ***@***.***

…

On Fri, Nov 10, 2023 at 4:43 AM Ryan Barrett ***@***.***> wrote: Agreed, we need to formalize the specification for the serialization and comparison in more detail. Should we make an issue in this repo to track that or somewhere else? — Reply to this email directly, view it on GitHub <#26 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ANJWBQZDA6FM5SIYOPZDMNLYDXZL3AVCNFSM6AAAAAA5UNCHTSVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM3TKMZRHAYTQ> . You are receiving this because you are subscribed to this thread.Message ID: <the-human-colossus-foundation/oca-spec/repo-discussions/26/comments/7531818 @github.com>

[blelump]

@carlyh-micb , I suggest elaborating on the needs (except the ordering) during OCAWG meetings. Here, we discuss the ordering part.

[pknowl]

I have not seen an official RFC for presentation ordering anywhere, yet a repo has already been developed for the work.

https://github.com/THCLab/oca-ordering/tree/main

@blelump, Can we get a status update from the tech team?

[carlyh-micb]

As I understand, ideas can be tried out technically before being accepted as part of the standard.

[carlyh-micb]

When a user is entering data, ordering can have a significant impact on how the user answers questions. This is especially relevant in form questions.

Questions that are asked early in a questionnaire can have effects on how survey users answer later questions (called order effects). Effects are so significant that for long term study, after a survey has been reordered, answers can be called into question when their context (ordering) has been changed. Order effects can also be present in the presentation of lists of options (e.g. entry codes and entry labels in OCA). See PEW summary for information which summarizes examples from the scientific literature.

I see OCA bundles containing three major things:

Content

• Capture Base
• All the other overlays and not conditional overlay

Structure

• Ordering of attributes
• Conditional logic
• For example, forms can become very complex.
• E.g. if you answer no in the above question, answer these next 6 questions.
• E.g. if you selected “angry” for question 5, answer this next question.

Style

• Colours (e.g. branding overlays)
• Absolute position (a.k.a. create a picture pixel by pixel)
• Appearance in different viewers?
• Accessibility?