Schemas

On this page

The GLEAM DP schemas define the structure, constraints, and relationships of metadata and data used to describe light exposure and optical measurement studies. Schemas are expressed using Frictionless Table Schema for tabular resources (e.g. study, participants, participant characteristics, light data) and JSON Schema for structured, non-tabular resources (e.g. datasets, devices, datasheets). The descriptions of their fields follow the Table Schema specifications and are presented below in human-readable form. Together, they specify required fields indicated with *, permitted values, and cross-references between entities, enabling validation, interoperability, and consistent interpretation across datasets.

Legend: * = required resource · Example = illustrative only · unmarked = optional resource

Study *

Source: study_schema.json

Name Definition Type
study_title *

Title of the study

Constraints
  • required: true
 string
study_internal_id *

Unique identifier for study

Constraints
  • required: true

Referenced by: dataset_schema.dataset_crossref.dataset_crossref_study_id

string
study_preregistration

DOI of pre-registration document describing data collection

 string
study_ethics

Name of ethics committee and approval number

 string
study_registration

Registry and ID of clinical trial registration

 string
study_short_description *

Short narrative description of the study

Constraints
  • required: true
 string
study_sample *

Short description of the study sample

Constraints
  • required: true
 string
study_groups

Groups in the study

 array
study_intervention

Short description of the study intervention, if any

 string
study_setting *

Description of the study setting

Constraints
  • required: true
 string
study_geographical_location *

Geographical location and context (city, rural, urban)

Constraints
  • required: true
 string
study_contributors

Any contributors to the study

 array
study_datasets *

Datasets contained within the study

Constraints
  • required: true
 array
study_type

Type of study

 string
study_funding_sources

Any funding sources supporting the project. If the funding number is available, it should be given

 array
study_keywords

Key words describing the project

 array

Contributor

Source: contributor_schema.json

Name Definition Type
contributor_full_name *

Full name of the contributor

 string
contributor_roles

List of contributor roles (e.g., author, data collector)

 array
contributor_email

Email address of the contributor

 string
contributor_orcid *

ORCID identifier of the contributor

 string
contributor_institution

Institutional affiliation of the contributor

Properties (3)
contributor_institution_name*

Name of the institution

string
contributor_institution_city

City of the institution

string
contributor_institution_country*

Country of the institution

string
string

Fields marked with * are required.

Dataset *

Source: dataset_schema.json

Name Definition Type
dataset_internal_id *

Unique identifier of dataset

 string
dataset_instructions *

Description of the instructions given to study participants before or during the collection of this data set

 string
dataset_crossref *

Crossreferencing information linking to study, participant, and device

Properties (3)
dataset_crossref_study_id*

Internal ID for study

References: study_schema.study_internal_id

string
dataset_crossref_device_id*

Internal ID for device

References: device_schema.device_internal_id

string
string
dataset_device_location *

Anatomical location of the acquisition device

 string
dataset_sampling_interval *

Sampling interval

Minimum: 0

 number
dataset_datetime *

Information about datetime columns in the dataset

Properties (4)
dataset_datetime_date*

Name of the date column or datetime column

string
dataset_datetime_dateformat*

Formatting of the date column (e.g., ‘YYYY/MM/DD’) or datetime column (e.g., ‘YYYY/MM/DD HH:MM:SS’)

string
dataset_datetime_time

Name of the time column (only if separate from date)

string
dataset_datetime_timeformat

Formatting of the time column (e.g., ‘HH:MM:SS’) (only if separate from date)

string
string
dataset_illuminance *

Column name in the data that contains photopic illuminance

 string
dataset_melEDI

Column name in the data that contains melanopic EDI (D65)

 string
dataset_timezone *

Timezone of data collection (Olson database)

 string
dataset_location *

Latitude/Longitude of data collection

 array
dataset_file *

Dataset descriptors

Item properties (7)
dataset_file_names*

File names corresponding

array
dataset_file_format*

File format

string
dataset_file_encoding*

File text encoding (e.g., UTF-8)

array
dataset_file_timezone*

Timezone of data (Olson database)

string
dataset_file_auxiliary*

Indicator whether the data files contain light data (or auxiliary data)

boolean
dataset_file_preprocessing*

Preprocessing information

Properties (2)
dataset_file_preprocessing_bol*

Indicator whether preprocessing was applied

boolean
dataset_file_preprocessing_desc

Description of what preprocessing was applied

array
array
dataset_file_variables*

Variables contained in the dataset, units and location (column)

Item properties (4)
dataset_file_variables_name*

Variable name as contained in the dataset

string
dataset_file_variables_labels*

Variable name as clear name

string
dataset_file_variables_calibration

Description of transformation that should be applied to the variable for calibration, based only on researchers’ calibration

string
string
string

Fields marked with * are required.

Device *

Source: device_schema.json

Name Definition Type
device_internal_id *

Unique internal identifier for the device

Referenced by: dataset_schema.dataset_crossref.dataset_crossref_device_id

string
device_manufacturer *

Manufacturer of the device

 string
device_model *

Model name or number of the device

 string
device_serial_number *

Serial number assigned to the individual device

 string
device_calibration_date *

Date of last calibration (format YYYY-MM-DD)

Pattern: ^\d{4}-\d{2}-\d{2}$

 string
device_firmware_version

Firmware version installed on the device

 string
device_datasheet_id *

Reference to the general device specifications. Datasheet ID (slug). Version suffix optional; e.g., lumitech-lt100-v1.0

Pattern: ^[a-z0-9][a-z0-9._-]*(-v[0-9]+(\.[0-9]+)*)?$

References schema: Device/Sensor datasheet

string
device_sensors

List of sensors contained within the device

Item properties (2)
device_sensor_type*

Type of sensor (e.g., photopic light sensor, UV sensor)

string
device_sensor_datasheet_id

Reference to detailed datasheet of the sensor

Pattern: ^[a-z0-9][a-z0-9._-]*(-v[0-9]+(\.[0-9]+)*)?$

string
string

Fields marked with * are required.

Device/Sensor datasheet *

Source: device_datasheet_schema.json

Referenced by: device_schema.device_datasheet_id

Name Definition Type
datasheet_id *

foreign key devices reference

Pattern: ^[a-z0-9][a-z0-9._-]*(-v[0-9]+(\.[0-9]+)*)?$

 string
datasheet_version

Version label for this datasheet, e.g. 1.0

 string
datasheet_manufacturer *

Manufacturer of the sensor/device

 string
datasheet_type *

Type of the sensor/device

 string
datasheet_model *

Model of the sensor/device

 string
datasheet_calibration_interval *

Required device calibration interval (in days)

Minimum: 0

 integer
datasheet_calibration_spectral_sensitivity *

Information about spectral sensitivity calibration

Item properties (2)
datasheet_calibration_spectral_sensitivity_wavelength*

Wavelength (nm)

Minimum: 0

number
datasheet_calibration_spectral_sensitivity_relative*

Relative spectral sensitivity at given wavelength (unitless or fraction)

number
number
datasheet_calibration_linearity *

Information about linearity calibration

 string
datasheet_calibration_directional_response *

Information about directional response calibration

 string
datasheet_calibration_range *

Information about response range

 string
datasheet_channel

Information on channels

Item properties (4)
datasheet_channel_nr*

Number of channel

Minimum: 1

integer
datasheet_channel_name*

Name of the channel as appearing in the export (file)

string
datasheet_channel_unit

Unit of channel

string
datasheet_channel_description

Description of channel

string
string

Fields marked with * are required.

Participants *

Source: participant_schema.json

Referenced by: participant_characteristics_schema.participant_internal_id

Name Definition Type
participant_internal_id *

Unique ID for participant

Constraints
  • required: true

Referenced by: dataset_schema.dataset_crossref.dataset_crossref_participant_id

string
participant_age *

Age of the participant at the time of first participation

Constraints
  • required: true
  • minimum: 0
  • maximum: 120
 integer
participant_sex

Sex of participant, if recorded

 string
participant_gender

Gender of participant, if required

 string

Participant characteristics

Source: participant_characteristics_schema.json

Name Definition Type
participant_internal_id

Linked participant ID

References: participant_schema.participant_internal_id

string
participant_characteristic_name

Name of the participant characteristic

 string
participant_characteristic_value

Value of the participant characteristic

 string
participant_characteristic_unit

Unit of the characteristic value

 string
participant_characteristic_description

Additional notes or description

 string