Skip to content

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 v1 has been phased out

All existing build targets have been migrated to schema v2. Schema v1 is no longer supported. Pull requests that introduce build targets using v1 schema will not be merged until updated to v2.

  • Schema v2 (Required)

    The only supported schema for all build targets. Features a flexible button system and uses the $schema field for version detection.

    View v2 Documentation

  • Schema v1 (Phased Out)

    No longer supported. All targets have been migrated to v2. This documentation is kept for historical reference only.

    View v1 Documentation

Version Detection

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

  1. $schema field - If present and contains schemas/v2.json, the file is treated as v2
  2. @metadata_file_version field - Legacy fallback for historical v1 and v2 files
  3. Error - If neither field is present, the build will fail

Using Schema v2

All build targets must use schema v2 with the $schema field. See the v2 documentation for the full list of fields.

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: