favicon.ico

U.S. Geological Survey

Data standards are the guidelines by which data are described and recorded. In order to share, exchange, combine and understand data, we must standardize the format as well as the meaning.

HEAL Data Stewards

[HEAL Semantic Search (HSS) 2.0](https://www.healdatafair.org/resources/semantic-search) is now available, bringing a refreshed interface that makes it easier to explore related studies, variables, Common Data Elements (CDEs), and biomedical concepts from a single search; compare how concepts and variables are defined and measured across studies; and access insights from 20 newly added data dictionaries, over 1000 HEAL studies, and 233 CDEs. Get started today by [entering a search term](https://www.healdatafair.org/resources/semantic-search) relevant to your research.

Explore HEAL studies, variables, CDEs, and concepts in [HEAL Semantic Search (HSS) 2.1](https://www.healdatafair.org/resources/semantic-search)!

HEAL Data Dictionary Preparation Guidance

This resource offers guidance for preparing variable-level [metadata](https://www.healdatafair.org/resources/metadata) (often in the form of a data dictionary) to support clarity, consistency, machine processing, reuse, and alignment with the variable-level metadata [schema](https://github.com/HEAL/heal-metadata-schemas/tree/main/variable-level-metadata-schema) used by the HEAL Data Ecosystem. Variable-level metadata (VLMD) is a core component of a complete [HEAL data package](https://www.healdatafair.org/resources/data-packaging-guidance) 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](https://heal.github.io/platform-documentation/vlmd/vlmd_tools/), enabling extraction of HEAL-compliant VLMD and validation against the HEAL VLMD schema.

## Preparing Your Data Dictionary 

This guidance is organized into four focus areas: variable clarity and reusability, consistency across variables, structure for programmatic use, and data integrity and source fidelity. Additional submission guidance and resources can be found in the Data Dictionary Sharing Readiness Tab. Each section outlines key elements supporting high-quality, reusable VLMD. This resource supports data dictionary preparation and helps reduce submission delays; it is not a rigid pass–fail checklist, and not all elements will apply to every study or data type.


Overview

# Variable Clarity and Reusability

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'*

# Consistency Across Variables

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.

# Structure for Machine and AI Processing

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](https://heal.github.io/platform-documentation/vlmd/vlmd_tools/)) 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](https://heal.github.io/platform-documentation/vlmd/vlmd_tools/) 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](https://github.com/HEAL/heal-metadata-schemas/tree/main/variable-level-metadata-schema/examples/valid) and [invalid](https://github.com/HEAL/heal-metadata-schemas/tree/main/variable-level-metadata-schema/examples/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 Integrity and Source Fidelity

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.




Data Dictionary Preparation Focus Areas

A data dictionary that reflects the guidance outlined in this reference guide is generally ready for submission. Not all elements will apply to every study or data type.

#### Next steps:
- Submit VLMD as a data dictionary through the [HEAL Platform's VLMD submission form](https://heal.github.io/platform-documentation/vlmd/) or by emailing the HEAL Stewards at [HEALStewards@renci.org.](healstewards@renci.org) 
- If you have questions, the [HEAL Stewards](https://forms.fillout.com/t/gcVveGMswBus) can provide additional guidance.

#### Additional resources:
- [VLMD Overview](https://www.healdatafair.org/resources/metadata)
- [Examples of valid submissions](https://github.com/HEAL/heal-metadata-schemas/tree/main/variable-level-metadata-schema/examples/valid)
- Webinar on [“Empowering Data Reuse: A Guide to Creating Data Dictionaries and Variable-Level Metadata (VLMD)”](https://docs.google.com/document/d/1Qkp7T3L6Jyjp6THHnWDyAUcfT6HF_upueQLnk2Md4qQ/edit?usp=sharing)
- [HEAL Data Packaging Guidance](https://www.healdatafair.org/resources/data-packaging-guidance)
