The publiccode.yml Standard

What is publiccode.yml

Public Administrations often create valuable software, but reuse is often limited due to poor discoverability or difficulty understanding if a project fits another administration's context.

publiccode.yml solves this by providing a human-readable and machine-readable metadata file.

It answers the questions:

• What does this project do? (name, description, languages)
• What is its status? (concept, development, beta, stable, obsolete)
• Who maintains it and until when?
• Who to contact for technical/support inquiries?
• What legal frameworks is it designed for?
• What are its dependencies?

Example

A minimal publiccode.yml file:

publiccodeYmlVersion: "0"
name: My text editor
url: "https://example.com/mysoftware/text-editor.git"
platforms:
  - windows
developmentStatus: development
softwareType: standalone/desktop
description:
  en:
    shortDescription: A lightweight text editor
    longDescription: >
          A lightweight yet powerful text editor designed for everyday use by developers,
          writers, and public administrations. It also supports syntax highlighting.
    features:
       - Syntax highlighting
       - Collaborative editing features
       - Scripting interface
legal:
  license: AGPL-3.0-or-later
maintenance:
  type: community
  contacts:
    - name: Margaret Hamilton
localisation:
  localisationReady: true
  availableLanguages:
    - en
    - de
    - fr

See all available fields...

Finding projects

Finding projects depends on how the search API is structured for every hosting platform. For example, you can find all publiccode.yml files in the root directory of projects on GitHub, either by using the search frontend or the API.

• GitHub Search path:/^publiccode.yml$/

Versioning

This project follows the Semantic Versioning.

See all versions

Contributing

Feel free to submit Pull Requests, file Issues or open a Discussion.

The Standard's website is built using the Python Sphinx package and deployed on GitHub Pages from the publiccodeyml.github.io repository.

Prerequisites

• uv

Local development process

sphinx-build can be used to compile all source files of the current checkout to static html files. Run this command to generate the website:

uv run sphinx-build docs/standard build -c .

then open the relevant file in the build directory with a browser (e.g., build/index.html) to explore the contents.

Hot reloading

sphinx-autobuild can be used to make use of hot reloading.

uv run sphinx-autobuild docs/standard build -c .

All the versions

The published website puts every version line of the Standard side by side, one directory per major version (/v0/, /v1/, ...) with a version switcher on each page. Each line is built from the newest release tag of its major version (v0.7.0, ...), or from its draft branch (1.0-rc, ...) while unreleased, using the conf.py and templates of the current checkout, see poly.py. Tags come with the clone, draft branches must exist locally (e.g. git branch 1.0-rc origin/1.0-rc), then:

uv run sphinx-polyversion poly.py build/html

To preview the switcher on the current checkout alone, without building every branch:

uv run sphinx-polyversion poly.py build/html -l

Tooling

Tools and libraries that implement and support the publiccode.yml Standard.

Core tools

Core tools are developed alongside the publiccode.yml specification and provide its reference implementations and supporting components.

• libpubliccode

• publiccode-parser-php

• publiccode-crawler

• open-catalog-api

• publiccode-api-client

• publiccode-parser-action

• publiccode-parser-gitlab-ci

• publiccode-validator-api

• publiccode-issueopener

• JSON Schema on SchemaStore

Third-party tooling

Maintained separately from the core tooling, but widely used in practice.

• publiccode-editor

• publiccode-parser-orb

More tools can e.g. be found by searching for the GitHub topic publiccode.

License

Licensed under the CC0-1.0.