Lo Standard publiccode.yml

publiccode.yml è uno standard di metadati ideato per essere inserito in repository contenenti software della Pubblica Amministrazione con lo scopo di renderli facilmente individuabili e, di conseguenza, riutilizzabili da altri enti.

Inserendo nella root di un repository un file chiamato publiccode.yml che descrive le caratteristiche del software se ne agevola la comprensione ai tecnici e ai decisori pubblici interessati a valutarlo; al tempo stesso si permette di costruire strumenti automatici di indicizzazione, poiché il formato è facilmente leggibile sia da esseri umani sia da macchine.

publiccode.yml è obbligatorio per tutto il software pubblico sviluppato in Italia, come da linee guida: questo consente al crawler automatico di Developers Italia di costituire il catalogo del software a riuso. Lo standard è tuttavia pensato in ottica internazionale, per cui tutte le specificità nazionali sono separate dal core e definite in apposite sezioni estensibili autonomamente dai governi nazionali.

Tra le informazioni contenute in un publiccode.yml vi sono:

  • il titolo e la descrizione del progetto o prodotto (in una o più lingue);

  • lo stato dello sviluppo ad es., concept, development, beta, stable, obsolete;

  • i riferimenti dell’organizzazione che ha sviluppato il progetto;

  • chi si sta occupando della sua manutenzione e quando il rapporto finirà;

  • per quale quadro giuridico è stato pensato questo progetto o prodotto;

  • quali dipendenze software esistono.

e molte altre informazioni rilevanti.

Indice dei contenuti

Lo standard (core)

La struttura di un file publiccode.yml prevede l’esistenza di chiavi top-level e sezioni che possono contenere al proprio interno altre chiavi. Lo standard ha rilevanza internazionale ma è possibile dichiarare una sezione dedicata per le chiavi relative ad un Paese specifico (si veda Estensioni nazionali per maggiori dettagli).

Chiavi e Sezioni Top-Level

Chiave publiccodeYmlVersion

  • Tipo: stringa

  • Presenza: obbligatoria

  • Esempio: "0.1"

Questa chiave specifica la versione alla quale il presente publiccode.yml aderisce, per una questione di compatibilità diretta.

Chiave name

  • Tipo: stringa

  • Presenza: obbligatoria

  • Esempio: “Medusa”

Questa chiave contiene il nome del software. Contiene il nome (abbreviato) pubblico del prodotto, che può essere tradotto nella sezione specifica chiamata localisation. Dovrebbe essere il nome con il quale la maggior parte delle persone si riferisce al suddetto software. Nel caso in cui il software abbia sia un nome in “codice” interno che uno commerciale, è preferibile usare il nome commerciale.

Chiave applicationSuite

  • Tipo: stringa

  • Presenza: opzionale

  • Esempio: “MegaProductivitySuite”

Questa chiave contiene il nome della “suite” alla quale il software appartiene.

Chiave url

  • Tipo: stringa (URL)

  • Presenza: obbligatoria

  • Esempio: "https://example.com/italia/medusa.git"

Un identificatore unico per questo software. Questa stringa deve essere una URL che punta al repository di codice sorgente (git, svn, …) nel quale il software è pubblicato. Se il repository è disponibile sotto diversi protocolli, preferire URL HTTP/HTTPS che non richiedono l’autenticazione.

I fork creati con lo scopo di contribuire upstream non devono modificare questo file; questo aiuta i software che fanno il parsing di publiccode.yml a saltare immediatamente i fork tecnici. Al contrario, un fork completo che sarà manutenuto in modo separato rispetto al software originale, dovrebbe modificare questa linea per essere trattato come una variante distinta.

Vedi Fork e varianti per una descrizione completa del significato di variante software e di come gestire i fork sia lato parser che lato autore.

Chiave landingURL

  • Tipo: stringa (URL)

  • Presenza: opzionale

  • Esempio: "https://example.com/italia/medusa"

Se la chiave url non porta ad una pagina leggibile da un umano, ma serve solo ad indirizzare un client di source control verso il codice sorgente, con questa chiave viene introdotta l’opzione di specificare la landing page. Questa pagina, idealmente, è il punto di arrivo dell’utente quando seleziona un pulsante chiamato, ad esempio, “Vai al codice sorgente dell’applicazione”. Nel caso in cui il prodotto preveda un installer grafico automatico, questa URL può puntare alla pagina contenente un riferimento al codice sorgente ma che offra anche la possibilità di scaricare tale installer.

Chiave isBasedOn

  • Tipo: stringa o array di stringhe

  • Presenza: opzionale

  • Esempio: "https://github.com/italia/otello.git"

Nel caso in cui questo software sia una variante o un fork di un altro software, che opzionalmente può contenere un file publiccode.yml, questa chiave conterrà la url di uno o più progetti originali.

L’esistenza di questa chiave identifica il fork come una variante (vedi Fork e varianti), discendente dal repository specificato.

Chiave softwareVersion

  • Tipo: stringa

  • Presenza: opzionale

  • Esempio: "1.0", "dev"

Questa chiave contiene il numero dell’ultima versione stabile del software. Il numero di versione è una stringa che non è pensata per essere interpretata dal parser ma solamente visualizzata; i parser non devono assumere l’utilizzo del semantic versioning o altri specifici formati di versionamento.

Questa chiave può essere omessa nel caso in cui il software sia in una fase iniziale di sviluppo e non sia stato ancora rilasciato.

Chiave releaseDate

  • Tipo: stringa (data)

  • Presenza: obbligatoria

  • Esempio: "2017-04-15"

Questa chiave contiene la data di ultimo rilascio del software. Questa data è obbligatoria se il software è stato rilasciato almeno una volta e dunque esiste un numero di versione.

Chiave inputTypes

  • Tipo: array di stringhe

  • Presenza: opzionale

  • Valori: vedi RFC 6838

  • Esempio: text/plain

Una lista di Media Types (MIME Types), come specificato dal RFC 6838, che possono essere gestiti in input dall’applicazione.

Nel caso in cui il software non supporti alcun input, è possibile saltare questo campo o usare application/x.empty.

Chiave outputTypes

  • Tipo: array di stringhe

  • Presenza: opzionale

  • Valori: vedi RFC 6838

  • Esempio: text/plain

Una lista di Media Types (MIME Types), come specificato dal RFC 6838, che possono essere gestiti in output dall’applicazione.

Nel caso in cui il software non supporti alcun output, è possibile saltare questo campo o usare application/x.empty.

Chiave platforms

  • Tipo: stringhe o array di stringhe

  • Presenza: obbligatoria

  • Valori: web, windows, mac, linux, ios, android. Valori leggibili da un umano al di fuori di questa lista sono permessi.

  • Esempio: web

Questa chiave specifica su quale piattaforma funziona il software. È pensata per descrivere le piattaforme che l’utente userà per accedere ed utilizzare il software, piuttosto che la piattaforma sul quale il software gira.

Se possibile, usare i valori predefiniti. Se il software gira su una piattaforma per la quale un valore predefinito non è disponibile, un diverso valore può essere usato.

Chiave categories

Una lista di parole che possono essere usate per descrivere il software e possono aiutare a costruire il catalogo di software open.

Il vocabolario controllato Lista delle categorie di software presenta la lista dei valori accettabili.

Chiave usedBy

  • Tipo: array di stringhe

  • Presenza: opzionale

Una lista di nome di prominenti Pubbliche Amministrazioni (che serviranno come “testimonial”) che il maintainer riconosce come utilizzatori attuali di questo software.

I parser sono incoraggiati ad accrescere questa lista anche con altre informazioni che riescono ad ottenere in modo indipendente; ad esempio, il fork di un software, di proprietà di un’amministrazione, può essere usato come un segnale di uso del software.

Chiave roadmap

  • Tipo: stringa

  • Presenza: opzionale

Un link ad una roadmap pubblica del software.

Chiave developmentStatus

  • Tipo: stringa

  • Presenza: obbligatoria

  • Valori permessi: concept, development, beta, stable, obsolete

Le chiavi sono:

  • concept - Il software è solo un “concept”. Non è stato sviluppato codice e il repository potrebbe semplicemente essere un placeholder.

  • development - Qualche sforzo è stato fatto in direzione dello sviluppo del software ma il codice non è pronto per l’utenza finale, nemmeno in una versione preliminare (beta o alpha) per essere testato dall’utenza.

  • beta - Il software è in fase di testing (alpha o beta). In questo stage, il software potrebbe aver o non aver ancora avuto una release pubblica preliminare.

  • stable - Il software ha già avuto una prima release pubblica ed è pronto per essere usato in un contesto di produzione.

  • obsolete - Il software non è più manutenuto o aggiornato. Tutto il codice sorgente è archiviato e tenuto per ragioni di storico.

Chiave softwareType

  • Tipo: stringa

  • Presenza: obbligatoria

  • Valori permessi: standalone/mobile, standalone/iot, standalone/desktop, standalone/web, standalone/backend, standalone/other, addon, library, configurationFiles

Le chiavi sono:

  • standalone/mobile - Il software è un pacchetto self-contained, standalone. Il software è un’applicazione nativa per dispositivi mobile.

  • standalone/iot - Il software è adatto ad essere utilizzato nel contesto Internet of Things.

  • standalone/desktop - Il software è tipicamente installato e utilizzato su un sistema operativo desktop.

  • standalone/web - Il software rappresenta un applicativo fruibile attraverso il web.

  • standalone/backend - Il software è un applicativo backend.

  • standalone/other - Il software ha una natura diversa rispetto a quanto specificato alle chiavi precedenti.

  • softwareAddon - Il software è un addon, come ad esempio un plugin o un tema, per un software più complesso (e.g., un CMS o una suite per ufficio).

  • library - Il software contiene una libreria o una SDK che facilita la creazione di nuovi prodotti a sviluppatori di terze parti.

  • configurationFiles - Il software non contiene script eseguibili ma una serie di file di configurazione. Questi potrebbero documentare come ottenere un certo tipo di deployment. I suddetti file potrebbero avere la forma di semplici file di configurazione, script bash, playbook ansible, Dockerfile, o altri set di istruzioni.

Sezione intendedAudience
Chiave intendedAudience/countries

  • Tipo: array di stringhe

  • Presenza: opzionale

Questa chiave include in modo esplicito alcuni Paesi tra il pubblico previsto, i.e., il software rivendica esplicitamente la conformità con processi specifici, tecnologie o leggi. Tutti i Paesi sono specificati usando country code a due lettere seguendo lo standard ISO 3166-1 alpha-2.

Chiave intendedAudience/unsupportedCountries

  • Tipo: array di stringhe

  • Presenza: opzionale

Questa chiave contrassegna esplicitamente i Paesi NON supportati. Questa situazione potrebbe verificarsi nel momento in cui esista un conflitto tra la modalità di funzionamento del software ed una legge specifica, un processo o una tecnologia. Tutti i Paesi sono specificati usando country code a due lettere seguendo lo standard ISO 3166-1 alpha-2.

Chiave intendedAudience/scope

Questa chiave contiene una lista di tag che rappresentano il campo di applicazione del software.

I tag consentiti sono elencati nella Lista dei campi di applicazione.

Sezione description

Questa sezione contiene una descrizione generale del software. I parser possono usare questa sezione ad esempio per creare una pagina web che descriva il software.

Nota bene: siccome tutte le stringhe contenute in questa sezione sono visibili all’utente e scritte in un linguaggio specifico, è necessario specificare il linguaggio con il quale si sta modificando il testo. Per farlo è necessario creare una sezione dedicata alla lingua seguendo le specifiche IETF BCP 47. Si ricorda che il primary language subtag non può essere omesso, come specificato nel BCP 47.

Un esempio per l’italiano:

description:
  it:
    shortDescription: ...
    longDescription: ...

Nelle parti successive del documento, tutte le chiavi sono assunte essere all’interno di una sezione con il nome della lingua (annoteremo questo con [lang]).

Nota bene: è obbligatorio avere almeno una lingua in questa sezione. Tutte le altre lingue sono opzionali.

Chiave description/[lang]/localisedName

  • Tipo: stringa

  • Presenza: opzionale

  • Esempio: “Medusa”

Questa chiave rappresenta un’opportunità di tradurre il nome in una lingua specifica. Contiene il nome pubblico (corto) del prodotto. Dovrebbe essere il nome con il quale la maggioranza delle persone normalmente si riferisce al software. Nel caso in cui il software abbia sia un nome “interno” che uno commerciale, è preferibile utilizzare quello commerciale.

Chiave description/[lang]/genericName

  • Tipo: stringa (max 35 caratteri)

  • Presenza: obbligatoria

  • Esempio: “Text Editor”

Questa chiave rappresenta il “Nome generico”, riferito alla categoria specifica alla quale il software appartiene. Normalmente è possibile trovare il nome generico nella presentazione del software, quando si scrive una frase del tipo: “Il software xxx è un yyy”. Esempi degni di nota includono “Editor di Testi”, “Word Processor”, “Web Browser”, “Chat” e così via. Il nome generico può avere una lunghezza fino a 35 caratteri.

Chiave description/[lang]/shortDescription

  • Tipo: stringa (max 150 caratteri)

  • Presenza: obbligatoria

  • Esempio: "Sistema avanzato di prenotazione per ospedali"

Questa chiave contiene una breve descrizione del software. Dovrebbe essere una singola linea contenente una singola frase. L’estensione massima consentita è di 150 caratteri.

Chiave description/[lang]/longDescription

  • Tipo: stringa (min 500 caratteri, max 10000 caratteri)

  • Presenza: obbligatoria (almeno per una lingua)

Questa chiave contiene una descrizione più lunga del software, con una lunghezza che può variare da 500 a 1000 caratteri. Questa chiave è pensata per fornire una panoramica delle caratteristiche del software per un potenziale utente. Il destinatario di questo testo dovrebbe essere l’utente finale, non nello sviluppatore. E’ possibile pensare a questo testo come alla descrizione del software che potrebbe stare nel sito web (nel caso in cui il software ne possieda uno).

Questa descrizione può contenere del Markdown base: *italic*, **bold**, elenchi puntati e [link](#).

Chiave description/[lang]/documentation

  • Tipo: URL

  • Presenza: opzionale

Questa chiave contiene un riferimento alla documentazione lato utente (non lato sviluppatore) Questo valore deve essere una URL che punta ad una versione ospitata della documentazione.

È suggerito che questa URL punti ad una versione ospitata della documentazione che sia direttamente leggibile utilizzando un comune web browser sia in formato desktop che mobile. La documentazione dovrebbe essere renderizzata in HTML e navigabile come un sito web (con un indice, una barra di ricerca, etc.).

Se la documentazione dovesse invece essere disponibile esclusivamente sotto forma di documento, è possibile inserire il link diretto per vedere/scaricare tale documento, sotto forma di URL, in questa chiave. E’ consigliabile trattare la documentazione come parte del codice sorgente e dunque gestirla tramite commit sul repository del codice sorgente. In questo modo, sarà possibile fornire una URL diretta alla piattaforma di hosting del codice (ad es., GitHub URL al file). E’ preferibile utilizzare formati aperti quali PDF o ODT per avere la massima interoperabilità. Qualunque sia il formato della documentazione, è importante ricordare di rilasciarne i sorgenti coperti da licenza aperta, possibilmente effettuandone un commit all’interno del repository stesso.

Chiave description/[lang]/apiDocumentation

  • Tipo: URL

  • Presenza: opzionale

Questa chiave contiene un riferimento alla documentazione delle API del software. Il valore deve essere una URL verso una versione ospitata della documentazione.

E’ suggerito che questa URL punti ad una versione ospitata della documentazione che sia direttamente leggibile utilizzando un comune web browser. La documentazione dovrebbe essere renderizzata in HTML e navigabile come un sito web (con un indice, una barra di ricerca, etc.), e se c’è un riferimento ad un deployment di prova, questo dovrebbe offrire un’interfaccia navigabile (e.g. Swagger).

Se la documentazione dovesse invece essere disponibile esclusivamente sotto forma di documento, è possibile inserire il link diretto per vedere/scaricare tale documento, sotto forma di URL, in questa chiave. E’ consigliabile trattare la documentazione come parte del codice sorgente e dunque gestirla tramite commit sul repository del codice sorgente. In questo modo, sarà possibile fornire una URL diretta alla piattaforma di hosting del codice (ad es., GitHub URL al file). E’ preferibile utilizzare formati aperti quali PDF o ODT per avere la

Qualunque sia il formato della documentazione, è importante ricordare di rilasciarne i sorgenti coperti da licenza aperta, possibilmente effettuandone un commit all’interno del repository stesso.

Chiave description/[lang]/features

  • Tipo: array di stringhe

  • Presenza: obbligatoria (almeno per una lingua)

Questa chiave contiene una lista di feature del software, che descriva le possibilità offerte dallo stesso. Il target di questo testo sono i decisori pubblici che potranno decidere di adottarlo o modificarlo. Per questo motivo, queste feature non devono riferirsi agli sviluppatori: invece di elencare le caratteristiche tecniche riferite ai dettagli implementativi, è preferibile elencare le funzionalità lato utente.

Anche se questa chiave è obbligatoria, non c’è un limite minimo o massimo sul numero di feature da elencare in questa chiave. Ogni feature deve però avere un massimo di 100 caratteri.

Il numero di feature suggerito da elencare è tra 5 e 20, a seconda della dimensione del software e della sua complessità. Non c’è bisogno di fare una lista esaustiva, dal momento che gli utenti hanno sempre a disposizione la documentazione per reperire ulteriori informazioni.

Chiave description/[lang]/screenshots

  • Tipo: array di stringhe (percorsi)

  • Presenza: opzionale

  • Formati: PNG, JPG

  • Esempio: "data/screenshots/configuration.png"

Questa chiave indica una o più immagini del software (screenshot). Queste hanno lo scopo di dare una panoramica dell’aspetto del software e del suo funzionamento. Il valore può essere il percorso relativo al file a partire dalla root del repository, oppure una URL assoluta che punta all’immagine in versione raw. In entrambi i casi, il file deve risiedere all’interno del medesimo repository che contiene il publiccode.yml.

Queste immagini possono essere di qualsiasi formato e dimensione; i formati suggeriti sono:

  • Desktop: 1280x800 @1x

  • Tablet: 1024x768 @2x

  • Mobile: 375x667 @2x

Chiave description/[lang]/videos

  • Tipo: array di stringhe (URL)

  • Presenza: opzionale

  • Esempio: "https://youtube.com/xxxxxxxx"

Questa chiave contiene una o più URL di video che mostrano il funzionamento del software. Così come gli screenshot, i video dovrebbero essere usati per dare una rapida panoramica sull’aspetto e le funzionalità del software. I video devono essere ospitati su una piattaforma di video sharing che supporti lo standard oEmbed; le opzioni più popolari sono YouTube e Vimeo.

Nota bene: dal momento che costituisce parte integrante della documentazione, è opportuno che il video sia pubblicato con una licenza aperta.

Chiave description/[lang]/awards

  • Tipo: array di stringhe

  • Presenza: opzionale

Una lista di premi assegnati al software.

Sezione maintenance

Questa sezione fornisce informazioni sullo stato di manutenzione del software, utile per valutare se il software è attivamente sviluppato o meno.

Chiave maintenance/type

  • Tipo: enumerate

  • Presenza: obbligatoria

  • Valori: "internal", "contract", "community", "none"

Questa chiave descrive come il software è attualmente manutenuto. Le chiavi sono:

  • "internal" - significa che il software è manutenuto internamente dal proprietario del repository;

  • "contract" - significa che c’è un contratto commerciale che lega un’entità alla manutenzione del software;

  • "community" - significa che il software è attualmente manutenuto da una o più persone che offrono il loro tempo al progetto;

  • "none" - significa che il software non è al momento manutenuto.

Chiave maintenance/contractors

  • Tipo: array di Contractor (vedi sotto)

  • Presenza: obbligatoria (se maintenance/type è contract)

Questa chiave descrive l’entità o le entità, se ce ne sono, che attualmente hanno un contratto di manutenzione del software. Queste possono essere aziende, organizzazioni o altri nomi collettivi.

Chiave maintenance/contacts

  • Tipo: Lista di Contatti (vedi sotto)

  • Presenza: obbligatoria (se maintenance/type è internal oppure community)

Uno o più contatti di chi sta mantenendo il software.

Questa chiave descrive le persone tecniche che attualmente sono responsabili della manutenzione del software. Tutti i contatti devono essere di una persona fisica, non una un’azienda o un’organizzazione. Se un contatto funge da rappresentante di un’istituzione, questo rapporto deve essere esplicitato attraverso la chiave affiliation.

Nel caso di un accordo commerciale (o una catena di tali accordi), specificare le entità finali che sono effettivamente contrattate per fornire la manutenzione. Non specificare il proprietario del software a meno che sia tecnicamente coinvolto anche nella manutenzione del prodotto.

Sezione localisation

Questa sezione fornisce una panoramica sulle funzionalità di localizzazione del software.

Chiave localisation/localisationReady

  • Tipo: booleano

  • Presenza: obbligatoria

Se yes, il software ha l’infrastruttura o è stato progettato per essere multi-lingua. Ad ogni modo, questo campo non pregiudica l’esistenza di una traduzione in altre lingue ma si riferisce esclusivamente all’aspetto tecnologico. Per l’elenco delle lingue disponibili si veda la chiave localisation/availableLanguages.

Chiave localisation/availableLanguages

  • Tipo: lista di language tag secondo le specifiche IETF BCP 47

  • Presenza: obbligatoria

  • Esempio: "it", "en", "sl-IT-nedis"

Se presente, questa è la lista di lingue in cui è disponibile il software. Ovviamente, questa lista dovrà contenere almeno una lingua. Si ricorda che il primary language subtag non può essere omesso, come specificato dal BCP 47.

Sezione dependsOn

Questa sezione fornisce una panoramica delle dipendenze a livello di sistema necessarie per installare ed utilizzare il software.

Nota bene: non elencare le dipendenze a livello di codice sorgente (ad es., librerie software usate), e focalizza solo su dipendenze di sistema e/o a runtime che devono essere installate e manutenute separatamente. Ad esempio, un database è un buon esempio di questo tipo di dipendenza.

Chiave dependsOn/open

  • Tipo: array di dependency (vedi sotto)

  • Presenza: opzionale

Questa chiave contiene una lista di dipendenze a runtime che sono distribuite con una licenza di tipo open-source.

Chiave dependsOn/proprietary

  • Tipo: array di dependency (vedi sotto)

  • Presenza: opzionale

Questa chiave contiene una lista di dipendenze a runtime che sono distribuite con una licenza proprietaria.

Chiave dependsOn/hardware

  • Tipo: array di dependency (vedi sotto)

This key contains a list of hardware dependencies that must be owned to use the software.

Formati di dato speciali

Dependency

Una dependency è un oggetto complesso. Le proprietà sono le seguenti:

  • name - obbligatoria - Il nome della dipendenza (e.g. MySQL, NFC Reader);

  • versionMin - la prima versione compatibile;

  • versionMax - l’ultima versione compatibile;

  • version - l’unica versione major con la quale il software è compatibile. Si assume la compatibilità con tutte le patch e i bugfix che saranno applicati successivamente a questa versione;

  • opzionale - se la dipendenza è opzionale o obbligatoria.

Versioning complesso

E’ ovviamente possibile utilizzare le varie chiavi per specificare una matrice di compatibilità complessa.

Ex. 1

- name: PostgreSQL
  version: 3.2
  opzionale: yes

Questo snippet segnala una dipendenza opzionale verso PostgreSQL, nell’esattezza la sua versione 3.2.

Ex. 2

- name: MySQL
  versionMin: 1.1
  versionMax: 1.3

Questo snippet segnala una dipendenza obbligatoria verso MySQL, permettendo ogni versione tra la 1.1 e la 1.3.

Contatto

Un Contatto è un oggetto con le seguenti proprietà:

  • name - obbligatoria - Questa chiave contiene il nome completo di uno dei contatti tecnici. Deve essere una persona reale; NON popolare questa chiave con informazioni di contatto generiche, dipartimenti dell’azienda, associazioni, etc.

  • email - Questa chiave contiene l’indirizzo email del contatto tecnico. Deve essere un indirizzo email per il contatto diretto con il tecnico; NON popolare questa chiave con mailing-list o punti di contatto generico tipo “info@acme.inc”. Questo indirizzo email non deve essere offuscato. Per migliorare la resistenza contro la raccolta di indirizzi email, usare \x64 per sostituire @, siccome questo è permesso dalle specifiche YAML.

  • phone - Numero telefonico (con prefisso internazionale).

  • affiliation - Questa chiave contiene informazioni esplicite sui contatti tecnici. Nel caso esistano diversi maintainer, questa chiave può essere usata per creare relazioni tra diversi contatti tecnici e entità di manutenzione. Ad esempio, può contenere il nome di un’azienda, il nome di un’associazione, etc.

Contractor

Un Contractor è un oggetto con le seguenti proprietà:

  • name - obbligatoria - Il nome del contractor, sia esso un’azienda o una persona fisica.

  • until - obbligatoria - Questa è una data (YYYY-MM-DD). Questa chiave deve contenere una data alla quale la manutenzione finirà. Nel caso di manutenzione gestita dalla community, questo valore non deve essere maggiore di 2 anni nel futuro, e quindi deve essere regolarmente aggiornata man mano che la community continua a lavorare al progetto.

  • email - Questa chiave contiene l’indirizzo email del contatto tecnico. Deve essere un indirizzo email per il contatto diretto con il tecnico; NON popolare questa chiave con mailing-list o punti di contatto generico tipo “info@acme.inc”. Questo indirizzo email non deve essere offuscato. Per migliorare la resistenza contro la raccolta di indirizzi email, usare \x64 per sostituire @, siccome questo è permesso dalle specifiche YAML.

  • website - Questa chiave punta al sito del maintainer. Può puntare al principale sito istituzionale, o ad una pagina o sito più specifica.

Data

Tutte le date in publiccode.yml devono aderire al formato “YYYY-MM-DD” che è una delle codifiche permesse dal ISO8601. Nota bene: questa è l’unica codifica permessa, quindi non sono consentiti gli altri formati previsti da ISO8601.

Estensioni nazionali

Mentre il core è strutturato per essere significativo a livello internazionale, vi sono informazioni addizionali che possono essere aggiunte a livello nazionale, come ad esempio una dichiarazione di compatibilità con una legge locale. Il meccanismo di estensione fornito prevede l’utilizzo di sezioni specifiche per ogni Paese (country-specific).

Tutte le sezioni specifiche per ogni Paese sono contenute in una sezione denominata con l’ISO 3166-1 alpha-2 country code. Ad esempio, spid è una proprietà definita per i software italiani per la dichiarazione dell’eventuale compatibilità con il Sistema Pubblico di Identità Digitale.

Dunque, se un software è compatibile, troveremo:

it:
  countryExtensionVersion: "0.2"
  piattaforme:
     - spid: yes

Nota bene che le chiavi country-specific non sono valide all’interno delle sezioni internazionali. I Paesi che vogliano estendere il formato devono aggiungere una sezione dedicata.

Italia

Tutte le estensioni elencate qui di seguito sono specifiche per l’Italia e, di conseguenza, devono essere inserite in una sezione denominata con il codice it. Tutti i Paesi sono specificati usando country code a due lettere seguendo lo standard ISO 3166-1 alpha-2.

Chiave countryExtensionVersion

  • Tipo: stringa

  • Presenza: obbligatoria

  • Esempio: "1.0"

Questa chiave specifica la versione alla quale il presente schema di estensioni aderisce.

Nota Bene: il valore di questa chiave è indipendente da quello contenuto nella chiave top-level publiccodeYmlVersion (vedi Lo standard (core)). In questo modo, il versioning di ogni schema di estensioni è indipendente sia dalla versione core dello schema che da ogni altra estensione per Paese.

Sezione conforme

Questa sezione contiene delle chiavi per auto dichiarare la conformità con la normativa vigente, rispetto ad alcune sezioni. Se queste chiavi non vengono incluse, si intende che la conformità non è nota o non viene dichiarata.

Chiave conforme/lineeGuidaDesign

  • Tipo: booleano

  • Presenza: opzionale

Se presente e impostato a yes, il software è conforme alle leggi in materia di accessibilità (L. 4/2004), come descritto ulteriormente nelle linee guida di design.

Chiave conforme/modelloInteroperabilita

  • Tipo: booleano

  • Presenza: opzionale

Se presente e impostato a yes, il software è conforme alle linee guida sull’interoperabilità.

Riferimento normativo: Art. 73 del CAD.

Chiave conforme/misureMinimeSicurezza

  • Tipo: booleano

  • Presenza: opzionale

Se presente e impostato a yes, il software è conforme alle Misure minime di sicurezza ICT per le Pubbliche amministrazioni.

Chiave conforme/gdpr

  • Tipo: booleano

  • Presenza: opzionale

Se presente e impostato a yes, il software rispetta il GDPR.

Sezione piattaforme
Chiave spid

  • Tipo: booleano

  • Presenza: opzionale

Se presente e impostato a yes, il software si interfaccia con SPID - il Sistema Pubblico di Identità Digitale.

Chiave cie

  • Tipo: booleano

  • Presenza: opzionale

Se presente e impostato a yes, il software si interfaccia con la Carta di Identità Elettronica.

Chiave anpr

  • Tipo: booleano

  • Presenza: opzionale

Se presente e impostato a yes, il software si interfaccia con ANPR.

Chiave pagopa

  • Tipo: booleano

  • Presenza: opzionale

Se presente e impostato a yes, il software si interfaccia con pagoPA.

Sezione riuso

Questa sezione contiene una serie di chiavi legate alla pubblicazione del software sul Catalogo del Riuso.

Chiave riuso/codiceIPA

  • Tipo: stringa (codice iPA)

  • Presenza: obbligatoria se repoOwner è una Pubblica Amministrazione

  • Esempio: c_h501

Questa chiave rappresenta il codice dell’amministrazione all’interno dell’Indice delle Pubbliche Amministrazioni (codice IPA).

Fork e varianti

Come già accennato precedentemente, il fork di un progetto software può essere inteso in modo diverso a seconda dello scopo finale di tale diramazione. Per questioni di chiarezza, qui di seguito distinguiamo le due possibilità: fork tecnici e varianti software.

Fork tecnici (i.e. pubblicare patch)

Un fork tecnico è un fork eseguito da uno sviluppatore con lo scopo di lavorare sulla code base originale o per inviare miglioramenti agli autori del software originale, senza la finalità esplicita di creare e mantenere una variante alternativa del software originale.

Nel contesto di un sistema di controllo distribuito e piattaforme di hosting di codice collaborative quali GitHub, lo strumento del fork è quasi sempre usato dagli sviluppatori come il primo passo per lavorare ad un contributo su una code base già esistente inviando pull request.

Visto il modo in cui il sistema di forking funziona su GitHub ed altre piattaforme simili, gli sviluppatori pubblicano i propri fork sotto forma di copie perfette del software originale, quindi includendo anche il file publiccode.yml originale. I parser devono essere in grado di distinguere questi fork tecnici dalla code base originale.

Parser

I parser DOVREBBERO identificare un fork tecnico notando che la chiave top-level url non punta al repository dove si trova il file publiccode.yml.

I parser POTREBBERO identificare un fork tecnico anche attraverso i metadati che potrebbero essere esposti dalla piattaforma di code hosting (e.g., GitHub contrassegna i fork esplicitamente come fork).

Autori

Gli autori di un fork tecnico NON DOVREBBERO modificare il file publiccode.yml in alcun modo. Più nello specifico, NON DEVONO modificare la chiave top-level url in quanto questa DEVE continuare a puntare al repository originale.

Non c’è una chiave specifica per contrassegnare un fork come tecnico. Questa è una scelta consapevole di design perché non vogliamo che gli autori di un fork tecnico debbano necessariamente essere consapevoli del file publiccode.yml e di come doverlo modificare. Il design corrente non richiede che questi autori facciano alcunché.

Varianti software

Una variante software è un fork che rappresenta una valida alternativa al software originale upstream.

Questa contiene modifiche che non sono ancora parte della versione upstream, come ad esempio più funzionalità, dipendenze diverse, ottimizzazioni, etc.

Contrassegnando un fork come una variante, l’autore indica che questa variante include una serie di modifiche complete e funzionanti che potrebbero giovare ad altre persone.

Contrassegnare un fork come una variante non pregiudica la volontà di contribuire upstream; l’autore potrebbe comunque voler contribuire upstream o essere in attesa di farlo. Perciò, anche se il fork alla fine verrà inclusa (merge) upstream, potrebbe aver senso contrassegnarla come una variante durante queste fasi di lavoro intermedie, in modo tale che anche altri possano trovarla e beneficiarne.

Parser

I parser DOVREBBERO identificare una variante notando che la chiave top-level url è uguale al repository nel quale il file publiccode.yml risiede, E una chiave top-level isBasedOn esiste e punta ad un altro repository.

I parser dovrebbero aspettarsi e analizzare altre differenze nelle due varianti dei file publiccode.yml. In particolare, la chiave description/features è pensata per essere comparata tra diverse varianti in modo da identificare e visualizzare le differenze lato utente.

Autori

Gli autori che vorrebbero pubblicare un fork come una variante DEVONO almeno:

  • Aggiungere una chiave isBasedOn che punti a uno o più repository upstream dai quali questa variante deriva.

  • Cambiare il valore di url per farla puntare al repository che ospita la variante.

  • Cambiare il valore di legal/repoOwner per identificarsi come autori della variante.

  • Rivisitare la sezione denominata maintenance per aggiornare lo stato di manutenzione della variante.

Inoltre, gli autori DOVREBBERO valutare di apportare anche i seguenti cambiamenti:

  • Aggiungere le funzionalità che differenziano le varianti alla chiave description/features. Le funzionalità esistenti NON DOVREBBERO essere modificate o rimosse da questa lista a meno che esse siano state rimosse dalla variante, per permettere ai parser di comparare facilmente la lista delle funzionalità.

Lista delle categorie di software

Qui di seguito è presentato un vocabolario controllato di tag utilizzabili per categorizzare il software.

Tag Validi

  • accounting

  • agile-project-management

  • applicant-tracking

  • application-development

  • appointment-scheduling

  • backup

  • billing-and-invoicing

  • blog

  • budgeting

  • business-intelligence

  • business-process-management

  • cad

  • call-center-management

  • cloud-management

  • collaboration

  • communications

  • compliance-management

  • contact-management

  • content-management

  • crm

  • customer-service-and-support

  • data-analytics

  • data-collection

  • data-visualization

  • digital-asset-management

  • digital-citizenship

  • document-management

  • donor-management

  • e-commerce

  • e-signature

  • email-management

  • email-marketing

  • employee-management

  • enterprise-project-management

  • enterprise-social-networking

  • erp

  • event-management

  • facility-management

  • feedback-and-reviews-management

  • financial-reporting

  • fleet-management

  • fundraising

  • gamification

  • geographic-information-systems

  • grant-management

  • graphic-design

  • help-desk

  • hr

  • ide

  • identity-management

  • instant-messaging

  • inventory-management

  • it-asset-management

  • it-development

  • it-management

  • it-security

  • it-service-management

  • knowledge-management

  • learning-management-system

  • marketing

  • mind-mapping

  • mobile-marketing

  • mobile-payment

  • network-management

  • office

  • online-booking

  • online-community

  • payment-gateway

  • payroll

  • predictive-analysis

  • procurement

  • productivity-suite

  • project-collaboration

  • project-management

  • property-management

  • real-estate-management

  • remote-support

  • resource-management

  • sales-management

  • seo

  • service-desk

  • social-media-management

  • survey

  • talent-management

  • task-management

  • taxes-management

  • test-management

  • time-management

  • time-tracking

  • translation

  • video-conferencing

  • video-editing

  • visitor-management

  • voip

  • warehouse-management

  • web-collaboration

  • web-conferencing

  • website-builder

  • workflow-management

Lista dei campi di applicazione

Qui di seguito è presentato un vocabolario controllato di tag utilizzabili per i campi di applicazione del software.

Tag Validi

  • agriculture

  • culture

  • defence

  • education

  • emergency-services

  • employment

  • energy

  • environment

  • finance-and-economic-development

  • foreign-affairs

  • government

  • healthcare

  • infrastructures

  • justice

  • local-authorities

  • manufacturing

  • research

  • science-and-technology

  • security

  • society

  • sport

  • tourism

  • transportation

  • welfare

Esempi

Qui di seguito vi sono due esempi di file publiccode.yml, il primo rappresenta la configurazione minima, ovvero contiene i campi obbligatori, mentre il secondo è più esteso.

Versione Minima

 1publiccodeYmlVersion: "0.2"
 2
 3name: Medusa
 4url: "https://example.com/italia/medusa.git"
 5softwareVersion: "dev"    # Optional
 6releaseDate: "2017-04-15"
 7platforms:
 8  - web
 9
10categories:
11  - financial-reporting
12
13developmentStatus: development
14
15softwareType: "standalone/desktop"
16
17description:
18  en:
19    localisedName: medusa   # Optional
20    genericName: Text Editor
21    shortDescription: >
22          A rather short description which
23          is probably useless
24
25    longDescription: >
26          Very long description of this software, also split
27          on multiple rows. You should note what the software
28          is and why one should need it. We can potentially
29          have many pages of text here.
30
31    features:
32       - Just one feature
33
34legal:
35  license: AGPL-3.0-or-later
36
37maintenance:
38  type: "community"
39
40  contacts:
41    - name: Francesco Rossi
42
43localisation:
44  localisationReady: yes
45  availableLanguages:
46    - en

Versione Estesa

  1publiccodeYmlVersion: "0.2"
  2
  3name: Medusa
  4applicationSuite: MegaProductivitySuite
  5url: "https://example.com/italia/medusa.git"
  6landingURL: "https://example.com/italia/medusa"
  7isBasedOn: "https://github.com/italia/otello.git"
  8softwareVersion: "1.0"
  9releaseDate: "2017-04-15"
 10logo: img/logo.svg
 11monochromeLogo: img/logo-mono.svg
 12
 13inputTypes:
 14  - text/plain
 15outputTypes:
 16  - text/plain
 17
 18platforms:
 19  - android
 20  - ios
 21
 22categories:
 23  - content-management
 24  - office
 25
 26usedBy:
 27  - Comune di Firenze
 28  - Comune di Roma
 29
 30roadmap: "https://example.com/italia/medusa/roadmap"
 31
 32developmentStatus: development
 33
 34softwareType: "standalone/desktop"
 35
 36intendedAudience:
 37  scope:
 38    - science-and-technology
 39  countries:
 40    - it
 41    - de
 42  unsupportedCountries:
 43    - us
 44
 45description:
 46  en:
 47    localisedName: Medusa
 48    genericName: Text Editor
 49    shortDescription: >
 50          This description can have a maximum 150
 51          characters long. We should not fill the
 52          remaining space with "Lorem Ipsum". End
 53
 54    longDescription: >
 55          Very long description of this software, also split
 56          on multiple rows. You should note what the software
 57          is and why one should need it.
 58
 59    documentation: "https://read.the.documentation/medusa/v1.0"
 60    apiDocumentation: "https://read.the.api.doc/medusa/v1.0"
 61
 62    features:
 63       - Very important feature
 64       - Will run without a problem
 65       - Has zero bugs
 66       - Solves all the problems of the world
 67    screenshots:
 68       - img/sshot1.jpg
 69       - img/sshot2.jpg
 70       - img/sshot3.jpg
 71    videos:
 72       - https://youtube.com/xxxxxxxx
 73    awards:
 74       - 1st Price Software of the year
 75
 76legal:
 77  license: AGPL-3.0-or-later
 78  mainCopyrightOwner: City of Chicago
 79  repoOwner: City of Chicago
 80  authorsFile: AUTHORS
 81
 82maintenance:
 83  type: "contract"
 84
 85  contractors:
 86    - name: "Fornitore Privato SPA"
 87      email: "dario.bianchi@fornitore.it"
 88      website: "https://privatecompany.com"
 89      until: "2019-01-01"
 90
 91  contacts:
 92    - name: Francesco Rossi
 93      email: "francesco.rossi@comune.reggioemilia.it"
 94      affiliation: Comune di Reggio Emilia
 95      phone: +39 231 13215112
 96
 97localisation:
 98  localisationReady: yes
 99  availableLanguages:
100    - en
101    - it
102    - fr
103    - de
104
105dependsOn:
106  open:
107    - name: MySQL
108      versionMin: "1.1"
109      versionMax: "1.3"
110      optional: yes
111    - name: PostgreSQL
112      version: "3.2"
113      optional: yes
114  proprietary:
115    - name: Oracle
116      versionMin: "11.4"
117    - name: IBM SoftLayer
118  hardware:
119    - name: NFC Reader
120      optional: yes
121
122it:
123  countryExtensionVersion: "0.1"
124
125  conforme:
126    lineeGuidaDesign: yes
127    modelloInteroperabilita: yes
128    misureMinimeSicurezza: yes
129    gdpr: yes
130
131  piattaforme:
132    spid: yes
133    cie: yes
134    anpr: yes
135    pagopa: yes
136
137  riuso:
138    codiceIPA: c_h501