Manual input hierarchy file format

We use a data-driven approach to define the many forms that make up the manual input feature in CityCatalyst. The data is stored in app/src/lib/util/form-schema/manual-input-hierarchy.json.

Identifiers in this file are mostly in kebab-case (lowercase words connected by dashes). Translations for these words are found in the localisation file at app/src/i18n/locales/<language>/data.json.

The manual input hierarchy file is a single JSON object. It has entries for each subsector-scope reference number in the GPC, with keys being the reference number:

{
   "I.1.1": { ... },
   "I.1.2": { ... },
   ...
   "II.2.1": { ... },
}

Each entry is an object with these properties:

• methodologies. An array of possible emissions estimation methodologies. Each methodology is a JSON object with the following properties:
  • id. A unique identifier for the methodology. Used to show the title of the methodology on the methodology chooser screen. Adding "-description" to the end gives the translation key used for showing the methodology description.
  • activityTypeField. For some reports, we need to show a single field to sort the activities -- often a "fuel type". This identifies the extra field (see below) to use. Note that this only works if there's only one kind of activity in the methodology.
  • inputRequired. These are translation keys for the required input needed for this methodology. Note that these are different from the labels of the extra fields, and may be a long clause or a full sentence. These are not used for data validation; only for making a list of required inputs in the methodology chooser.
  • disabled. A boolean value. If it's true, the methodology will be shown but not enabled in the methodology chooser.
  • mostUsed. A boolean value. If it's true, the methodology will get a little "most used" tablet to indicate that it's a preferred methodology. There should (?) be only one methodology that is "most used" per subsector-scope.
  • activities. An array of possible activities to save for this methodology. An activity value is a measurement that is not directly greenhouse gas emissions that can be converted into emissions values using emissions factors or another formula. Most but not all methodologies have only one type of activity. Each activity is an object with the following properties:
    • id. A unique identifier for the activity. Not (?) used as a translation string, but used for storing activity data.
    • group-by. An extra field ID (see below) used to group the activities on the activity list page.
    • unique-by. An array of extra field IDs for determining the uniqueness of an activity. No two activities can have the same values for all of these fields. Fields that aren't in this array can be duplicated.
    • activity-title. The label to use for the activity value.
    • units. An array of possible units for this activity value. These can be multiple measurements of the same dimension (liters and cubic meters are both ways of measuring volume) or different dimensions (liters are volume, kilojoules is energy).
    • default-units. The default value to show in the units field.
    • extra-fields. Every activity form has some default fields (activity value, emissions factor, data quality, ...). These are extra fields that define the sub-category of activity used for measurement. This is an array of JSON objects. Each object has the following properties:
      • id. ID for the extra field. This is used for the label on the form, and is also stored with the activity value.
      • emissions-factor-dependency. A boolean. If this is true, when this extra field's value changes, the emissions factor is automatically (?) changed to match it.
      • type. Defines the input type. One of "text" (free-form text), "number" (a floating point number), or "percentage-breakdown" (show a list of options with possible percentages). If not set, the input field will be a dropdown box using the values from options.
      • required. A boolean. If false, this value will not be required to save the activity. Default true (?).
      • options. A list of translation strings/unique IDs for the available options in the drop down selection (only for default input type).
      • multiselect. A boolean. If true, with the default input type, multiple values can be selected.
      • exclusive. An ID, one of the values in the options array. If an activity is made using this ID for the extra field value, it counts as unique for all other values. For example, if the vehicle type is "all", then once this activity is saved, no other vehicle type can be used (assuming no other uniqueness values). The extra field ID should be in the "unique-by" array.
      • units. For the "number" input type, this is an array of ID strings that can be units for the extra field.
      • default-units. for the "number" input type, this is the default choice for the units.
      • min. For the "number" input type, a minimum value.
      • max. For the "number" input type, a maximum value.
      • total-required. For the "percentage-breakdown" input type, the value that all the percentages should add up to. Default value 100, and hard to imagine what other value this could be.
      • subtypes. For the "percentage-breakdown" input type, the IDs of possible sub-types to use.
      • dependsOn. For the default dropdown box type, this provides a dropdown that has contents dependent on another extra field. The dependsOn property is the ID of the property it depends on. The extra field should also have a dependentOptions property.
      • dependentOptions. For a dependent extra field, this is an object mapping the values of the depended-upon extra field to the values that should be shown in the dependent field. For example: {"other-1": ["this-1", "this-2", "this-3"], "other-2": ["this-4", "this-5"]}. If the other field has value other-1, this field should list only this-1, this-2, and this-3 in the dropdown.
  • suggestedActivities. When the activity creation screen is shown for the first time, there are a few "suggested activities" with pre-filled values listed on the page. This array defines those pre-fills. Each array element is a JSON object with the following properties:
    • id. The ID of the activity to use. Most methodologies only have one activity type, but if there are multiple ones, this identifies which one. Note that multiple objects in the suggestedActivities array can have the same id value; it's not an identify for the prefill group, but an identifier for the activity form to use.
    • prefills. An array of key-value pairs to show by default when this suggested activity is chosen. Each item is a JSON object with the following properties:
      • key. The ID of the extra field to pre-fill. It should exist for the activity! This feature probably (?) only works for default input type extra fields; no "number" or "text" input types please!
      • value. The ID of the option to choose. This only works for the default (dropdown) extra field type.
• directMeasure. Every subsector-scope should have one directMeasure option. The forms used here are different than for activity values; namely, the emissions values are entered directly (thus the name). This field consists of a single JSON object with the following properties.
  • id. The translation key to use for the direct measure option in the methodology chooser. Usually something like "Direct measure". The description translation key is this ID plus "-description".
  • inputRequired. An array of translation keys for describing what input values are required
  • activityTypeField. Some reports organize results a single extra field, usually something like "fuel type". This property defines the ID of the extra field to use for those reports.
  • group-by. In the activity list page, the activities (even direct measure) are grouped by an extra field. This property defines which extra field it is. A single string, the ID.
  • extra-fields. An array of extra fields JSON objects to use in the direct measure form. Can be any (?) of the values used above for extra-fields for the activity forms.