Study Object Files and Formats

2024-03-28

The xml formats used for study objects in folder archives are documented in the LabKey XML Schema Reference. This page provides a summary of some key files exported for a study and links to the schemas for these files.

Note: Study, list, and folder archives are all written using UTF-8 character encoding for text files. Imported archives are parsed as UTF-8. In addition, text exports from grids use UTF-8 character encoding.

Study Section of Folder Archive Directory Structure

Studies have the following directory structure within a folder archive. The structure shown below is provided as an example and excludes most details within folders containing lists, views, etc. The included elements in any archive will differ depending the nature of your study, and which export options are selected.

folder
folder.xml
pages.xml
filebrowser_admin_config.xml
data_states.xml
view_categories.xml
lists - subdirectory containing lists
reports - subdirectory containing reports
views - subdirectory containing views
wikis - subdirectory containing wikis
study
│ cohorts.xml
│ participant_groups.xml
│ security_policy.xml
│ study.xml
│ visit_map.xml

├───datasets
│ dataset5004.tsv
│ dataset5006.tsv
│ dataset5007.tsv
│ datasets_manifest.xml
│ datasets_metadata.xml
│ [First Word of Study Name].dataset

├───properties
│ objective.tsv
│ personnel.tsv
│ study.tsv
│ study_metadata.xml

└───views
participant.html
settings.xml

Note that if you are using the specimens module, you will have additional specimen-related content. Learn more in the documentation archives.

XML Formats

Exporting a study folder produces a zipped folder archive containing a set of XML/XSD files that describe the study's settings and associated data. Some of these files are contained in similarly-named folders rather than at the top level. Key .xml and .xsd files are listed here and linked to their schema documentation pages:

  • study.xml -- Top level study schema XML file.
  • cohorts.xsd -- Describes the cohorts used in the study. A cohort.xml file is exported only when you have manually assigned participants to cohorts.
  • datasets.xsd -- Describes the study dataset manifest. Includes all study dataset-specific properties beyond those included in tableInfo.xsd. Used to generate dataset_manifests.xml.
  • study.xsd -- A manifest for the serialized study. It includes study settings, plus the names of the directories and files that comprise the study.
  • studyDesign.xsd -- Includes studyDesign table information including immunogens, adjuvants, sample types, immunization schedule.
  • visit_map.xsd -- Describes the study visit map. It is used to generate the visitMap.xml file, which describes the study's visits and includes all of the information that can be set within the "Manage Visit" UI within "Manage Study." For example XML file see Import Visit Map.
  • data.xml -- An XML version of dataset schemas.
  • tableInfo.xsd -- Describes metadata for any database table in LabKey Server, including lists and datasets. A subset of this schema's elements are used to serialize lists for import/export. Similarly, a subset of this schema's elements are used to generate the datasets_metadata.xml file for dataset import/export. Note that a complementary schema file, datasets.xsd, contains additional, dataset-specific properties and is used to generate and read datasets_manifest.xml during dataset import/export. These properties are not included in tableInfo.xsd because of their specificity to datasets.
  • query.xml -- Describe the queries in the study.
  • report.xsd -- Describe the reports in the study.
  • Additional information on query, view, and report schemas can be found on the Tutorial: File Based Module Resources page.

Related Topics