docs(standard): add organisation key (#229)

Author: bfabio

docs/standard/schema.core.rst

@@ -288,6 +288,45 @@ The keys are:
    configuration files, bash scripts, ansible playbooks, Dockerfiles, or
    other instruction sets.
 
+Section ``organisation``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This optional section provides the organisation publishing the software.
+
+Key ``organisation/uri``
+'''''''''''''''''''''''
+
+-  Type: string
+-  Presence: mandatory
+-  Example: ``"https://example.org/my-organisation"``, ``"urn:x-foobar:my-organisation"``
+
+The URI identifying the organisation publishing the software. The value
+SHOULD be a stable, resolvable URI or a persistent identifier.
+
+Parsers MAY use the URI structure to extract additional information if it follows a
+recognized format (for example, inferring an institutional domain or an
+official code).
+
+It is RECOMMENDED that crawlers and consumers of publiccode.yml verify this
+information out-of-band, to ensure that the declared `organisationUri` actually
+corresponds to the organisation in control of the repository.
+The specific verification method depends on the implementation and policies of the
+platform consuming the file.
+
+Key ``organisation/name``
+'''''''''''''''''''''''
+
+-  Type: string
+-  Presence: optional
+-  Example: ``"My organisation"``
+
+The canonical name of the organisation publishing the software.
+
+It MUST correspond to the same entity identified by ``organisation/uri`` and is
+intended to provide a human-readable label for that URI.
+It SHOULD be the canonical, widely recognized form of the name (such as the
+registered legal or institutional name).
+
 Section ``intendedAudience``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -560,8 +599,8 @@ 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``.
 
-Key ``legal/repoOwner``
-'''''''''''''''''''''''
+Key ``legal/repoOwner`` (*deprecated*)
+''''''''''''''''''''''''''''''''''''''
 
 -  Type: string
 -  Presence: optional
@@ -572,6 +611,8 @@ 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``.
 
+This key is deprecated, use ``organisation/name`` instead.
+
 Key ``legal/authorsFile`` (*deprecated*)
 ''''''''''''''''''''''''''''''''''''''''
 

docs/standard/schema.it.rst

@@ -125,12 +125,14 @@ Section ``riuso``
 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>`__.
 
-Chiave ``riuso/codiceIPA``
-''''''''''''''''''''''''''
+Chiave ``riuso/codiceIPA`` (*deprecated*)
+'''''''''''''''''''''''''''''''''''''''''
 
 -  Type: string (iPA code) 
 -  Presence: mandatory if ``repoOwner`` is a Public Administration 
 -  Example: ``c_h501``
 
 This key represents the administration code inside the Public Administration
 index (codice IPA).
+
+This key is deprecated, use ``organisation/uri`` instead.