From a63eb236c123790547787fd042c0c2940c1a4797 Mon Sep 17 00:00:00 2001 From: Fabio Bonelli Date: Wed, 5 Nov 2025 14:18:43 +0100 Subject: [PATCH 1/2] docs: improve wording for country-specific sections Improve wording in the main standard and in the Italian translation. Fix #259. --- docs/it/country.rst | 36 +++++++++--------------------------- docs/standard/country.rst | 29 +++++++---------------------- 2 files changed, 16 insertions(+), 49 deletions(-) diff --git a/docs/it/country.rst b/docs/it/country.rst index baa6a2be..fcc83d3f 100644 --- a/docs/it/country.rst +++ b/docs/it/country.rst @@ -1,34 +1,16 @@ .. _`estensioni-paese`: -Estensioni nazionali -==================== +Sezioni specifiche per Paese +============================ -Mentre lo standard è 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*). +Le sezioni specifiche per paese permettono di includere informazioni rilevanti +solo per un determinato Paese, come la conformità a regolamenti nazionali o +l'integrazione con piattaforme nazionali. -Tutte le sezioni specifiche per ogni Paese sono contenute in una sezione -denominata con l’\ `ISO 3166-1 alpha-2 country -code `__ in minuscolo (*deprecato*) o -in maiuscolo. -Ad esempio, ``spid`` è una proprietà definita per i software italiani per la -dichiarazione dell’eventuale compatibilità con il Sistema Pubblico di -Identità Digitale. +Ogni sezione è identificata con l'\ `ISO 3166-1 alpha-2 country code +`__ del Paese in minuscolo +(*deprecato*) o in maiuscolo. -Dunque, se un software è compatibile, troveremo: - -.. code:: yaml - - 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. +Attualmente, l'unica sezione specifica per Paese definita è quella italiana (it:). .. include:: schema.it.rst diff --git a/docs/standard/country.rst b/docs/standard/country.rst index 77ab000d..aab2e450 100644 --- a/docs/standard/country.rst +++ b/docs/standard/country.rst @@ -1,31 +1,16 @@ .. _`country-section`: -Country-Specific Sections +Country-specific sections ========================= -While the standard is structured to be meaningful on an international -level, there are additional information that can be added that makes -sense in specific countries, such as declaring compliance with local -laws or regulations. The provided extension mechanism is the usage of -country-specific sections. +Country-specific sections allow including information relevant only within a +given country, such as compliance with national regulations or integration with +national platforms. -All country-specific sections live under a key named after two-letter +Each section is identified by a two-letter ISO 3166-1 alpha-2 country code lowercase (*deprecated*) or uppercase `ISO 3166-1 alpha-2 country -codes `__. For instance -``spid`` is a property for Italian software declaring whether the -software is integrated with the Italian Public Identification System. +codes `__. -If a software is compliant I will find: - -.. code:: yaml - - it: - countryExtensionVersion: "1.0" - piattaforme: - - spid: true - -Notice that country-specific keys within international sections -are not allowed. Countries that want to extend the format should add a -country-specific section instead. +Currently, the only defined country-specific section is the Italian one (``it:``). .. include:: schema.it.rst From 5146e685afae1e2c8412c86368436d058b0e9748 Mon Sep 17 00:00:00 2001 From: Fabio Bonelli Date: Wed, 5 Nov 2025 14:24:28 +0100 Subject: [PATCH 2/2] docs: remove redundant sentence --- docs/fr/schema.it.rst | 5 +---- docs/it/schema.it.rst | 4 +--- docs/standard/schema.it.rst | 4 +--- 3 files changed, 3 insertions(+), 10 deletions(-) diff --git a/docs/fr/schema.it.rst b/docs/fr/schema.it.rst index cb189712..cb93ea4b 100644 --- a/docs/fr/schema.it.rst +++ b/docs/fr/schema.it.rst @@ -4,10 +4,7 @@ Italy ----- All the extensions listed below are specific for Italy and, as such, they must -be inserted in a section named with the ``it`` code. Every Country is specified -using a two letters lowercase (*deprecated*) or uppercase *country code* following -the ISO 3166-1 alpha-2 standard. - +be inserted in a section named with the ``it`` code. Key ``countryExtensionVersion`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/it/schema.it.rst b/docs/it/schema.it.rst index e7ccb7df..33c12ae1 100644 --- a/docs/it/schema.it.rst +++ b/docs/it/schema.it.rst @@ -5,9 +5,7 @@ Italia Tutte le chiavi 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 -in minuscolo (*deprecato*) o in maiuscolo, seguendo lo standard ISO 3166-1 alpha-2. - +``it``. Chiave ``countryExtensionVersion`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/standard/schema.it.rst b/docs/standard/schema.it.rst index 339e35b6..38f006fe 100644 --- a/docs/standard/schema.it.rst +++ b/docs/standard/schema.it.rst @@ -4,9 +4,7 @@ Italy ----- All the keys listed below are specific for Italy and, as such, they must -be inserted in a section named with the ``it`` code. Every Country is specified -using a two letters lowercase (*deprecated*) or uppercase *country code* following -the ISO 3166-1 alpha-2 standard. +be inserted in a section named with the ``it`` code. Key ``countryExtensionVersion``