publiccode.yml
publiccode.yml
| Type | object |
|---|---|
| File match |
publiccode.yml
|
| Schema URL | https://catalog.lintel.tools/schemas/schemastore/publiccode-yml/latest.json |
| Source | https://www.schemastore.org/publiccode.json |
Validate with Lintel
npx @lintel/lintel checkpubliccode.yml is a metadata standard for repositories containing software developed or acquired by the Public Administration, aimed at making them easily discoverabile and thus reusable by other entities.
By including a publiccode.yml file in the root of a repository, and populating it with information about the software, technicians and civil servants can evaluate it. Automatic indexing tools can also be built, since the format is easily readable by both humans and machines.
publiccode.yml is mandatory for all public software developed in Italy, according to the national guidelines: this enables the Developers Italia crawler to build the national software catalog. The standard is designed to be interoperable internationally, thus the country-specific keys are separated by the core part and are defined in specific sections that each government can rule.
Properties
This key specifies the version to which the current publiccode.yml adheres to, for forward compatibility.
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.
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.
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.
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.
4 nested properties
This string describes the license under which the software is distributed. The string must contain a valid SPDX expression, referring to one (or multiple) open-source license. Please refer to the SPDX documentation for further information.
This string describes the entity that owns the copyright on "most" of the code in the repository. Normally, this is the line that is reported with the copyright symbol at the top of most files in the repo.
It is possible to list multiple owners if required so, using an English sentence. It is also possible to informally refer to a community of group of people like "Linus Torvalds and all Linux contributors".
In case it is not possible to name a main copyright owner, it is possible to omit this key; in those cases, if the repo has a authors file, you can point to it through legal/authorsFile.
This string describes the entity that owns this repository; this might or might not be the same entity who owns the copyright on the code itself. For instance, in case of a fork of the original software, the repoOwner is probably different from the mainCopyrightOwner.
Some open-source software adopt a convention of identify the copyright holders through a file that lists all the entities that own the copyright. This is common in projects strongly backed by a community where there are many external contributors and no clear single/main copyright owner. In such cases, this key can be used to refer to the authors file, using a path relative to the root of the repository.
This section provides information on the maintenance status of the software, useful to evaluate whether the software is actively developed or not.
3 nested properties
This key describes how the software is currently maintained.
This key describes the entity or entities, if any, that are currently contracted for maintaining the software. They can be companies, organizations, or other collective names.
One or more contacts maintaining this software.
This key describes the technical people currently responsible for maintaining the software. All contacts need to be a physical person, not a company or an organisation. If somebody is acting as a representative of an institution, it must be listed within the affiliation of the contact.
In case of a commercial agreement (or a chain of such agreements), specify the final entities actually contracted to deliver the maintenance. Do not specify the software owner unless it is technically involved with the maintenance of the product as well.
This section provides an overview of the localization features of the software.
2 nested properties
If yes, the software has infrastructure in place or is otherwise designed to be multilingual. It does not need to be available in more than one language.
If present, this is the list of languages in which the software is available. Of course, this list will contain at least one language. The primary language subtag cannot be omitted, as mandated by the BCP 47.
This key contains the name of the "suite" to which the software belongs.
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.
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.
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.
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.
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.
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.
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.
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.
A list of words that can be used to describe the software and can help building catalogs of open software.
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.
A link to a public roadmap of the software.
3 nested properties
This key explicitly includes certain countries in the intended audience, i.e. the software explicitly claims compliance with specific processes, technologies or laws. All countries are specified using ISO 3166-1 alpha-2 two-letter country codes.
This key explicitly marks countries as NOT supported. This might be the case if there is a conflict between how software is working and a specific law, process or technology. All countries are specified using ISO 3166-1 alpha-2 two-letter country codes.
This key contains a list of tags related to the field of application of the software.
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.
3 nested properties
This key contains a list of runtime dependencies that are distributed under an open-source license.
This key contains a list of runtime dependencies that are distributed under a proprietary license.
This key contains a list of hardware dependencies that must be owned to use the software.
2 nested properties
The organisation publishing the software as a stable resolvable URI or a persistent identifier.
The canonical name of the organisation publishing the software.
A list of organisations that are currently known to be funding the development of this software.
4 nested properties
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.
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.
4 nested properties
If present and set to true, the software is compliant with the Italian accessibility laws (L. 4/2004), as further explained in the linee guida di design (Italian language).
If present and set to true, the software is compliant with the linee guida sull'interoperabilità.
Regulatory reference: Art. 73 del CAD (Italian language).
If present and set to true, the software is compliant with the Misure minime di sicurezza ICT per le Pubbliche amministrazioni (Italian language).
If present and set to true, the software is compliant with the Misure minime di sicurezza ICT per le Pubbliche amministrazioni (Italian language).
5 nested properties
If present and set to true, the software interfaces with SPID - il Sistema Pubblico di Identità Digitale.
If present and set to true, the software interfaces with the Italian electronic ID card (Carta di Identità Elettronica).
If present and set to true, the software interfaces with ANPR.
If present and set to true, the software interfaces with pagoPA.
If present and set to true, the software interfaces with IO app (https://io.italia.it)
1 nested properties
This key represents the administration code inside the Public Administration index (codice IPA).
Definitions
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.
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 "[email protected]". 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 number (with international prefix). This has to be a string.
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.
The name of the contractor, whether it's a company or a physical person.
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.
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 "[email protected]". 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.
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.
The name of the dependency (e.g. MySQL, NFC Reader)
The first compatible version
The latest compatible version
The only major version for which the software is compatible. It assumes compatibility with all patches and bugfixes later applied to this version.
Whether the dependency is optional or mandatory
The organisation publishing the software as a stable resolvable URI or a persistent identifier.
The canonical name of the organisation publishing the software.