upmeta

Universal Project Metadata Format

A simple, language-agnostic structure for project metadata.

v1.0.0
File Name: project.toml
File Extension: .toml
Format Version: v1.0

Documentation

The Universal Project Metadata Format aims to standardize project metadata across programming ecosystems. It is human-readable, machine-parseable, and supports key information like project name, version, authors, and dependencies.

This format is ideal for polyglot projects, CI/CD systems, documentation generation, and more.

The metadata file for your project should follow the naming convention specified below. This ensures consistency across projects and facilitates tool compatibility.

Place the project.toml file in the root of your project directory. This ensures that tools and systems relying on this metadata can locate it easily.

Sections

1. [project]

  • name: The name of the project.
  • version: The current version of the project.
  • description: A short description of the project.
  • homepage: The official website URL for the project.
  • repository: URL of the project's source repository.
  • license: The project's license (e.g., MIT, Apache 2.0).

2. [authors]

  • primary: The main author of the project.
  • contributors: A list of additional contributors.

3. [maintainers]

  • main: The main maintainer of this project,
  • backup: A list of additional maintainers.

4. [dependencies]

  • python: Minimum Python version required.
  • nodejs: Minimum Node.js version required.
  • rust: Minimum Rust version required.

5. [platforms]

  • os: Supported operating systems.
    Valid values include:
    • "linux" – All Linux distributions.
    • "windows" – Microsoft Windows.
    • "macos" – macOS systems.
    • "freebsd" – FreeBSD systems.
    • "android" – Android platforms.
    • "ios" – iOS platforms.
    • "unix" – General Unix-like systems.
    • "any" – Compatible with all operating systems.
  • arch: Supported processor architectures.
    Valid values include:
    • "x86" – 32-bit x86 architecture.
    • "x86_64" – 64-bit x86 (amd64).
    • "armv7" – 32-bit ARM architecture.
    • "arm64" – 64-bit ARM architecture.
    • "riscv64" – 64-bit RISC-V architecture.
    • "ppc64le" – 64-bit PowerPC (little-endian).
    • "any" – Compatible with all architectures.

6. [funding]

  • url: Funding url.

Example (TOML)

[project]
name = "Example Project"
version = "1.0.0"
description = "A universal project metadata example"
homepage = "https://example.com"
repository = "https://github.com/example/project"
license = "MIT"
tags = ["library", "data-science", "open-source"]
public = true

[authors]
primary = "Jane Doe <jane.doe@example.com>"
contributors = ["John Smith <john.smith@example.com>"]

[maintainers]
main = "Jane Doe <jane.doe@example.com>"
backup = ["John Smith <john.smith@example.com>", "Team Alpha <alpha-team@example.com>"]

[dependencies]
python = ">=3.8"
nodejs = ">=16.0"
rust = ">=1.60.0"

[platforms]
os = ["linux", "windows", "macos"]
arch = ["x86_64", "arm64"]

[funding]
url = "https://opencollective.com/example"