publiccodeyml/publiccode.yml

A metadata standard for public software

The publiccode.yml Standard

A metadata description standard for public software that is easy to use both for developers and people with less technical background in order to make the software developed by Public Administrations and Public Organisations easily discoverable.

Charter | Voting procedure | Contributing

What publiccode.yml is for

Many great software projects are developed by public administrations, however reuse of these projects is very limited. Some of the reasons for low uptake of such projects is a lack of discoverability and that it is hard to find out what project can actually work in the context of a different public administration.

The publiccode.yml file is meant to solve all those problems. It is an easily readable file for civil servants that are trying to figure out whether a project will work for them, and easily readable by computers as well. It contains information such as:

• the title and description of the project in English and/or other languages;
• the development status, e.g. concept, development, beta, stable, obsolete;
• which organisation developed the project;
• who is caring for the maintenance and when this expires;
• who to contact for technical or support inquiries;
• what national and local legal frameworks the project is designed for;
• what software dependencies the project has.

The publiccode.yml file format should both be able to easily be added to any new project, as well as grow with the project as it expands beyond the original context it was developed in.

Finding projects

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

• GitHub Search path:publiccode.yml

Versioning

Latest release: See all versions

This project follows the Semantic Versioning. For more information see SemVer.org.

Furthermore, the project uses branches and tags in the following way:

• The main branch contains the improvements coming up in the next version.
• Release page contains all the released versions of the standard. Releases are tagged with the Standard's version.

Contributing

Feel free to submit Pull Requests and to file Issues.

Licence

Licenced under the CC0-1.0.

publiccode.yml's Issues

Consider removing genericName

As of now, genericName is mandatory and limited to 35 characters.

However, field experience is showing that this field always contains information that is already carried by shortDescription, softwareType and categories. We should consider removing genericName if no good reason for it arises.

[IT] Add 'it/conforme/lineeGuidaAccessibilita'

Context

Italian Public Administrations only

Details

Since Jan '20 it is necessary to attach a mandatory certification stating that the application/website is accessible (see https://docs.italia.it/AgID/documenti-in-consultazione/lg-accessibilita-docs/it/stabile/index.html in Italian language).
As such, I believe the publiccode.yml specification should provide the possibility to add this conformity.

Proposal

I suggest adding the following

key:  `it/conforme/lineeGuidaAccessibilita`
type: `boolean`
presence: `optional`

Review the list of tags

As of now, the list of allowed values for the tags key is not very comprehensive and government-oriented, and it mixes two distinct ontologies:

• what the software is
• what the software is used for

There's backend but there's no mobile app or website or web application.
There are amusement and instant-messaging but there's no culture or cultural heritage or human resources management or time tracking or open data or gis or many other categories of public software.

Phone values must be treated as strings

Right now there are some issues with the way the phone numbers are represented in this YAML file and the way the parser handles them.
As such, I propose switching the phone value to always be a string.

Consider changes in usedBy

As of now, it is not clear if the usedBy key should contain also the name of the PA which owns the copyright or not. Probably it should be clearer.

Add changelog

We should add a changelog page that lists all changes between versions, for easing developers of parsers/editors/validators.

Move German documentation files to the correct docs folder

By mistake, we put the German documentation into the root folder. Could you please move the files to the correct /docs/de/ folder please?

Change yes/no to true/false

This specification defines a YAML file which should use yes/no is accepted in several places. However, the meaning of yes/no is ambiguous in YAML. In YAML 1.1 and older these values represent booleans, but in YAML 1.2 they don’t, meaning they represent strings.

I suggest to remove this ambiguity by changing them to unambigous booleans (true/false) in the specification.

Make sure examples are valid YAML (quotes etc.)

Not all the publiccode.yml examples in this repository are valid, since they were hand-crafted. String values containing double colons (:) such as URLs should be enclosed in single or double quotes.

Do not limit contact's pointers to email

A software could have:

• a website
• one or more social pages
• a Forum Italia topic
• ...

Which could be helpful to learn more about it or ask questions.

Expand the Contact https://docs.italia.it/italia/developers-italia/publiccodeyml/it/master/schema.core.html#contatto
definition to allow for URLs and not just emails.

Use landingURL variable to create a link to the project site

While working on the publication of GlobaLeaks i've noticed that the variable landingURL (https://github.com/globaleaks/GlobaLeaks/blob/main/publiccode.yml#L5) apprears not used anywhere on the profile of the software.

This ticket is to propose to use the value of the landingURL variable in order to create a link "Site" on the right sidebar to be shown over the link "Documentation

Consider removing government scope

I believe the word government is out of scope since it does not clearly identify anything in the context of a Public Administration (i.e., every PA is a "government" or it's operating in the "government" sphere).
As such, I propose to remove the government word from the list of scopes.

Boolean fields values should be true or false

Instead of 'yes' boolean type should be true or false

"This repository is structured in order to be compatible with the Docs Italia platform."

Ciao.

Ho provato a fare il mio primo "publiccode.yml".
Ho letto il readme e nella sezione Documentation farei un'aggiunta e/o una modifica.
Forse sono io che non mastico molto la materia, ma non avevo capito che

"This repository is structured in order to be compatible with the Docs Italia platform."
voleva dire: vai al link e leggiti le istruzioni

Così mi sono fatto un mio publiccode.yml copiando quelli di 18app, per poi capire che
in docs italia platform c'era l'editor.

Potrebbe essere interessante mettere nella documentazione dopo

"This repository is structured in order to be compatible with the Docs Italia platform."
Una riga che dica (scusate l'inglese, ci provo)
"If you want a fast track to create your publiccode.yml go [here](link all'editor)"

Grazie mille!
E' stato divertente provare a rendere codice pubblico per il nostro Paese e la PA!
Spero che il mio codice sia indexato correttamente e di non aver fatto qualche errore, nonchè sia utile ad altri!

Andrea

[IT] Add platform io-pagopa

We should add io or pagopa (or both) to the platforms sections

Contractor's until should be in the future

The standard should state that until needs to be a date in the future, ie. a date in the past should result in an invalid publiccode.yml, because the correct way to describe it would be using maintenance/type: none.

We are already hinting it:

https://docs.italia.it/italia/developers-italia/publiccodeyml-en/en/master/schema.core.html#section-maintenance

Key maintenance/type
This key describes how the software is currently maintained.

Key maintenance/contractors
This key describes the entity or entities, if any, that are currently contracted for maintaining the software

Add link to the Docs Italia version in the README

Many web pages link to this GitHub repository. We should put a visible link in the README that points to the Docs Italia version(s) for easier browsing experience.

Extended fields that aren't country specific?

If publiccode.yml were used to document civic tech projects produced in affiliation with local volunteer groups (e.g. Code for America / Code for All brigades) we'd like to document the name of which group within publiccode.yml

The local group is not always the repo owner and not always the copyright owner, nor does it make sense to use a country-specific extension

What approaches to adding this information could be faithful to the format? Essentially we're trying to describe what organization facilitates/moderates/houses a project. This might be the same thing as when a project joins an org like OSI/CNCF. I can't think of a generic term that covers all these cases. Maybe they are different, since volunteer groups don't consolidate copyright ownership like the foundations do

If there's not a standard field to add for this, then the question might change to how do you add extensions that are program-specific rather than country-specific

Convert into RST for Docs Compatibility

The whole repo has to be converted into RST format for Docs Italia compatibility.

Consider to change softwareVersion not static

Now the software version is static, it could alternatively indicate a URL, or for the artifacts present on maven central it would be enough to indicate the groupId and the artifactId

Clarification on intendedAudience/countries key usage when the software has a broad worldwide target audience

While working on the Globaleaks publication we are experiencing difficulties giving a value to the key intendedAudience.

Similarly to a Content Management System (CMS), GlobaLeaks has a broad target audience so that the current intendedAudience seems to require to list an unlimited set of country codes with significant inefficiency.

I suggest this key could be extended / documented clarifying how this condition should be handled.

Use BCP-47 for language codes

Consider creating a microservices key

Current situation

We are experiencing some issues with projects containing different repos inside.
Let's make an example.

PROJECT A
--> microservice 1
--> microservice 2
...
--> microservice n

Right now our solution is to tell PAs to create a new repo, let's call it metarepo, in order to store the information regarding the whole project. This metarepo will contain the publiccode.yml file which will be indexed in the catalog.
However, this solution has some flaws:
a) if the metarepo does not have a clear README file, the information regarding the other repositories (containing the n microservices) will be rather vague or lost. This is suboptimal.
b) the vitality index is calculated exclusively based upon the information regarding the metarepo and this does not make sense.

Proposal

We should add a key, called for example components or microservices, containing the list of repositories "related" to the project. As such, the metarepo will still contain the publiccode.yml file inside but each repo will be somehow listed in the catalog. This could also facilitate the calculation of the vitality index.

Fix broken links

Fix this set of broken links pointing to the old repo structure.
See:

➜  publiccode.yml git:(development) ✗ grep -rnw "w3id"
docs/en/schema.md:44:* Example: `"http://w3id.org/publiccode/version/0.1"`
docs/en/example/publiccode.yml:1:publiccodeYamlVersion: "http://w3id.org/publiccode/version/0.2"
docs/en/example/publiccode.yml:23:# For a list of allowed values, check out w3id.org/publiccode/version/0.1/tags.html
docs/en/example/publiccode.minimal.yml:1:publiccode-yaml-version: "http://w3id.org/publiccode/version/0.1"
docs/it/schema.it.md:80:Il parser applicherà il corretto prefisso al valore dato a questa chiave per creare un'URI identificativa, una volta che questo sarà definito. L'URI sarà riconducibile a http://w3id.org/italia/data secondo la politica degli URI adottata in ambito [DAF](https://developers.italia.it/it/daf).
docs/it/example/publiccode.yml:1:publiccodeYamlVersion: "http://w3id.org/publiccode/version/0.2"
docs/it/example/publiccode.yml:23:# For a list of allowed values, check out w3id.org/publiccode/version/0.1/tags.html
docs/it/example/publiccode.minimal.yml:1:publiccode-yaml-version: "http://w3id.org/publiccode/version/0.1"

`type` key name change proposal

The current Maintenance/type key (https://github.com/italia/publiccode.yml/blob/master/docs/it/schema.rst#chiave-maintenancetype) creates some possible collisions with the JSON schema type keyword. This may be a problem during validation.
I'd suggest changing the maintenance/type property to something else.

Suggestions:

• maintenance/typology
• maintenance/form
• maintenance/variant
• maintenance/kind

Set-up a translation infrastructure

We need a simple way to manage translations and evolve the standard with automated consistency checks.

The master copy needs to be developed in English, translations are handled with a separate workflow and can be done separately. With a build-like process translated versions are created and uploaded, without the need for manual merges.

Consider a "noindex" key

In the last couple of months we faced situations where the publiccode.yml:

• is a "placeholder" filled with Lorem Ipsum;
• is under construction (not totally filled);
• has been copied from another repo and the information contained inside are not related to the project;
• is a test repo;
• other possibilities.

As such, I wonder if it could be feasible to add a decentralized mechanism to tell the spiders not to index such a file.
I was thinking at something like a boolean "noindex" key which simply states whether the repo should be indexed or not yet.
What do you think about this?
I think that acting in a centralized way from the spider perspective (e.g., using something like a blacklist) is harder since it requires the intervention of the spider's responsibles who are external from the software publishers group, it does not scale, it is very error prone and it requires a communication channel to be established at least twice.

The main risk is of course that someone could leave the value to "true" and such a software would never be indexed.

What do you think?

Relative vs absolute URLs

Some fields expect relative paths to files contained in the repository. For example description/[lang]/screenshots and legal/authorsFile. It should be clearly stated that those fields are expected to contain either:

• a relative path to a file contained in the repository (relative to the publiccode.yml file, thus to the repository root)
• an absolute URL pointing to the raw file, but only if the file is contained in the same repository as the publiccode.yml file itself

This limitation ensures that the file is owned by the software publisher, or published under an open license, so that there's no potential issue in embedding it in a catalog.

Consider making legal/repoOwner mandatory

As of now, it/riuso/codiceIPA is specified to be mandatory only if legal/repoOwner is a Public Administration. However legal/repoOwner is an optional key, so this creates ambiguity.

We should consider either making legal/repoOwner mandatory or changing the specification for it/riuso/codiceIPA so that it does not mention legal/repoOwner.

Minimum logo size

Discussion

Currently the standard states 1000px minimum. https://github.com/italia/publiccode.yml/blob/libremente-patch-1/docs/it/schema.rst#chiave-monochromelogo
I guess we should discuss this further.

Clarification on inputTypes key usage when the software supports any file type

While working on the Globaleaks publication we are experiencing difficulties giving a value to the key inputTypes.

Similarly to a Content Management System (CMS), GlobaLeaks could manage every kind of file so that the current inputTypes seems to require us to list an unlimited set of mime types with significant inefficiency.

I suggest this key could be extended / documented clarifying how this condition should be handled.

Add email to Contractor

We need an optional email field for each contractor. While there's already website, and a company website contains all the contact information, someone might want to publish a specific address for each software project.

Allow multiple values for softwareType

Looks like for now softwareType accepts only a single value.
As our application is both standalone/desktop and standalone/mobile, we would need to add both...

Please change softwareType to accept enumerated string or array of strings.

Add "Whistleblowing" to the software categories list

Whistleblowing software is a category of software that currently does not fit in any of the currently defined software categories list and that is defined by many existing and upcoming regulations (e.g. 190/2012, 179/2017, EU Regulation 2016/679) that determine specific software capabilities.

This ticket is to propose the addition of a specific software category "Whistleblowing".

Here are examples of two softwares that would fit in this category:

• https://developers.italia.it/it/software/globaleaks-globaleaks-f22648.html
• https://developers.italia.it/it/software/c_l736-comune_venezia-whistleblowing

Naming issue "public administration"

Proposal for discussion

The term public administration, now used throughout the schema, should be reviewed.
Proposals:

• public bodies
• public authorities
• others...

@alranel

Add laborHours field

Add the following optional field to the main section:

laborHours: [integer] An estimate of total labor hours spent by your organization/component across all versions of this release. This includes labor performed by federal employees and contractors. See the Code.gov summary for calculating labor hours.

cc @RicardoAReyes

Review publiccode

A list of questions:

• Spinal-case or camelCase?
  https://github.com/italia/publiccode.yml/blob/master/version/development/example/publiccode.yml#L1
• Consider summary and description or avoid dict["description"]["*description"]
  https://github.com/italia/publiccode.yml/blob/master/version/development/example/publiccode.yml#L54
• Always use url instead of website or other synonims.
  https://github.com/italia/publiccode.yml/blob/master/version/development/example/publiccode.yml#L95
• Why is that? https://github.com/italia/publiccode.yml/blob/master/version/development/example/publiccode.yml#L14
• Potentially long https://github.com/italia/publiccode.yml/blob/master/version/development/example/publiccode.yml#L29
• Why Countries? https://github.com/italia/publiccode.yml/blob/master/version/development/example/publiccode.yml#L44
• Use plurals eg features not datatypes
  https://github.com/italia/publiccode.yml/blob/master/version/development/example/publiccode.yml#L70
• name, url, email everywhere
  https://github.com/italia/publiccode.yml/blob/master/version/development/example/publiccode.yml#L95
• Here's Diego "Zoro" Bianchi
  https://github.com/italia/publiccode.yml/blob/master/version/development/example/publiccode.yml#L104
• bcp47
  https://github.com/italia/publiccode.yml/blob/master/version/development/example/publiccode.yml#L116
• still open point as there are big entities (eg. AdE) under a single IPA entity
  https://github.com/italia/publiccode.yml/blob/master/version/development/example/publiccode.yml#L148

Updates to the Italian section

• As of #45 we have a new core scope key which basically matches the ontology represented by our it/riuso/ecosistemi. Thus we can remove it/riuso/ecosistemi.

• Change conforme/accessibile to conforme/linee-guida-design

• Change conforme/interoperabile to conforme/modello-interoperabilita

• Change conforme/sicuro to conforme/misure-minime-sicurezza

• Change conforme/privacy to conforme/gdpr

• Move spid, cie, anpr, pagopa under a new piattaforme section

New categories

Let's use this issue for tracking proposals for new categories:

• whistleblowing

Consider adding a "technologies" multi value field

Many open source civic tech catalogs include search by technology (like java or sql or nodejs, etc.). I'd make it mandatory if possible, from a developer potential contributor this is an important information.

Finding a connection with the PublicCode.Directory

Dear all,

The great FSFE and OpenUK people have also come up with a decentralised Public Code dissemination strategy at FOSDEM last year, what are the odds!

They've developed the publiccode.directory as a way for Public Coders to find Public Code projects. As part of the project they've also developed a JSON based datamodel for projects that aims to achieve very similar things as this standard.

They've expressed intent to figure out how we can combine forces with the two projects and combine our common goal of ultimate Public Code discoverability.

Check out the entries in their repository: https://github.com/OpenUK/publiccode.directory

Consider removing monochromeLogo

Consider relaxing the format of inputTypes and outputTypes

As of now, inputTypes and outputTypes are restricted to MIME types. This is proving to be a bit too restrictive, as some file types/extensions do not have a MIME type. We should consider relaxing this syntactic requirement, maybe turning it into a recommendation (so that editors can display a tentative combobox instead of a comprehensive dropdown).

Consider adding phone international prefix as mandatory

Right now, the phone field may or may not have an international prefix (e.g., +39).
It may be better to set such prefix as mandatory.
@ruphy @alranel

Define the encoding used.

The standard should explicitly state the encoding used by the YAML file, which should most probably be UTF-8.

Consider requiring at least one screenshot

Maybe in a future version.

Consider allowing longer features

As of now, each feature under description/[lang]/features shall not exceed 100 characters. This is a bit too short, as longer sentences might be needed, especially when mentioning laws etc. 200 or 250 might be good values.

Make contacts optional if maintenance/type is contract

As of now, at least one item in contacts is always required. However, if maintenance/type is contract, we already fill the contractor contact information and it may be not feasible to name an individual person.

So let's make the logic as follows:

• if maintenance/type is contract, at least one contractor is required
• if maintainance/type is internal or community, at least one (individual) contact is required
• if maintainance/type is none, nothing is required

Independent versioning for country-specific extensions?

As of now, every update to fields defined in a country-specific extension (for instance it/riuso/codiceIPA) would require to increment the publiccodeYmlVersion field.

While this is semantically correct, it triggers unneeded extra work by all implementers. Whenever a country makes an update to its extension, all the parsers need to be updated in order to accept the newer version number even if they are not affected by the change.

We should consider adding a version field to each country extension, and not increment publiccodeYmlVersion when country extensions are updated. This way, each parser can update the list of versions it supports only if it is affected by the change (i.e. if the change affects the common part or a country-specific extension it supports).

Default branch for storing the publiccode.yml file

Discussion

Since there are no indications whether the default branch where to store the publiccode.yml file has to be master, maybe the standard should provide more details.
This may be a problem when a repository does not have a branch named master.