Schemas

On this page

The GLC 3.0.2 schemas define the structure, constraints, and relationships of metadata used to describe light-exposure and optical-measurement studies. Tabular resources use Frictionless Table Schema; structured resources use JSON Schema. The tables below show required fields (*), permitted values, descriptions, and cross-resource references.

Resources marked with * are required.

Download the GLC 3.0.2 schema bundle (.zip)

Study Schema *

Source: study_schema.json · Download schema

Name Definition Type
schema_version *

Version of the metadata schema used by this study

Example: "3.0.2"

string
study_internal_id *

Unique identifier for study

Example: "EXAMPLE_STUDY_001"

Referenced by: dataset_schema.dataset_crossref.dataset_crossref_study_id

string
study_title *

Study name

Example: "Example everyday light exposure study"

string
study_preregistration

DOI, URL, or concise status note for study or analysis preregistration. Clearly distinguish analysis preregistration from preregistration of the study or data collection.

Example: "https://osf.io/example/"

string
study_ethics

Name of ethics committee and approval number

Example: "Example University Ethics Committee, approval EX-2026-001"

string
study_registration

Registry and ID of clinical trial registration

Example: "Not registered"

string
study_short_description *

Short narrative description of the study

Example: "Observational study of everyday light exposure and sleep."

string
study_sample *

Short description of the study sample

Example: "Three healthy adult volunteers."

string
study_groups

Groups in the study

Example: [{"study_group_name":"Example cohort","study_group_description":"Adult community sample","study_group_size":3,"study_group_datasets":["EXAMPLE_DATASET_P001"]}]

Item properties (6)
study_group_name*

Group name

Example: "Example cohort"

string
study_group_description

Group description

Example: "Adult community sample"

string
study_group_size

Sample size

Example: 3

integer
study_group_inclusion

Inclusion criteria for sample group, given as an array of strings

Example: ["Age 18 years or older"]

array
study_group_exclusion

Exclusion criteria for sample group, given as an array of strings

Example: ["Unable to provide informed consent"]

array
study_group_datasets*

Dataset internal IDs linked to this study group

Constraints
  • Minimum items: 1

Example: ["EXAMPLE_DATASET_P001","EXAMPLE_DATASET_P002"]

array
array
study_intervention

Short description of the study intervention, if any

Example: "No intervention; observational study."

string
study_setting *

Description of the study setting

Example: "Participants’ everyday indoor and outdoor environments."

string
study_geographical_location *

Geographical location and context (city/rural, urban)

Example: "Munich, Germany"

string
study_contributors

Any contributors to the study

Example: ["Alex Example"]

array
study_datasets *

Datasets contained within the study

Example: ["EXAMPLE_DATASET_P001","EXAMPLE_DATASET_P002"]

array
study_type

Type of study

Example: "observational"

string
study_funding_sources

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

Constraints
  • Minimum items: 1

Example: ["Example Research Council grant EX-2026-001"]

array
study_keywords

Key words describing the projects

Example: ["light exposure","sleep","circadian rhythms"]

array

Fields marked with * are required.

Contributor Schema

Source: contributor_schema.json · Download schema

Name Definition Type
contributor_full_name *

Full name of the contributor

Example: "Alex Example"

string
contributor_roles

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

Example: ["data collector","metadata curator"]

array
contributor_email

Email address of the contributor

Constraints
  • Format: idn-email

Example: "alex.example@example.org"

string
contributor_orcid

ORCID identifier of the contributor

Example: "https://orcid.org/0000-0002-1825-0097"

string
contributor_institution

Institutional affiliation of the contributor

Example: {"contributor_institution_name":"Example University","contributor_institution_city":"Munich","contributor_institution_country":"Germany"}

Properties (3)
contributor_institution_name*

Name of the institution

Example: "Example University"

string
contributor_institution_city

City of the institution

Example: "Munich"

string
contributor_institution_country*

Country of the institution

Example: "Germany"

string
string

Fields marked with * are required.

Dataset Schema *

Source: dataset_schema.json · Download schema

Name Definition Type
schema_version *

Version of the metadata schema used by this dataset

Example: "3.0.2"

string
dataset_internal_id *

Unique identifier of dataset

Example: "EXAMPLE_DATASET_P001"

string
dataset_participant_associated *

Whether this dataset is associated with one participant. True requires a valid participant ID. For datasets containing no participant-associated data, set this to false and omit the participant ID.

Example: true

boolean
dataset_crossref *

Crossreferencing information linking to study, participant, and device

Example: {"dataset_crossref_study_id":"EXAMPLE_STUDY_001","dataset_crossref_participant_id":"EXAMPLE_P001"}

Properties (2)
dataset_crossref_study_id*

Internal ID for study

Example: "EXAMPLE_STUDY_001"

string
dataset_crossref_participant_id

Internal ID for participant. Required for participant-associated datasets and omitted otherwise.

Constraints
  • Minimum length: 1

Example: "EXAMPLE_P001"

string
string
dataset_timezone *

IANA time zone name for data collection, such as Europe/Berlin

Constraints
  • Format: iana-timezone

Example: "Europe/Berlin"

string
dataset_location *

Latitude/Longitude of data collection

Constraints
  • Minimum items: 2
  • Maximum items: 2

Example: [48.1372,11.5756]

array
dataset_variable_terms *

Dataset-specific controlled vocabulary for variable_term values. Include ‘other’ as fallback.

Constraints
  • Minimum items: 1

Example: [{"term":"illuminance","label":"Illuminance"}]

Item properties (2)
term*

Short controlled token (e.g., melEDI)

Constraints
  • Minimum length: 1

Example: "illuminance"

string
label

Human-readable label for the controlled term

Constraints
  • Minimum length: 1

Example: "Illuminance"

string
string
dataset_file *

Dataset descriptors

Constraints
  • Minimum items: 1

Example: [{"dataset_file_names":["data/EXAMPLE_P001_light.csv"]}]

Item properties (21)
dataset_file_modality*

Controlled data modalities contained in this same-structure file group

Constraints
  • Allowed item values: light, accelerometry, temperature, humidity, air_pollution, questionnaire, diary, wear_log, other
  • Minimum items: 1
  • Items must be unique.

Example: ["light"]

array
dataset_file_modality_other

Human-readable modality required when dataset_file_modality contains other

Constraints
  • Minimum length: 1

Example: "sleep diary"

string
dataset_file_modality_other_type

Whether an other modality is sensor-generated or non-device data

Constraints
  • Allowed values: sensor, non_device

Example: "non_device"

string
dataset_file_instrument

Instrument and collection method for a questionnaire, diary, or wear-log file group

Example: {"recorded_by":"participant"}

Properties (7)
instrument_type*
Constraints
  • Allowed values: questionnaire, diary, wear_log
string
instrument_name*
Constraints
  • Minimum length: 1
string
collection_method*
Constraints
  • Allowed values: paper, software, other
string
software_name
Constraints
  • Minimum length: 1
string
collection_method_other
Constraints
  • Minimum length: 1
string
recorded_by*

Who entered or completed the questionnaire, diary, or wear log

Constraints
  • Allowed values: participant, study_staff, other

Example: "participant"

string
recorded_by_other

Description of who entered or completed the record when recorded_by is other

Constraints
  • Minimum length: 1

Example: "trained research assistant"

string
string
dataset_file_crossref_device_id

Internal ID of the device that generated or is directly described by this file group. For questionnaires, diaries, and wear logs, provide this only when the complete file group unambiguously concerns one device; omit device metadata when it concerns multiple devices collectively or device attribution is unknown. Shared timing alone is not sufficient.

Constraints
  • Minimum length: 1

Example: "EXAMPLE_DEVICE_001"

string
dataset_file_device_location

Specific placement of the acquisition device, such as non-dominant wrist, bedside table, or building rooftop

Constraints
  • Minimum length: 1

Example: "non-dominant wrist"

string
dataset_file_device_location_type

Relationship of the acquisition device to the participant or wider environment. Use body_worn when the device is attached to or worn by the participant, such as on the wrist or chest. Use participant_proximal when the device is intentionally positioned near the participant but is not worn, such as on a bedside table or beside a workstation. Use environmental when the device measures the wider environment without being positioned relative to a participant, such as on a building rooftop or at an outdoor monitoring station.

Constraints
  • Allowed values: body_worn, participant_proximal, environmental

Example: "body_worn"

string
dataset_file_temporal_resolution*

Temporal resolution of records in this file group

Example: {"value":30,"unit":"s"}

Properties (3)
resolution_type*
Constraints
  • Allowed values: fixed_interval, event_based
string
value
Constraints
  • Must be greater than 0
number
unit
Constraints
  • Minimum length: 1
string
string
dataset_file_description

Concise human-readable description of the file group’s contents, scope, and intended interpretation. Use when important information is not represented by the structured file-group metadata.

Constraints
  • Minimum length: 1

Example: "Thirty-second light and activity measurements."

string
dataset_file_instructions*

Instructions associated with collection of this file group

Constraints
  • Minimum length: 1

Example: "Wear the device continuously except during bathing."

string
dataset_file_names*

File names corresponding

Constraints
  • Minimum items: 1

Example: ["data/EXAMPLE_P001_light.csv"]

array
dataset_file_format*

File format

Example: "text/csv"

string
dataset_file_encoding*

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

Constraints
  • Minimum items: 1

Example: ["UTF-8"]

array
dataset_file_timezone*

IANA time zone name for the data files, such as Europe/Berlin

Constraints
  • Format: iana-timezone

Example: "Europe/Berlin"

string
dataset_file_datetime*

Datetime metadata that applies to every file in this file group

Example: {"dataset_file_datetime_source":"column","dataset_file_datetime_date":"timestamp","dataset_file_datetime_dateformat":"YYYY-MM-DD HH:mm:ss"}

Properties (5)
dataset_file_datetime_source*

Whether datetime information comes from file columns or a fixed collection date/time value

Constraints
  • Allowed values: column, collection

Example: "column"

string
dataset_file_datetime_date*

Date/datetime column name when source is column, or fixed collection date/time value when source is collection

Constraints
  • Minimum length: 1

Example: "timestamp"

string
dataset_file_datetime_dateformat*

Format of the date/datetime column or fixed collection date/time value. For consistency, use YYYY-MM-DD for a date or YYYY-MM-DD HH:mm:ss for a datetime when possible.

Constraints
  • Minimum length: 1

Example: "YYYY-MM-DD HH:mm:ss"

string
dataset_file_datetime_time

Separate time column name when source is column. Omit when no separate time column is used.

Constraints
  • Minimum length: 1

Example: "time"

string
dataset_file_datetime_timeformat

Format of the separate time column when present. Omit when no separate time column is used.

Constraints
  • Minimum length: 1

Example: "HH:mm:ss"

string
string
dataset_file_role*

Role of this file group in the dataset. Primary file groups contain the principal data used for analysis; supporting file groups provide related context or supporting information.

Constraints
  • Allowed values: primary, supporting

Example: "primary"

string
dataset_file_data_state*

State of the data in this file group. Raw data have not undergone preprocessing; processed data have undergone transformations described in dataset_file_preprocessing.

Constraints
  • Allowed values: raw, processed

Example: "raw"

string
dataset_file_header_row

Optional 1-based row index of the true header row in the file; use when preamble lines exist

Constraints
  • Minimum: 1

Example: 1

integer
dataset_file_preprocessing*

Preprocessing information

Example: {"dataset_file_preprocessing_bol":true,"dataset_file_preprocessing_desc":["Converted timestamps to ISO 8601."]}

Properties (2)
dataset_file_preprocessing_bol*

Indicator whether preprocessing was applied

Example: true

boolean
dataset_file_preprocessing_desc

Description of what preprocessing was applied

Example: ["Converted timestamps to ISO 8601."]

array
array
dataset_file_variables*

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

Constraints
  • Minimum items: 1

Example: [{"dataset_file_variables_name":"illuminance","dataset_file_variables_labels":"Illuminance","dataset_file_variables_units":"lx","dataset_file_variables_type":"numeric"}]

Item properties (8)
dataset_file_variables_name*

Variable name as contained in the dataset

Example: "illuminance"

string
dataset_file_variables_labels*

Variable name as clear name

Example: "Illuminance"

string
dataset_file_variables_description

Optional full description, questionnaire prompt, or interpretation of the variable. Keep the label concise and use this field for complete source wording and instructions.

Constraints
  • Minimum length: 1

Example: "Photopic illuminance measured at the participant’s wrist."

string
dataset_file_variables_units

UCUM unit code or a precise custom unit. Required for numeric and integer variables and omitted for string, boolean, and factor variables. Do not use placeholders such as N/A or Unknown.

Constraints
  • Minimum length: 1
  • Disallowed values: N/A, NA, n/a, Unknown, unknown

Example: "lx"

string
dataset_file_variables_calibration

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

Example: "Apply the manufacturer-provided calibration coefficients."

string
dataset_file_variables_type*

Expected value type for non-empty cells in this variable column. Boolean values may be encoded as true/false or 0/1. Select factor only for categorical variables with a finite set of defined levels, such as 0 = No and 1 = Yes. A numerical factor, coefficient, ratio, proportion, percentage, score, count, or other quantitatively meaningful value must instead be declared numeric or integer.

Constraints
  • Allowed values: string, boolean, numeric, integer, factor
  • Every non-empty value in the corresponding data column must match the declared type; empty values are reported as warnings.

Example: "numeric"

string
dataset_file_variables_factor_levels

Permitted categorical values and their meanings when the variable type is factor

Constraints
  • Minimum items: 1
  • Factor values must be unique, and every non-empty value in the data column must match one of them.

Example: [{"value":"0","label":"No"},{"value":"1","label":"Yes"}]

Item properties (3)
value*

Permitted factor value as represented in the tabular file

Example: "1"

string
label*

Human-readable meaning of the factor value

Constraints
  • Minimum length: 1

Example: "Illuminance"

string
description

Optional additional explanation of the factor level

Example: "Participant selected “Yes”."

string
string
dataset_file_variables_term*

Semantic term metadata for this variable

Example: {"variable_term":"illuminance"}

Properties (2)
variable_term*

Controlled semantic term for this variable

Constraints
  • The value must be declared in dataset_variable_terms or use the reserved fallback term other.

Example: "illuminance"

string
variable_name

Custom variable name required when variable_term is ‘other’

Example: "custom_light_metric"

string
string
string
primary_variables

Principal or default variables used when analysing this file group. Values must be a subset of dataset_file_variables_name.

Constraints
  • Minimum items: 1
  • Maximum items: 4
  • Items must be unique.
  • Required and non-empty for primary file groups.

Example: ["illuminance"]

array
array

Fields marked with * are required.

Device Schema *

Source: device_schema.json · Download schema

Name Definition Type
schema_version *

Version of the metadata schema used by this device record

Example: "3.0.2"

string
device_internal_id *

Unique internal identifier for the device

Example: "EXAMPLE_DEVICE_001"

Referenced by: dataset_schema.dataset_crossref.dataset_crossref_device_id

string
device_manufacturer *

Manufacturer of the device

Example: "Example Instruments"

string
device_model *

Model name or number of the device

Example: "Light Sensor LS-100"

string
device_serial_number *

Serial number assigned to the individual device

Example: "LS100-0001"

string
device_calibration_date *

Required date of the device’s most recent applicable calibration (format YYYY-MM-DD).

Constraints
  • Format: date
  • Pattern: ^\d{4}-\d{2}-\d{2}$

Example: "2026-01-15"

string
device_firmware_version

Firmware version installed on the device

Example: "1.2.0"

string
device_datasheet_id *

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

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

Example: "example-instruments-ls100-v1"

string
device_sensors

List of sensors contained within the device

Example: [{"device_sensor_type":"photopic light sensor"}]

Item properties (2)
device_sensor_type*

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

Example: "photopic light sensor"

string
device_sensor_datasheet_id

Optional reference to a separate detailed datasheet for this sensor component. Omit when the required whole-device datasheet covers the integrated sensor.

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

Example: "example-instruments-ls100-v1"

string
string

Fields marked with * are required.

Device/sensor datasheet schema *

Source: device_datasheet_schema.json · Download schema

Metadata schema for device and sensor datasheets.

Name Definition Type
schema_version *

Version of the metadata schema used by this datasheet record

Example: "3.0.2"

string
datasheet_id *

Unique datasheet identifier referenced by devices or sensors

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

Example: "example-instruments-ls100-v1"

string
datasheet_version

Version label for this datasheet, e.g. 1.0

Example: "1.0"

string
datasheet_manufacturer *

Manufacturer of the device or sensor

Example: "Example Instruments"

string
datasheet_type *

Human-readable type of the device or sensor

Example: "wearable light sensor"

string
datasheet_sensor_modality *

One or more controlled modalities/categories used to apply modality-specific validation rules

Constraints
  • Allowed item values: light, accelerometer, temperature, other
  • Minimum items: 1
  • Items must be unique.

Example: ["light"]

array
datasheet_sensor_modality_other

Free-text modality description when datasheet_sensor_modality contains other

Example: "skin temperature"

string
datasheet_model *

Model of the device or sensor

Example: "Light Sensor LS-100"

string
datasheet_calibration_interval

Recommended or required calibration interval in days. Omit when not applicable.

Constraints
  • Minimum: 0

Example: 365

integer
datasheet_calibration_method

General description of the calibration method, if applicable

Example: "Calibrated against a traceable reference photometer."

string
datasheet_calibration_accuracy

Accuracy, uncertainty, or tolerance information, if applicable

Example: "±5% under reference conditions"

string
datasheet_calibration_range

Light-sensor measurement or calibration range. Required when datasheet_sensor_modality is light.

Example: "0.1–100000 lx"

string
datasheet_calibration_notes

Additional calibration notes

Example: "Calibration applies at 23 °C."

string
datasheet_calibration_parameters

Generic calibration or sensor specification parameters. This supports non-light sensor metadata without hardcoding modality-specific fields.

Example: [{"parameter_name":"sampling interval","parameter_value":30,"parameter_unit":"s"}]

Item properties (4)
parameter_name*

Name of the calibration/specification parameter

Example: "sampling interval"

string
parameter_value*

Value of the parameter

Example: 30

string or number or boolean
parameter_unit

Unit of the parameter value, if applicable

Example: "s"

string
parameter_description

Additional explanation of the parameter

Example: "Time between consecutive measurements."

string
string
datasheet_calibration_spectral_sensitivity

Optional light-sensor spectral sensitivity calibration, when documented by the source.

Constraints
  • Minimum items: 1

Example: [{"datasheet_calibration_spectral_sensitivity_wavelength":555,"datasheet_calibration_spectral_sensitivity_relative":1.0}]

Item properties (2)
datasheet_calibration_spectral_sensitivity_wavelength*

Wavelength (nm)

Constraints
  • Minimum: 0

Example: 555

number
datasheet_calibration_spectral_sensitivity_relative*

Relative spectral sensitivity at the given wavelength

Example: 1.0

number
number
datasheet_calibration_linearity

Optional linearity calibration information, when documented by the source.

Example: "R² ≥ 0.99 across the documented measurement range."

string
datasheet_calibration_directional_response

Optional directional-response calibration information, when documented by the source.

Example: "Cosine-response deviation below 10% up to 60° incidence."

string
datasheet_channel *

Information on channels exported by the device or sensor

Constraints
  • Minimum items: 1

Example: [{"datasheet_channel_nr":1,"datasheet_channel_name":"LIGHT","datasheet_channel_unit":"lx","datasheet_channel_description":"Photopic illuminance channel."}]

Item properties (4)
datasheet_channel_nr*

Channel number

Constraints
  • Minimum: 1

Example: 1

integer
datasheet_channel_name*

Channel name as it appears in exported files

Example: "LIGHT"

string
datasheet_channel_unit

Unit of channel

Example: "lx"

string
datasheet_channel_description

Description of channel

Example: "Photopic illuminance channel."

string
string

Fields marked with * are required.

Participant schema *

Source: participant_schema.json · Download schema

Name Definition Type
participant_internal_id *

Unique ID for participant

Example: EXAMPLE_P001

Referenced by: dataset_schema.dataset_crossref.dataset_crossref_participant_id

string
participant_age *

Age of the participant at the time of first participation

Constraints
  • minimum: 0
  • maximum: 120

Example: 34

 integer
participant_sex

Sex of participant, if recorded

Example: female

 string
participant_gender

Gender of participant, if required

Example: woman

 string

Participant characteristics schema

Source: participant_characteristics_schema.json · Download schema

Name Definition Type
participant_internal_id

Linked participant ID

Example: EXAMPLE_P001

References: participants.participant_internal_id

string
participant_characteristic_name

Name of the participant characteristic

Example: chronotype

 string
participant_characteristic_value

Value of the participant characteristic

Example: intermediate

 string
participant_characteristic_unit

Optional unit of the characteristic value. Leave blank for unitless scores or categorical values.

 string
participant_characteristic_description

Additional notes or description

Example: Self-reported chronotype category.

 string