Metadata JSON Files

2024-04-18

Premium Feature — Available in the Enterprise Edition of LabKey Server. Learn more or contact LabKey.

A metadata file written in JSON is used to configure the fields and categories for document abstraction. The file configures the field categories and lists available, as well as what type of values are permitted for each field.

Metadata JSON files may be used to control a variety of implementation specific configurations, such as understanding common fields of a specific type of cancer report or case file. Implementing conditional or branching logic (if this is true, show these extra fields) can also be included using metadata.json files.

Metadata Fields
Basic Example
Enable Multiple Values Per Field
Conditional or Branching Logic

Listener Configurations
Handler Configurations
Conditional Logic Examples

Metadata Fields

The metadata JSON file defines fields for abstraction using these properties:

field: (Required/String) The field name.
datatype: (Required/String) The type of the field.
closedClass: (Optional/Boolean) If true, the field is closed (only values on a pulldown menu can be selected). Otherwise and by default, arbitrary values can be entered into the field, whether or not they are on the expected list.
diseaseProperties: (Optional/Array of properties) The group of disease diagnoses for which this field is presented to abstractors. For example, if the field is shown for all types of disease, with four options on a dropdown list, the field might look like:
```
"diseaseProperties":[
  {"diseaseGroup":["*"],
      "values":["brain","breast","GI","GU"]
}]
```
multiValue: (Optional/Boolean) If true, the field supports entry of multiple values. Otherwise, and by default, each field accepts a single value.
hidden: (Optional/Boolean) If true, the field is hidden in the initial state and only shown if triggered by conditional logic. Otherwise and by default, the field will be shown to the abstractor from the beginning.
disabled: (Optional/Boolean) If true, the field is shown, but disabled (grayed-out) in the initial state and only enabled to receive input via use of conditional logic. Otherwise and by default, the field will be enabled from the beginning.
listeners: (Optional) See Conditional or Branching Logic below.
handlers: (Optional) See Conditional or Branching Logic below.

Basic Example

Download this sample file for a simple example:

metadata.json

Here, a Pathology category is defined, with table and field level groupings, and two tables with simple fields, "ClassifiedDiseaseGroup" and "Field1", a boolean.

{
  "pathology": {
    "groupings": [
      {
        "level": "table",
        "order": "alpha",
        "orientation": "horizontal"
      },
      {
        "level": "field",
        "order": "alpha",
        "orientation": "horizontal"
      }
    ],
    "tables":[
      {"table":"EngineReportInfo",
        "fields":[
          {"field":"ClassifiedDiseaseGroup",
            "datatype":"string",
            "closedClass":"False",
            "diseaseProperties":
            [
              {"diseaseGroup":["*"],
                "values":["disease1","disease2","disease3"]
              }
            ]
          }
        ]
      },
      {"table":"Table1",
        "fields":[
          {"field":"Field1",
            "datatype":"string",
            "closedClass":"True",
            "diseaseProperties":
            [
              {"diseaseGroup":["*"],
                "values":["Yes","No"]
              }
            ]
          }
        ]
      }
    ]
  }
}

Enable Multiple Values per Field

To allow an abstractor to multiselect values from a pulldown menu, which will be shown in the field value separated by || (double pipes), include the following in the field definition:

"multiValue" : "True"

Conditional or Branching Logic

Conditional or branching logic can be used to control the fields and options presented to annotators. For example, options could vary widely by disease group or whether metastasis is reported. To introduce conditional logic, use listeners and handlers within the metadata JSON file.

To enable or disable the field upon initial opening of the abstraction/annotation screen, use the disabled boolean described above.

Listener Configurations

A listener configuration includes the following properties:

field: (Required/String) The name of the field to listen to and respond to changes in.
tableName: (Optional) Specifies the table in which the listened-to-field resides. Defaults to the same table as this field definition resides in.
recordKey: (Optional)

If record key level grouping is configured, specifies the record key of the field to listen on. This can be used in conjunction with tableName to target a very specific field that this field definition needs to respond to.
If omitted, this will default to the sub table that this field definition resides on.
An optional wildcard value of "ALL" can be specified which will listen to all subtables for the table associated with this field definition.

handlers: (Required/Array of handler configurations) The configurations which define which changes to respond to and how to respond to such changes

Handler Configurations

values: (Required/Array of strings) The values to attempt to match on; can have explicit values or can be an empty array to match arbitrary input.
match: (Optional - Defaults to "EQUALS") Determines how the above values are to be interpreted for the specified action to be taken. This field is a string constant, options:

EQUALS - matches the exact values for either the array or single value
NOT_EQUALS
IS_NOT_BLANK - matches any (non-blank) value
EQUALS_ONE_OF - matches any of the values in the array
NOT_EQUALS_ANY_OF - does not match any of the values in the array

success (Optional) The behavior this field will exhibit if the value expression is matched. This field is a string with possible values ("ENABLE" | "DISABLE" | "SHOW" | "HIDE")
failure (Optional) The behavior this field will exhibit if the value expression is not matched. This field is a string constant ("ENABLE" | "DISABLE" | "SHOW" | "HIDE")

It is important to note the difference between the following paired settings in the handlers section:

ENABLE/DISABLE: These settings control whether a field is enabled to accept user input based on the success or failure of the condition.
SHOW/HIDE: These settings control whether a field is show to the user based on the success or failure of the condition.

Specifically, if a field is initially hidden, your success handler must SHOW it; enabling a hidden field will not show the field to the user.

Conditional Logic Examples

The following examples will help illustrate using conditional logic.

Scenario 1: You have two fields, "Metastasis" and "Cancer Recurrance", and only want to show the latter if the former is true, you would define the "Cancer Recurrance" field as:

{
    "field":"Cancer Recurrence",
    "datatype":"string",
    "listeners" : [{
        "field" : "metastasis",
        "handlers" : [{
            "values" : ["true"],
            "success" : "SHOW",
            "failure" : "HIDE"
        }
    ]
}

Scenario 2: A field called diseaseGroup is a multi-select type. You want to enable a field only if the selections : "brain", "lung", and "breast" are selected and disabled otherwise. Within the definition of that field, the listeners portion would read:

"listeners" : [{
        "field" : "diseaseGroup",
        "handlers" : [{
            "values" : ["brain", "lung", "breast"],
            "match" : "EQUALS",
            "success" : "ENABLE",
            "failure" : "DISABLE"
            }
        ]
    }]

Scenario 3 : You want a field to be shown only if any selection is made on the multi select field "testsCompleted". Within the field definition, the listeners section would look like:

"listeners" : [{
        "field" : "testCompleted",
        "handlers" : [{
            "values" : [],
            "match" : "IS_NOT_BLANK",
            "success" : "SHOW",
            "failure" : "HIDE"			// will hide if there is no selection
            }
        ]
    }]]