Data Packaging Guidance

At a minimum, a data package should include the core file components: data files, a README file, and variable-level metadata files, such as data dictionaries. Additional files that strengthen transparency and support long-term reuse include study protocols, blank data collection instruments, code or scripts, and publication citations that link study data to related research. Together, these materials create a clear and complete record of a team’s study, which helps others interpret their work, reproduce results, and build on their findings.

Each data package should include the following core components:

• Data file(s): These might be raw or processed data. When possible, share files in a non-proprietary file format, like .csv or .tsv, so others can open them easily.
• A summary or README file: * A README, or summary file, describes context and characteristics of the data. It may describe experimental and data acquisition details, such as how data subjects were sampled, study start and end dates, and data collection activity geographic locations. A README may also describe the study or study files, such as the data package file directory structure, experimental and data acquisition details, any accompanying code documentation, and a list of software and versions used for data management and analysis. It may also include investigator names, institutes involved, funding sources, and version identifiers. Click here for additional guidance and templates. .
• Variable-level Metadata documentation (often a data dictionary or codebook): Variable-level metadata (VLMD) helps others understand a study’s data file variables, listing and defining each variable, stating units of measurement, and noting coding schemes. Each data file should have a VLMD file. A VLMD file for tabular data (data organized by rows and columns) is called a data dictionary or a codebook. HEAL Stewards have developed HEAL-specific data dictionary preparation guidance and you can click here for general guidance on data dictionaries. A VLMD file template for HEAL Data Platform submissions and VLMD schemas can be found in the Github repository, and additional documentation on submitting VLMD is available here. Studies with non-tabular data should click here if they would like to schedule a consultation with the HEAL Data Stewards regarding suitable VLMD files for their data type.

Note: Repository-specific documentation
A selected HEAL-compliant repository may have additional data package requirements. Tip: navigate to the HEAL-compliant Repository Selection Guide, find the selected repository in the table, and click on “Guidance” under the “links” column to find additional information on that repository.

Sharing other files in the data package can increase understandability and reusability. Consider sharing:

• Code used to transform raw data into analytic datasets: Include code/scripts/workflows documenting how raw data were cleaned, processed, or combined into analytic datasets, so others can understand and reproduce the study’s steps.
• Code used to conduct analyses: Provide analysis scripts or notebooks, allowing others to verify results, reproduce findings, or adapt methods for their own research.
• Publication citation(s): Linking data and publications helps others understand how the data were used, validate interpretations, and cite work accurately. Some repositories include a metadata field for citations, where investigators can list the digital object identifiers (DOIs) of related publications. It is also common to list related publication DOIs and/or web addresses in README files.
• Study protocol(s): Protocols clarify how and why data were collected and provide information about the study design and methods. They support reproducibility, reduce misinterpretation, and guide others in designing compatible or follow-up studies.
• Standard Operating Procedures (SOPs): Standard Operating Procedures (SOPs) document data generation and processing in more detail.
• Blank data collection instruments: Include blank instruments, such as questionnaires, surveys, or forms. This helps others understand variable definitions, data structure, and question wording, which are critical for secondary analysis, harmonization, or comparison across studies.
• Context or explanatory documents: Include write-ups explaining data quality issues, opaque data processing decisions, or missing information and files. These contextual details prevent misuse or misinterpretation and help secondary users assess data limitations. For example, some data packages include a one-page text file describing how to interpret missing values for certain variables. Others may include a brief description of steps taken to de-identify data.