Skip to main content

Building Dictionaries

Before any record is submitted to your platform, someone has to decide what fields exist, what types they hold, what values are permitted, and which are required. Lectern is Overture's data dictionary management service: it gives those decisions a persistent, versioned, machine-readable home, so the same dictionary that guides submitters also drives automated validation at ingestion time.

Looking for the complete specification?

This page is a hands-on introduction to building dictionaries. The full reference lives in the Lectern dictionary reference: every restriction type, schema-level uniqueKey/foreignKey relationships, reusable references, and versioning.

Dictionary Structure​

A Lectern dictionary is a JSON document made up of a name, a version, and one or more schemas, each schema modeling a single data entity (for example, donor or specimen). Within a schema, each field specifies a name, a value type (string, integer, number, or boolean), and any restrictions on the values it will accept:

{
  "name": "my-dictionary",
  "version": "1.0",
  "schemas": [
    {
      "name": "donor",
      "description": "Core donor record",
      "fields": [
        {
          "name": "donor_id",
          "valueType": "string",
          "restrictions": { "required": true, "regex": "^DO-[0-9]{3,}$" }
        },
        {
          "name": "sex",
          "valueType": "string",
          "restrictions": {
            "required": true,
            "codeList": ["Female", "Male", "Other", "Unknown"]
          }
        }
      ]
    }
  ]
}

Restrictions (required, codeList, regex, range, and many more) are where the curation work lives; they turn naming conventions and value ranges into enforced constraints, rejected at submission time rather than discovered after the fact. Schemas can also reference each other through shared identifier fields (a specimen schema referencing its donor's donor_id), expressing hierarchy without flattening everything into one table.

Where a Dictionary Fits​

Once published to a running Lectern server, a dictionary drives the rest of the pipeline:

  • Lyric validates incoming submissions against it; every restriction becomes an automated, field-level check
  • Maestro uses the schema to inform how validated data is indexed into Elasticsearch, carrying typed fields, controlled vocabularies, and relationships through to the search layer

Try It: Dictionary Playground​

Build a dictionary hands-on in the Lectern Dictionary Playground. Edit a Lectern schema and it renders as an interactive table, validated live as you type, then download or copy the JSON to take it with you.

Prefer a guided walkthrough?

The workshop's Extension Task builds a dictionary step by step in that same playground: starting from a single required field, layering on restrictions, then adding a second related schema.