Merge pull request #318 from publiccodeyml/supports

Add `supports` and deprecate the country specific sections

Author: bfabio

docs/standard/aliases-list.rst

@@ -0,0 +1,22 @@
+.. _aliases-list:
+
+List of aliases
+===============
+
+Here follows the list of aliases that can be used in the
+``supports`` key. Each alias resolves to the canonical resource it
+refers to.
+
+========  ===============================================
+alias     resource
+========  ===============================================
+gdpr      https://eur-lex.europa.eu/eli/reg/2016/679/oj
+eidas     https://eur-lex.europa.eu/eli/reg/2014/910/oj
+nis2      https://eur-lex.europa.eu/eli/dir/2022/2555/oj
+cra       https://eur-lex.europa.eu/eli/reg/2024/2847/oj
+spid      https://www.spid.gov.it/
+cie       https://www.cartaidentita.interno.gov.it/
+anpr      https://www.anpr.interno.it/
+pagopa    https://www.pagopa.gov.it/
+io        https://io.italia.it/
+========  ===============================================

docs/standard/country.rst

@@ -1,7 +1,13 @@
 .. _`country-section`:
 
-Country-specific sections
-=========================
+Country-specific sections (*deprecated*)
+========================================
+
+Country-specific sections are deprecated and will be removed in
+publiccode.yml 1.0. The use cases they covered are now expressed with
+generic keys: declare compliance with national regulations or
+integration with national platforms through the ``supports`` key, and
+reference the publishing administration through the ``organisation`` key.
 
 Country-specific sections allow including information relevant only within a
 given country, such as compliance with national regulations or integration with

docs/standard/index.rst

@@ -49,4 +49,5 @@ Table of contents
    forks.rst
    categories-list.rst
    scope-list.rst
+   aliases-list.rst
    example.rst

docs/standard/schema.core.rst

@@ -295,6 +295,36 @@ The keys are:
    configuration files, bash scripts, ansible playbooks, Dockerfiles, or
    other instruction sets.
 
+Key ``supports``
+~~~~~~~~~~~~~~~~
+
+-  Type: array of objects
+-  Presence: optional
+
+A list of standards, regulations, frameworks or systems that the
+software supports or complies with.
+
+Each item is an object with a single property:
+
+-  ``id`` - **mandatory** - an identifier for the supported standard,
+   regulation, framework or system. It is either an alias in
+   the form ``alias:<name>`` (e.g. ``alias:gdpr``), resolved through the
+   :ref:`list of aliases <aliases-list>`, or any other valid URI (URL or
+   URN) referencing the resource directly.
+
+   An ``alias:`` value MUST exist in the
+   :ref:`list of aliases <aliases-list>`. An unknown alias is an error.
+   Any other value MUST be a syntactically valid URI. A value that is
+   well formed but not otherwise known is accepted as is.
+
+Example:
+
+.. code:: yaml
+
+   supports:
+     - id: alias:gdpr
+     - id: https://eur-lex.europa.eu/eli/reg/2016/679/oj
+
 Section ``organisation``
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/standard/schema.it.rst

@@ -1,14 +1,20 @@
 .. _italian-sections:
 
-Italy
------
+Italy (*deprecated*)
+--------------------
+
+The entire Italian country-specific section is deprecated and will be
+removed in publiccode.yml 1.0. Use the generic ``supports`` key for
+compliance with national regulations and integration with national
+platforms, and the ``organisation`` key to reference the publishing
+administration.
 
 All the keys listed below are specific for Italy and, as such, they must
 be inserted in a section named with the ``IT`` code.
 
 
-Key ``countryExtensionVersion``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Key ``countryExtensionVersion`` (*deprecated*)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Type: string
 - Presence: mandatory
@@ -17,6 +23,8 @@ Key ``countryExtensionVersion``
 
 This key **MUST** always be set to ``1.0``.
 
+This key is deprecated together with the rest of the Italian section.
+
 Key ``conforme`` (*deprecated*)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -72,12 +80,14 @@ Key ``conforme/gdpr`` (*deprecated*)
 
 If present and set to ``true``, the software respects the GDPR.
 
+Use the ``supports`` key with ``alias:gdpr`` instead.
 
-Section ``piattaforme``
-~~~~~~~~~~~~~~~~~~~~~~~
 
-Key ``piattaforme/spid``
-''''''''''''''''''''''''
+Section ``piattaforme`` (*deprecated*)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Key ``piattaforme/spid`` (*deprecated*)
+'''''''''''''''''''''''''''''''''''''''
 
 - Type: boolean
 - Presence: optional
@@ -87,42 +97,52 @@ If present and set to ``true``, the software interfaces with `SPID
 - il Sistema Pubblico di Identità
 Digitale <https://developers.italia.it/it/spid>`__.
 
-Key ``piattaforme/cie``
-'''''''''''''''''''''''
+Use the ``supports`` key with ``alias:spid`` instead.
+
+Key ``piattaforme/cie`` (*deprecated*)
+''''''''''''''''''''''''''''''''''''''
 
 - Type: boolean
 - Presence: optional
 
 If present and set to ``true``, the software interfaces with the Italian
 electronic ID card (``Carta di Identità Elettronica``).
 
-Key ``piattaforme/anpr``
-''''''''''''''''''''''''
+Use the ``supports`` key with ``alias:cie`` instead.
+
+Key ``piattaforme/anpr`` (*deprecated*)
+'''''''''''''''''''''''''''''''''''''''
 
 - Type: boolean
 - Presence: optional
 
 If present and set to ``true``, the software interfaces with ANPR.
 
-Key ``piattafome/pagopa``
-'''''''''''''''''''''''''
+Use the ``supports`` key with ``alias:anpr`` instead.
+
+Key ``piattafome/pagopa`` (*deprecated*)
+''''''''''''''''''''''''''''''''''''''''
 
 - Type: boolean
 - Presence: optional
 
 If present and set to ``true``, the software interfaces with pagoPA.
 
-Key ``piattaforme/io``
-'''''''''''''''''''''''''
+Use the ``supports`` key with ``alias:pagopa`` instead.
+
+Key ``piattaforme/io`` (*deprecated*)
+'''''''''''''''''''''''''''''''''''''
 
 - Type: boolean
 - Presence: optional
 
 If present and set to ``true``, the software interfaces with `IO - the public services app <https://io.italia.it/>`__.
 
+Use the ``supports`` key with ``alias:io`` instead.
+
 
-Section ``riuso``
-~~~~~~~~~~~~~~~~~
+Section ``riuso`` (*deprecated*)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This section contains a set of keys related to the publication of the software
 inside the reuse catalog of `Developers Italia <https://developers.italia.it>`__.