Metadata Configuration

When custom metadata is provided, we always upload all the custom metadata known about a sample and automatically configure it based on the schemas defined in your .lightly/metadata/schema.json file.

When navigating to the Metadata Configurator view in the Lightly Platform, you see all previously configured custom metadata entries.


Custom Metadata Entry

An entry consists of

  • a name referenced throughout the Lightly Platform
  • a path to where this particular key is located within your custom metadata JSON
  • a fallback/default value if the path can't be retrieved for a sample
  • a data type of the value

You can add a new custom metadata entry at the bottom of the view. When adding a new entry, we propose different paths based on the custom metadata JSON provided and also show some example values for you to better understand the values a specific path is retrieving.


Data Type

Lightly supports numeric and categorical custom metadata, which have different use cases and enable additional features within the Lightly Platform.


A numeric data type is used for linear values that have a range. Numeric custom metadata can be used, e.g., in the histograms of the metadata view, when sorting samples, or to project the ranges in the embedding page.

We support:

  • Float
  • Integer

A categorical data type is used for categorical values which fall into specific "buckets". Categorical custom metadata can be used, e.g., to segment the samples into clusters in the embedding page.

We support:

  • Strings
  • Integers
  • Booleans (true, false)
  • Datetime (ISO 8601 format YYYY-MM-DDTHH:mm:ss.sssZ)
  • Timestamp (Unix timestamp)