HEAL Data Dictionary Preparation Guidance

This resource offers guidance for preparing variable-level metadata (often in the form of a data dictionary) to support clarity, consistency, machine processing, reuse, and alignment with the variable-level metadata schema used by the HEAL Data Ecosystem. Variable-level metadata (VLMD) is a core component of a complete HEAL data package and, along with key supporting documentation, helps others understand how your research defines, measures, and encodes variables for reuse and analysis. Following these practices can also help ensure your file is ready for use with the Platform’s VLMD tool, enabling extraction of HEAL-compliant VLMD and validation against the HEAL VLMD schema.

OverviewData Dictionary Preparation Focus AreasData Dictionary Sharing Readiness

Data Dictionary Preparation Focus Areas

Each variable should be clearly defined, self-contained, and understandable without prior study knowledge. Well-documented variables improve interpretability, support reuse, and reduce ambiguity for both humans and machines.

Best Practices and Examples

  • Each row represents exactly one variable.
  • Variable names are meaningful and clear, not internal shorthand.
  • Each variable is described, so someone unfamiliar with the study can understand what it represents.
  • Permissible values are included for categorical variables when known.
  • Variable units are included where applicable.
  • Relevant contextual information, such as baseline versus longitudinal collection, is included when readily available.
  • Each measure is represented once, without duplicate variables under different names.
  • Information about each variable, including the variable title, variable name, and variable description, is fully documented within each row, without relying on implicit assumptions or information defined elsewhere.
    • Examples of variable information:
      • Variable title (human-readable): ‘Participant ID’
      • Variable name (machine-readable): ‘participant_id’
      • Variable description: ‘Unique identifier for participant'

Variables that represent similar concepts should follow consistent naming, structure, and encoding patterns. Consistency improves interpretability, supports cross-variable comparisons, and enables more efficient data harmonization across studies and instruments.

Best Practices and Examples

  • Use consistent encoding patterns for similar variables within the same instrument or form, and clearly define how values are represented.
    • For example, ‘Yes/No’ vs ‘1/0’ vs ‘Y/N’
  • Original encodings are preserved when similar outcomes are measured across instruments, and differences in permissible values are clearly documented.
    • When the same outcome is measured using different instruments, categorical encodings may differ (for example, one instrument may use ‘Y/N’ while another uses ‘1/0’). These differences are acceptable when clearly documented at the variable level.
  • Naming conventions are consistent, and relationships between variables are clear, while allowing for differences across instruments, when appropriate.
    • Variable names for the same outcome may differ across instruments (for example, ‘SleepDuration’ vs ‘SleepTime’) and are acceptable when clearly documented.
  • When multiple variables capture related concepts, use consistent naming patterns to make relationships clear, even across different forms.
    • For example, sleep-related variables might share a common prefix such as 'SleepDuration', ‘SleepLatency,’ and ‘SleepQuality,’ to indicate related aspects of the same concept.

Data dictionaries should be structured in a simple, consistent, and machine-readable format to support automated processing, validation, and reuse. Clean structure reduces parsing errors, enables tools (like the HEAL VLMD tool) to interpret data reliably, and ensures compatibility across systems and workflows.

Best Practices and Examples

  • Use a simple, machine-readable tabular format (e.g., CSV, TSV, JSON, or REDCap export) with a single, clean header row. The VLMD tool only accepts these file types.
  • Avoid structural and visual elements that interfere with parsing (e.g., merged cells, hidden columns, multiple header rows, color-coding, decorative fonts, emojis, or special characters). Use plain, unformatted tables and standard characters to support automated and AI-driven processing.
  • Ensure required HEAL VLMD fields (e.g., name, description) are present and aligned with the expected schema.
    • Examples of valid and invalid VLMD are available for reference.
    • Because HEAL studies vary in design and data types, some VLMD schema fields may not map directly to every column. In these cases, align column headers and metadata as closely as possible with the expected schema to support automated processing.

Data dictionaries should accurately reflect the original source data and preserve each variable’s full meaning. Maintaining source system fidelity reduces errors introduced through manual handling, ensures completeness, and supports reliable interpretation and reuse.

Best Practices and Examples

  • Generate data dictionaries directly from the source system when possible (e.g., REDCap export), rather than manually recreating or editing.
  • Ensure each variable row contains all information needed to interpret its encoding (e.g., meaning, permissible values, units) without requiring external references.
  • Verify that variable descriptions are complete and not unintentionally truncated due to formatting, software limitations, or export issues.