Key publiccodeYmlVersion¶

• Type: string
• Presence: mandatory
• Example: "0.1"

This key specifies the version to which the current publiccode.yml adheres to, for forward compatibility.

Key name¶

• Type: string
• Presence: mandatory
• Example: "Medusa"

This key contains the name of the software. It contains the (short) public name of the product, which can be localised in the specific localisation section. It should be the name most people usually refer to the software. In case the software has both an internal “code” name and a commercial name, use the commercial name.

Key applicationSuite¶

• Type: string
• Presence: optional
• Example: "MegaProductivitySuite"

This key contains the name of the “suite” to which the software belongs.

Key url¶

• Type: string (URL)
• Presence: mandatory
• Example: "https://example.com/italia/medusa.git"

A unique identifier for this software. This string must be a URL to the source code repository (git, svn, …) in which the software is published. If the repository is available under multiple protocols, prefer HTTP/HTTPS URLs which don’t require user authentication.

Forks created for the purpose of contributing upstream should not modify this file; this helps software parsing publiccode.yml to immediately skip technical forks. On the contrary, a complete fork that is meant to be maintained separately from the original software should modify this line, to give themselves the status of a different project.

See Forks and variants for a complete description of what is a software variant and how to handle forked software as a parser or an author.

Key landingURL¶

• Type: string (URL)
• Presence: optional
• Example: "https://example.com/italia/medusa"

If the url parameter does not serve a human readable or browsable page, but only serves source code to a source control client, with this key you have an option to specify a landing page. This page, ideally, is where your users will land when they will click a button labeled something like “Go to the application source code”. In case the product provides an automated graphical installer, this URL can point to a page which contains a reference to the source code but also offers the download of such an installer.

Key isBasedOn¶

• Type: string or array of strings
• Presence: optional
• Example: "https://github.com/italia/otello.git"

In case this software is a variant or a fork of another software, which might or might not contain a publiccode.yml file, this key will contain the url of the original project(s).

The existence of this key identifies the fork as a software variant, descending from the specified repositories.

Key softwareVersion¶

• Type: string
• Presence: optional
• Example: "1.0", "dev"

This key contains the latest stable version number of the software. The version number is a string that is not meant to be interpreted and parsed but just displayed; parsers should not assume semantic versioning or any other specific version format.

The key can be omitted if the software is currently in initial development and has never been released yet.

Key releaseDate¶

• Type: string (date)
• Presence: mandatory
• Example: "2017-04-15"

This key contains the date at which the latest version was released. This date is mandatory if the software has been released at least once and thus the version number is present.

Key logo¶

• Type: string (relative path to file or absolute URL)
• Presence: optional
• Acceptable formats: SVG, SVGZ, PNG
• Example: "img/logo.svg"

This key contains the path to the logo of the software. Logos should be in vector format; raster formats are only allowed as a fallback. In this case, they should be transparent PNGs, minimum 1000px of width. The key value can be the relative path to the file starting from the root of the repository, or it can be an absolute URL pointing to the logo in raw version. In both cases, the file must reside inside the same repository where the publiccode.yml file is stored.

Key monochromeLogo¶

• Type: string (path to file)
• Presence: optional
• Acceptable formats: SVG, SVGZ, PNG
• Example: "img/logo-mono.svg"

A monochromatic (black) logo. The logo should be in vector format; raster formats are only allowed as a fallback. In this case, they should be transparent PNGs, minimum 1000px of width. The key value can be the relative path to the file starting from the root of the repository, or it can be an absolute URL pointing to the logo in raw version. In both cases, the file must reside inside the same repository where the publiccode.yml file is stored.

Key inputTypes¶

• Type: array of enumerated strings
• Presence: optional
• Values: as per RFC 6838
• Example: "text/plain"

A list of Media Types (MIME Types) as mandated in RFC 6838 which the application can handle as input.

In case the software does not support any input, you can skip this field or use application/x.empty.

Key outputTypes¶

• Type: array of enumerated strings
• Presence: optional
• Values: as per RFC 6838
• Example: "text/plain"

A list of Media Types (MIME Types) as mandated in RFC 6838 which the application can handle as output.

In case the software does not support any output, you can skip this field or use application/x.empty.

Key platforms¶

• Type: enumerated string or array of strings
• Presence: mandatory
• Values: web, windows, mac, linux, ios, android. Human readable values outside this list are allowed.
• Example: web

This key specifies which platform the software runs on. It is meant to describe the platforms that users will use to access and operate the software, rather than the platform the software itself runs on.

Use the predefined values if possible. If the software runs on a platform for which a predefined value is not available, a different value can be used.

Key categories¶

• Type: array of strings
• Presence: mandatory
• Acceptable values: see List of software categories

A list of words that can be used to describe the software and can help building catalogs of open software.

The controlled vocabulary List of software categories contains the list of allowed values.

Key usedBy¶

• Type: array of strings
• Presence: optional

A list of the names of prominent public administrations (that will serve as “testimonials”) that are currently known to the software maintainer to be using this software.

Parsers are encouraged to enhance this list also with other information that can obtain independently; for instance, a fork of a software, owned by an administration, could be used as a signal of usage of the software.

Key roadmap¶

• Type: string
• Presence: optional

A link to a public roadmap of the software.

Key developmentStatus¶

• Type: enumerated string
• Presence: mandatory
• Allowed values: concept, development, beta, stable, obsolete

The keys are:

• concept - The software is just a “concept”. No actual code may have been produced, and the repository could simply be a placeholder.
• development - Some effort has gone into the development of the software, but the code is not ready for the end user, even in a preliminary version (beta or alpha) to be tested by end users.
• beta - The software is in the testing phase (alpha or beta). At this stage, the software might or might not have had a preliminary public release.
• stable - The software has seen a first public release and is ready to be used in a production environment.
• obsolete - The software is no longer maintained or kept up to date. All of the source code is archived and kept for historical reasons.

Key softwareType¶

• Type: enumerated string
• Presence: mandatory
• Allowed values: "standalone/mobile", "standalone/iot", "standalone/desktop", "standalone/web", "standalone/backend", "standalone/other", "addon", "library", "configurationFiles"

The keys are:

• standalone/mobile - The software is a standalone, self-contained The software is a native mobile app.
• standalone/iot - The software is suitable for an IoT context.
• standalone/desktop - The software is typically installed and run in a a desktop operating system environment.
• standalone/web - The software represents a web application usable by means of a browser.
• standalone/backend - The software is a backend application.
• standalone/other - The software has a different nature from the once listed above.
• softwareAddon - The software is an addon, such as a plugin or a theme, for a more complex software (e.g. a CMS or an office suite).
• library - The software contains a library or an SDK to make it easier to third party developers to create new products.
• configurationFiles - The software does not contain executable script but a set of configuration files. They may document how to obtain a certain deployment. They could be in the form of plain configuration files, bash scripts, ansible playbooks, Dockerfiles, or other instruction sets.

Section intendedAudience¶

Section description¶

This section contains a general description of the software. Parsers can use this section for instance to create a web page describing the software.

Note: since all the strings contained in this section are user-visible and written in a specific language, you must specify the language you are editing the text in (using the IETF BCP 47 specifications) by creating a sub-section with that name. The primary language subtag cannot be omitted, as mandated by the BCP 47.

An example for English:

description:
  en:
    shortDescription: ...
    longDescription: ...

In the following part of the document, all keys are assumed to be in a sub-section with the name of the language (we will note this with [lang]).

Note: it is mandatory to have at least one language in this section. All other languages are optional.

Section legal¶

Section maintenance¶

This section provides information on the maintenance status of the software, useful to evaluate whether the software is actively developed or not.

Section localisation¶

This section provides an overview of the localization features of the software.

Section dependsOn¶

This section provides an overview on the system-level dependencies required to install and use this software.

NOTE: do not list dependencies at the source code level (e.g.: software libraries being used), and focus only on runtime and/or system-level dependencies that must be installed and maintained separately. For instance, a database is a good example of such dependencies.

Dependency¶

A dependency is a complex object. The properties are the following:

• name - mandatory - The name of the dependency (e.g. MySQL, NFC Reader)
• versionMin - the first compatible version
• versionMax - the latest compatible version
• version - the only major version for which the software is compatible. It assumes compatibility with all patches and bugfixes later applied to this version.
• optional - whether the dependency is optional or mandatory

Complex versioning¶

It is of course possible to use the various keys to specify a complex compatibility matrix.

Ex. 1

- name: PostgreSQL
  version: "3.2"
  optional: yes

This snippet marks an optional dependency on PostgreSQL exactly version 3.2.

Ex. 2

- name: MySQL
  versionMin: "1.1"
  versionMax: "1.3"

This snippet marks a mandatory dependency on MySQL, allowing any version between 1.1 and 1.3.

Contact¶

A Contact is an object with the following properties:

• name - mandatory - This key contains the full name of one of the technical contacts. It must be a real person; do NOT populate this key with generic contact information, company departments, associations, etc.
• email - This key contains the e-mail address of the technical contact. It must be an email address of where the technical contact can be directly reached; do NOT populate this key with mailing-lists or generic contact points like “info@acme.inc”. The e-mail address must not be obfuscated. To improve resistance against e-mail collection, use \x64 to replace @, as allowed by the YAML specification.
• phone - phone number (with international prefix). This has to be a string.
• affiliation - This key contains an explicit affiliation information for the technical contact. In case of multiple maintainers, this can be used to create a relation between each technical contact and each maintainer entity. It can contain for instance a company name, an association name, etc.

Contractor¶

A Contractor is an object with the following properties:

• name - mandatory - The name of the contractor, whether it’s a company or a physical person.
• until - mandatory - This is a date (YYYY-MM-DD). This key must contain the date at which the maintenance is going to end. In case of community maintenance, the value should not be more than 2 years in the future, and thus will need to be regularly updated as the community continues working on the project.
• email - This key contains the e-mail address of the technical contact. It must be an email address of where the technical contact can be directly reached; do NOT populate this key with mailing-lists or generic contact points like “info@acme.inc”. The e-mail address must not be obfuscated. To improve resistance against e-mail collection, use \x64 to replace @, as allowed by the YAML specification.
• website - This key points to the maintainer website. It can either point to the main institutional website, or to a more project-specific page or website.

Dates¶

All dates in publiccode.yml must follow the format “YYYY-MM-DD”, which is one of the ISO8601 allowed formats. This is the only allowed format though, so not the full ISO8601 is allowed for the date keys.

Encoding¶

publiccode.yml MUST be UTF-8 encoded.

Key countryExtensionVersion¶

• Type: string
• Presence: mandatory
• Example: "1.0"

This key specifies the version to which the current extension schema adheres to, for forward compatibility.

Please note how the value of this key is independent from the top-level publiccodeYmlVersion one (see The Standard (core)). In such a way, the extensions schema versioning is independent both from the core version of the schema and from every other Country.

Key conforme¶

This section contains the keys for auto-declaring the compliance with the current legislation, with respect to the following sections. Not including these keys implies that the compliance is not known or not declared.

Section piattaforme¶

Section riuso¶

This section contains a set of keys related to the publication of the software inside the reuse catalog of Developers Italia.

Parsers¶

Parsers SHOULD identify a technical fork by noticing that the top-level url key does not point to the repository in which the publiccode.yml is found.

Parsers MIGHT identify a technical fork also through metadata that might be exposed by the code hosting platform (eg: GitHub marks forks explicitly as forks)

Authors¶

Authors of technical forks SHOULD NOT modify publiccode.yml in any way. Specifically, they MUST NOT modify the top-level url key that MUST continue pointing to the original repository.

There is no explicit key to mark a fork as a technical fork. This is a conscious design decision because we do not want authors of technical forks to be aware of publiccode.yml and necessarily be aware of how to modify it. The current design does not require authors to do anything.

Parsers¶

Parsers SHOULD identify a variant by noticing that the top-level url key matches to the repository in which the publiccode.yml is found, AND a top-level isBasedOn exists and points to a different repository.

Parsers should expect and analyze other differences in publiccode.yml between variants of the software. Specifically description/features is designed to be compared across variants to identify and show user-visible differences.

Authors¶

Authors that are willing to publish a fork as a variant MUST at least:

• add a key isBasedOn pointing to one or more upstream repositories from which this variant is derived.
• Change the value for url to point to the repository holding the variant.
• Change the value for legal/repoOwner to refer to the themselves (the authors of the variant).
• Revisit the maintenance section to refer to the maintenance status of the variant.

Moreover, authors SHOULD evaluate the following changes:

• add the features that differentiate the variant to the description/features key. Existing features SHOULD NOT be edited or removed from this list unless they have been removed from the variant, to allow parsers to easily compare feature lists.