Syntax Reference for `metadata.json`

The metadata.json file is used to define the metadata for each build target in the HKU Notes project. This file is required for each build target as it contains information about how the target should be built, how it should be displayed and presented on the website.

Schema Versions

There are two versions of the metadata.json schema:

Schema v2 (Recommended)

The current recommended schema for new build targets. Features a flexible button system and uses the $schema field for version detection.

View v2 Documentation
Schema v1 (Legacy)

The legacy schema maintained for backward compatibility. Uses @metadata_file_version for version detection and supports primary/secondary button structure.

View v1 Documentation

Version Detection

The build pipeline automatically detects the schema version of each metadata.json file using the following priority:

$schema field - If present and contains schemas/v2.json, the file is treated as v2
@metadata_file_version field - Legacy method for both v1 and v2
Error - If neither field is present, the build will fail

Choosing a Schema Version

For new build targets: Use schema v2 with the $schema field
For existing build targets: No changes needed - v1 files will continue to work
Migrating from v1 to v2: See the v2 documentation for key differences

Common Concepts

Both schema versions share common naming conventions and structural concepts:

Key Naming Conventions

All keys in the metadata.json file should be in snake_case format. In this documentation, dots (.) are used to represent a hierarchy of keys. Keys should not contain dots in their names.

Example

The key build.build_command would mean:

Correct Interpretation

{
    "build": {
        "build_command": "..."
    }
}

rather than:

Incorrect Interpretation

{
    "build.build_command": "..."
}

An arbitrary object of an array is denoted using [i]. The keys of the object are enclosed within curly braces {}.

Example

The key static_site.buttons[i].{text} would mean:

{
    "static_site": {
        "buttons": [
            {
                "text": "Button 1"
            },
            {
                "text": "Button 2"
            }
        ]
    }
}

Next Steps

Select the appropriate schema version documentation for detailed field references:

Schema v2 Documentation - Recommended for new projects
Schema v1 Documentation - Reference for legacy projects

Syntax Reference for metadata.json