Public administrations often create valuable software. Other administrations rarely reuse it, because the software is hard to find. It is also hard to tell whether a project fits another administration's context.
publiccode.yml is a human-readable and machine-readable metadata
file placed in the root of a repository. It answers these 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?
It is designed to be easy to add to any new project and to grow as the project evolves.
A minimal publiccode.yml file:
publiccodeYmlVersion: "1"
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- Create a
publiccode.ymlfile in the root directory of the repository, starting from the example above. - Check it with the GitHub Action or the GitLab CI job, so that every change to the file is validated.
- Update the file when the project changes, for example its development status, maintainers or supported languages.
Each code hosting platform has its own search. On GitHub, this search
finds every publiccode.yml file in the root directory of a repository:
This project follows the Semantic Versioning.
Read the contributing guide before opening an issue or a pull request. Questions and proposals are welcome in Discussions.
Translations of the documentation live in publiccodeyml/translations.
The Standard's website is built using the Python Sphinx package and deployed on GitHub Pages from the publiccodeyml.github.io repository.
Each major version of the Standard has its own directory, spec/v0 and
spec/v1. sphinx-build compiles one of them to static HTML files. Run
this command to generate the version 1 website:
uv run sphinx-build spec/v1 build -c .Then open a file of the build directory in a browser, for example
build/index.html. Use spec/v0 instead for version 0.
sphinx-autobuild rebuilds the website and reloads the browser on every
change:
uv run sphinx-autobuild spec/v1 build -c .The published website puts every major version of the Standard side by
side, one directory per major version (/v0/, /v1/, ...) with a
version switcher on each page. A major version with a release is built
from its newest release tag (v0.8.0, ...). A major version with no
release yet is built from the spec/vN directory of the last commit of
the current checkout, as a draft (1.0-rc, ...) marked by a banner.
Every version uses the conf.py and templates of the current checkout,
see poly.py. Tags come with the clone, then:
uv run sphinx-polyversion poly.py build/htmlTo preview the draft with the switcher, uncommitted changes included, without building the release tags:
uv run sphinx-polyversion poly.py build/html -lTools and libraries that implement and support the publiccode.yml Standard.
Core tools are developed alongside the publiccode.yml specification and provide its reference implementations and supporting components.
-
Parser and validator library. Reference implementation of the specification.
- Bindings: PHP (via FFI)
- CI: GitHub Action, GitLab CI
- Validator API: RESTful API returning validation errors and warnings
-
Crawler to discover and collect descriptor files for catalogs.
-
RESTful API powering software catalogs for public administrations, used to store, query and expose all catalog data about FLOSS solutions.
- CLI client to query the catalog API (alpha)
-
Opens GitHub issues to repos in a software catalog with invalid publiccode.yml files.
-
JSON Schema definition mainly used by editors and IDEs for coarse validation and autocompletion.
Maintained separately from the core tooling, but widely used in practice.
-
User friendly editor and basic validator for publiccode.yml files (maintained by Developers Italia, Italian Government).
Licensed under the CC0-1.0.
