Skip to content

Creating a publiccode.yml

The publiccode.yml file is a standard format for metadata that can be used to describe open source projects in the public sector.

On openCode, all entries in the software directory are automatically imported from the respective publiccode.yml files of the projects on the GitLab instance. Conversely, this means that only projects that contain a valid publiccode.yml file will appear in the directory.

These instructions are designed to help you create such a publiccode.yml file for your software.

How do I create a working publiccode-yml file?

  1. Open your project on GitLab
  2. Navigate to Repository > Files

  3. Create a new file named publiccode.yml. Use the openCode editor or download this annotated template.

    What you need to consider when creating the publiccode.yml file

  4. Maintain the basic data: Start with the official schema, such as the name, version of your software, the URL, and appropriate categories. You can find a list of possible entries on the metadata standard page.

    publiccodeYmlVersion: "0.4"    # Version of the publiccode.yml format. Please only change this if you know what you are doing. 
name: "PROJEKT_NAME"    # Name of the software
url: "https://gitlab.opencode.de/IHR_PROJEKT"    # URL to your project. The URL is usually the direct link to your openCode repository. Please note that you may only link to a project and not to a group.
landingURL: "https://IHR-PROJEKT.de"    # URL to your software's website
softwareVersion: “1.0.1”    # Latest version of your software
softwareVersion: "1.0.1"    # Aktuelleste Version Ihrer Software
releaseDate: "2022-01-24"    # Release Date
logo: logo.svg     # Path to the logo in the top folder of the project. The path to your logo is relative to the top folder of your project. Permitted file formats are: .svg, .svgz, and .png
platforms:    # Supported platforms. Please select from the following entries: web, windows, mac, linux, ios, android. Custom entries are not possible.
    - linux
    - windows
    - mac
    usedBy:    # Reuse. Any number of entries are possible.
    - Zendis
categories:    # Categories that describe your software. Please select one or more categories from the publiccode standard: https://yml.publiccode.tools/categories-list.html. Custom entries are not possible. 
    - financial-reporting
    - email-marketing
developmentStatus: development    # Development status. Select one of the following options: concept, development, beta, stable, obsolete.
softwareType: "standalone/desktop"    # Software type. Select one of the following options: standalone/backend, standalone/desktop, standalone/iot, standalone/mobile, standalone/web, standalone/other, addon, library, configurationFiles
localisation:
    localisationReady: true
    availableLanguages:    #  Supported languages. Languages in the form of a lowercase IETF BCP 47 language tag (see https://en.wikipedia.org/wiki/IETF_language_tag). Custom entries are not possible.
        - de
        - en

  5. Fill in the project description: Explain briefly and clearly what your software project is and illustrate it with meaningful screenshots. Our recommendation: Maintain two languages!

    description:
    de:
        genericname: >  # Dieser Schlüssel ist der "genericName", der sich auf die spezifische Kategorie bezieht, zu der die Software gehört. Sie können den generischen Namen normalerweise in einer Präsentation der Software finden, wenn Sie etwas wie folgt schreiben: "Software xxx ist ein yyy" Nennenswerte Beispiele sind zum Beispiel: "Texteditor", "Textverarbeitung", "Webbrowser", "Chat" und so weiter... Der generische Name darf bis zu 35 Zeichen lang sein
        shortDescription: >    # Kurze Beschreibung AUF DEUTSCH. Maximal 150 Zeichen 
        Eine kurze Beschreibungen, welche
        mehrere Zeilen umfassen kann.
        longDescription: >    # Ausführliche Beschreibung AUF DEUTSCH. Dieser Schlüssel enthält eine längere Beschreibung der Software, zwischen 500 und 10000 Zeichen. Sie soll einem potenziellen Benutzer einen Überblick über die Fähigkeiten der Software für einen potenziellen Benutzer geben. Die Zielgruppe für diesen Text sollten die Benutzer der Software sein, nicht die Entwickler. Sie können sich diesen Text vorstellen Text als die Beschreibung der Software, die auf Ihrer Website zu finden wäre (wenn Sie eine hätte). Diese Beschreibung kann einige grundlegende Markdown-Elemente enthalten: *Kursiv*, **fett**, - Aufzählungen und [Links](#)
        Eine sehr lange Beschreibung dieser Software,
        auch auf mehrere Zeilen aufgeteilt.
        Sie sollten beschreiben, worum es bei der Software geht
        und warum man Sie benötigt.
        Hier könnten potenziell viele Seiten Text enthalten sein.
        features:    # Auflistung der Features Ihrer Software (Anführungszeichen beachten!)
        - "Das erste Feature"
        - "Ein anderes zweites Feature"
        screenshots:    # Bildschirmfotos Ihres Projekts. Pfad zu Ihren Screenshots. Die Pfade sind ausgehend von dem obersten Ordner Ihres Projekts
            - .opencode/screenshots/sshot1.jpg
            - .opencode/screenshots/sshot2.jpg
            - .opencode/screenshots/sshot3.jpg
    en:
        genericname: >  # This key is the “genericName,” which refers to the specific category to which the software belongs. You can usually find the generic name in a presentation of the software when you write something like this: “Software xxx is a yyy.” Notable examples include: “text editor,” “word processor,” “web browser,” “chat,” and so on... The generic name can be up to 35 characters long.
        shortDescription: >    # Short description IN ENGLISH. Maximum 150 characters.
        A rather short description that
        can span multiple lines.
        longDescription: >    # Detailed description IN ENGLISH. This key contains a longer description of the software, between 500 and 10,000 characters. It should give a potential user an overview of the capabilities of the software. The target audience for this text should be the users of the software, not the developers. You can think of this text as the description of the software that would be found on your website (if you had one). This description can contain some basic Markdown elements: *italics*, **bold**, - bullet points, and [links](#).
        Very long description of this software, also split
        on multiple rows. You should note what the software
        is and why one should need it. We can potentially
        have many pages of text here.

    Attention

    If you have added a description in a language, you must also adjust the corresponding values under the entry localisation. If you have provided a description in German and English, this entry should look as follows:

    localisation:
    localisationReady: true
    availableLanguages:
        - de
        - en

  6. Determine the target audience (countries and subject areas) for the software:

    intendedAudience:
    countries: # Countries (https://de.wikipedia.org/wiki/ISO-3166-1-Kodierliste) that correspond to the target group. In lowercase letters!
        - "de"
    scope: # Subject areas that most closely correspond to those of your software. The supported entries can be found at https://yml.publiccode.tools/scope-list.html# scope-list. You cannot enter your own entries.
        - "local-authorities"
        - "environment"

    Note

    The country codes differ in some cases from the language codes (under availableLanguages and description). The possible country codes for this entry can be found on the Wikipedia page on ISO 3166-1 country codes. Contrary to the spelling in the Wikipedia article, the country codes must be entered in lowercase letters.

  7. Add license and contact persons: Specify the license under which your project is licensed and where the code is located. The selected license must be on our list of permitted licenses. You should also name a contact person who is responsible for the software.

    Note

    In addition to specifying the license in publiccode.yml, a LICENSE file is also required in the main directory of the project, which contains information about the licenses used in the software. Our Badge API accesses this LICENSE file—not the publiccode.yml.

    legal:
license: AGPL-3.0-or-later    # Open source license used. A list of approved licenses can be found in the openCode knowledge section: https://opencode.de/wissen/rechtssichere-nutzung/open-source-lizenzen#2.-Open-Source-Lizenzliste. Entries in the SPDX identifier format specified on the page are valid.

maintenance:
type: "community"    # Type of support. Please select one of the following options: internal, contract, community, none
contacts:    # List of contacts who support the software
    - name: "Francesco Rossi"
    email: "francesco.rossi@zendis.de"
contractors:    # Contract partners
    - name: ZenDis
    email: "hallo@zendis.de"
    website: "zendis.de"
    until: "2023-01-01"

  8. Check and publish: The easiest way to check your publiccode.yml file is to load it into our openCode Editor and then click on the Validate button. If the file is error-free, nothing stands in the way of publication. After creating the file, your project will automatically appear in the software directory shortly thereafter.

Customizing the display in the openCode software directory

To customize the display of your software in the software directory to best suit your needs, we recommend following the detailed instructions for customizing the display in the software directory in this guide.

Best Practices from the community

The following examples from the community may be useful for you to understand how to create a publiccode.yml file:

Frequently asked questions and problems

Why are my project's logo or screenshots not displayed?

If your project's logo or screenshots are not displayed, this may be due to the following errors:

  • Your logo or screenshots are not yet listed in the publiccode.yml file. Add the file and complete the path name. The logo file must be located in the top-level folder of your project.
  • Add screenshots in the description section under the section for the respective supported language (e.g., en).
  • You may be using an unsupported file format. Valid file formats for logos are: .svg, .svgz, and .png. Valid file formats for screenshots are: .png and .jpg.
  • The path you specified for your logo file is incorrect. Check the path.
How do I find errors in my publiccode.yml file?

The best way to create your publiccode.yml file is to use our publiccode.yml editor.

In the editor, you can display errors in your file either after uploading your publiccode.yml file or after filling in the corresponding fields using the Validate button.