Validate a dataset

The GLC validator checks whether a data package follows a supported version of the GLC Standard. Validation runs in the dataset's GitHub repository and produces a downloadable report containing its errors and warnings.

Before you begin

You need:

• a GitHub repository containing your complete GLC data package;
• a datapackage.json file at the repository root;
• every metadata and data file referenced by datapackage.json; and
• permission to add files to the dataset repository.

Review the required structure and fields in the GLC Standard resource schemas. You can create or edit the metadata using the GLC Metadata Builder or prepare the files manually with a text editor.

1Prepare the complete package

A package exported by the GLC Metadata Builder has this structure:

your-package/
├── datapackage.json
├── README.txt
├── schemas/
│   └── 3.0.2/
│       ├── glc-dp-profile.json
│       └── … resource schemas
└── data/
    ├── study.json
    ├── participants.csv
    ├── participant_characteristics.csv  (when provided)
    ├── devices.json
    ├── device_datasheet.json
    ├── datasets.json
    └── datasets/
        └── your-measurement-files.csv    (add after export)

The builder exports the package descriptor, resource metadata and schema files, but it cannot retain the original measurement files selected in the browser. Add those files at the paths declared in data/datasets.json before validation.

Folders below data/datasets/ may use descriptive names such as light/, questionnaires/ or longitudinal-reports/. These are organizational choices, not required folder names. Their paths must agree with the paths declared in the package metadata.

Commit and push the complete package to GitHub before configuring validation.

2Add the validation workflow

Copy the contents of this one file from the validator repository:

Open the validation workflow template

The button opens the exact template file that must be copied.

Create this file in the dataset repository and paste the copied contents into it:

.github/workflows/validate-glc-dataset.yml

You do not need to copy the validator code, schema directories, Dockerfile or the validator repository.

Add the workflow through the GitHub website

1. Open the dataset repository on GitHub.
2. Select Add file, then Create new file.
3. Enter the complete filename .github/workflows/validate-glc-dataset.yml. GitHub creates the two folders automatically.
4. Open the workflow template in another tab.
5. Copy its complete contents and paste them into the new file.
6. Select Commit changes.

The workflow calls the centrally released GLC validator. Users do not need to install Python, Docker or the validator on their own computers.

3Run validation

Validation runs automatically when changes are pushed to main, when a pull request is opened or updated, or when the workflow is started manually.

To start it manually:

1. Open the dataset repository on GitHub.
2. Select the Actions tab.
3. Select Validate GLC Dataset in the workflow list.
4. Select Run workflow.
5. Choose the branch containing the package.
6. Select the green Run workflow button.
7. Wait for the run to finish.

A green check means validation passed. A red cross means that one or more errors prevented it from passing. A passing run can still contain warnings that should be reviewed.

4Review errors and warnings

The downloadable validation-report artifact is the main place to inspect the results:

1. Open the repository’s Actions tab.
2. Select Validate GLC Dataset.
3. Select the relevant workflow run.
4. On the run summary page, scroll to Artifacts.
5. Download validation-report.
6. Unzip the downloaded file.

How to interpret the messages

Errors prevent the package from passing. Examples include an absent required field, an invalid type or format, a missing referenced file, a broken identifier reference, or a quantitative variable without its required unit.

Warnings do not prevent the package from passing. They identify issues worth reviewing, such as missing source-data cells or uneven row widths.

Correct errors in the package, commit and push the changes, and inspect the new workflow run. Validation applies to one exact commit: an older passing report does not validate later changes.

The validation step within the GitHub Actions job also displays the messages, but the artifact is easier to download, retain and inspect.

5Request inclusion in the GLC Registry

Passing validation does not automatically publish a repository in the registry. The dataset owner proposes an entry, automated checks verify the validation evidence, and a GLC maintainer reviews the request.

View the GLC Registry

The registry repository maintains its list in datasets.yml. Only submit a request after the dataset’s main branch has a passing validation run for its current commit.

Prepare the entry

Add an entry under datasets: without deleting any existing entries:

  - id: your-dataset-name
    repo: github-owner/your-dataset-repository
    branch: main

For example:

  - id: melidos-iztech-glc-dataset
    repo: tscnlab/melidos-iztech-glc-dataset
    branch: main

• id is a short, unique name for the registry entry.
• repo is the exact GitHub repository in owner/repository form.
• branch is the validated branch, normally main.

Do not enter the status, schema version, commit hash or validation date manually. Registry automation reads those values from the trusted validation artifact for the exact dataset commit.

Open the registry pull request

If you can edit the registry repository:

1. Open datasets.yml.
2. Select the pencil icon.
3. Add the entry.
4. Select Commit changes.
5. Choose Create a new branch for this commit and start a pull request.
6. Open the pull request against the registry’s main branch.

If GitHub does not allow you to edit the file, fork tscnlab/glc-registry, edit datasets.yml in your fork, and open a pull request from that fork to tscnlab/glc-registry:main.

What happens after submission

The automated pull-request check:

1. locates the current commit of the specified dataset branch;
2. finds the validation artifact produced for that exact commit;
3. verifies that it came from an accepted GLC validation workflow; and
4. confirms that the validation status is pass.

After publication, the registry displays the validated repository, commit, schema version, status and validation time. The result applies only to that commit and schema version—not to later commits or later GLC schema versions.

The Send to LLW action is a separate optional step for passing packages that should be sent to LightLogWeb. Registry inclusion alone does not transfer the dataset.