1

Background

In an expert system, configuration users may be able to define custom behavior by way of business rules or decision tables. For those to be meaningful, the system offers its domain-specific data model as input. This kind of data model may be fairly complex and subject to changes over time, which means it is hard to document in a usable way without risking it getting outdated quickly.

I don't expect users to consult long lists/tables in a manual to find what they are after. The same goes for some big/separate documentation like Javadoc or JSDoc. Instead, it should be available in-line together with the business rule or decision table being defined.

Approach

  1. Avoid overwhelming the user while allowing to traverse the complex hierarchical data structure by not displaying the full tree but rather only the sub-elements of a particular selection in a column view like in the Mac OS Finder: Mac OS Finder: Column View
  2. Utilize a standard way of describing a data structure that can be generated from code (like Javadoc/JSDoc): JSON-Schema

You can find the current state of my component on GitHub and even play around in its Storybook.

Challenge

In contrast to a file system (as represented by the Finder's column view), such a domain-specific data model can contain optional elements. This can be represented in a JSON-Schema in multiple ways – mainly as anyOf or oneOf sub-structures.

E.g. a customer may be a private individual (with a first name, surname, date of birth, etc.) or company (with a single name, an organization number, etc.) – on an invoice the customer may be represented as:

Invoice: {
  properties: {
    Customer: {
      oneOf: [
        { $ref: "PrivateIndividual" },
        { $ref: "Company" }
      ]
    }
  }
}

How to meaningfully show these alternatives?

From the top of my head, I can think of the following approaches but am not fully convinced by any one of them, especially with the anyOf in mind where sub-structures may even be combined (instead of the exclusive oneOf alternatives):

mockup

download bmml source – Wireframes created with Balsamiq Mockups

  • How can these be improved?
  • Is there a better one that I simply missed?
  • How to handle anyOf?

EDIT: While not an answer as to how this may be represented best, just wanted to mention that I ended up implementing both options #1 and #3 (and their combinations) in the linked component. After having played around with it for a while, I found use-cases for both approaches (but treating option #3 as the default as it more clearly indicates the original structure in the schema definition).

  • This is a UX site. We're focused on the "what to display to the user" not "how to code the display." – Mayo Mar 19 at 20:57
  • Hi @Mayo That's what I'm after. I'm confident to find a way "to code the display", but I'm out of ideas regarding "what to display to the user". – Carsten Mar 19 at 20:58
  • @Carstein - I thought so. As you're a new member I was just making sure. :) – Mayo Mar 19 at 21:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.