Config and constants conventions¶

Overview¶

This page covers the conventions TetraScience-maintained (common and client-* namespace) protocols follow on top of the config field reference in protocol.yml field reference: description wording, config ordering, and the two most common reusable config blocks (datetime and timezone parsing).

These conventions can optionally be followed for self-service private-* namespace protocols as recommended practices.

Guidelines¶

Prefix every config’s description with Optional. or Required., and state the default value or behavior explicitly — don’t leave the reader to infer it from required/default alone.
Order required configs before optional ones. This isn’t just readability: the order configs are declared in protocol.yml determines the order they render in the TDP pipeline configuration UI.
A config which is required: false with no default arrives at the task script as null. Either give it a default or handle the missing value in the task script.

Raw-to-IDS protocol conventions¶

For a protocol whose job is exposing a raw-to-IDS task script:

name should read <brand> <model> Raw to IDS, e.g. "Agilent TRS100 Raw to IDS".
config must include idsFileCategory, and the step must pass it through:

config:
  idsFileCategory:
    label: "IDS File Category"
    description: >
      Optional. Default is 'IDS'. You can use 'TMP', 'PROCESSED' or 'IDS' to
      overwrite the file category of the IDS file created by the raw to IDS
      task script.
    type: "string"
    required: false
    default: "IDS"

steps:
  - task: { ... }
    input:
      ids_file_category: $( config.idsFileCategory )

Common reusable config blocks¶

Datetime parsing¶

config:
  datetimeParsingConfig:
    label: "Datetime Parsing Configuration"
    description: >
      Optional. Can contain: datetime_formats [list of strings]. See the
      README for more details and examples.
    type: "object"
    required: false
    default: {}

steps:
  - task: { ... }
    input:
      datetime_parsing_config: $( config.datetimeParsingConfig )

Timezone configuration¶

Identical shape, swapping datetimeParsingConfig for timezoneConfig:

config:
  timezoneConfig:
    label: "Timezone Configuration"
    description: >
      Optional. Contains: timezone_mapping {dictionary}. See the README for
      more details and examples.
    type: "object"
    required: false
    default: {}

steps:
  - task: { ... }
    input:
      timezone_config: $( config.timezoneConfig )

Note the naming convention across both examples: config IDs are camelCase in protocol.yml; the input keys passed to the task script are snake_case, because they land in Python code and follow Python naming convention (datetimeParsingConfig the config ID, datetime_parsing_config the input key).

`manifest.json` labels and `catalog_keys`¶

See the manifest.json field table in Repo structure for the full labels shape and its reserved names, and for requirements, which catalog_keys is deprecated in favor of.