Skip to content

docs(standard): add organisationUri #229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bfabio merged 3 commits into from
Oct 14, 2025
Merged

docs(standard): add organisationUri #229

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
018e69f
docs(standard): add organizationUri
bfabio Aug 14, 2025
1b3d348
docs(standard): rename organizationUri to organisationUri
bfabio Sep 25, 2025
f5397df
docs(standard): turn into an object, add name, clarify publisher, dep…
bfabio Sep 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions docs/standard/schema.core.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,28 @@ contain the ``url`` of the original project(s).
The existence of this key identifies the fork as a software
variant, descending from the specified repositories.

Key ``organizationUri``
~~~~~~~~~~~~~~~~~~~~~~~

- Type: string
- Presence: optional
- Example: ``"https://example.org/my-organization"``, ``"urn:x-foobar:my-organization"``

The URI identifying the organization owning the software. The value
Copy link
Member

@libremente libremente Aug 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be a bit more specific here on the term owning. I mean, is it the legal/mainCopyrightOwner (IP) or is it the repoOwner (possibly contractor or smt like that)? Maybe it could be nice to add such info directly in the text, something like [...](it should be the same organization mentioned in {mainCopyrightOwner, repoOwner}

Copy link
Contributor Author

@bfabio bfabio Sep 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point!

repoOwner is a recurring subject and it has always interpreted in a different way, depending on who was looking. I think it is not a coincidence it's coming up now.

The spec:

repoOwner
This string describes the entity that owns this repository; this might 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.

The wording is the same as my proposed one for organizationUri.

Why? Because it's the same thing and we didn't realize it.

Here #60 there was a proposal (2019!) to make it mandatory. Why? Because it/riuso/codiceIPA was mandatory (for Italian PAs)

it/riuso/codiceIPA
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).

Meaning that it/riuso/codiceIPA == repoOwner, but with a different way to represent it. What's it/riuso/codiceIPA? repoOwner as controlled vocabulary for Italian PAs. Whereas organizationUri is supposed to be the controlled vocabulary for everyone.

Another hint:
https://yml.publiccode.tools/forks.html?highlight=repoowner#authors-1

Authors that are willing to publish a fork as a variant MUST at least:
Change the value for legal/repoOwner to refer to the themselves (the authors of the variant).

repoOwner is a (much) worse codiceIPA which in turn is a worse organizationUri, and they all refer to the publisher of the solution.

So:

  • Deprecate repoOwner
  • Deprecate codiceIPA
  • Clarify that organizationUri is the publisher and define "publisher" (btw another hint: https://api.developers.italia.it/v1/publishers in the API. First of all they already exist as a concept in the system, and that's something, but they also MUST match codiceIPA)

This wraps it all up perfectly IMO.

Copy link
Member

@libremente libremente Sep 5, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @bfabio!
I still have some doubts though (and I know we have been discussing this for such a long time!).
Few points below:

  • codiceIPA is kind of the only way to identify (uniquely) an Italian PA. It's the only "controlled" key we have which does not change over time and we can somehow backtest against a public DB (AgID's website). So IIUC you are proposing to remove the alphanumeric code itself and use a "stable, resolvable" URI. What should that be? This entry called Sito Istituzionale in the IPA website? Is that populated for everyone? We know that many PAs don't update IPA regularly, some of them don't even know how to do it! Is this the safest option? OR should that URI be this URL itself? Very scary since we know that it might be changed any day soon without any previous notice from AgID. In a fantastic world we could have some sort of persistent identifiers (w3id style) but AFAIK we are far from it.

  • Overall, I think the main misunderstanding comes from the way the Italian LLGG of Acquisition and Reuse of Software for PA are written/interpreted and in the way the codiceIPA is used in the Italian Catalogue. In fact, in the perfect world designed by the LLGG, repoOwner/mainCopyrightHolder/codiceIPA are the same, so no problem exists. However, in reality, things change a lot: we have many cases where the developer keeps the control over the repository, so that's where mainCopyrightHolder != repoOwner. Now, the question becomes: what should we do with codiceIPA in such cases? In the Italian Catalogue, that's rendered as "Pubblicato da" so yeah, you are right, we are interpreting that key as the publisher so deprecating it in favor of organizationUri may make sense. However, is that really what we want to express with that key? Shouldn't it be "the PA that is making that software available for reuse"? In such cases, the codiceIPA should NOT be the same as repoOwner but of mainCopyrightHolder. Or not, in case it's a fork...

So yes, as of today this triplet is very ambiguous and IMHO it does NOT cover all the cases as mentioned above.
Deprecating everything in favor of a single key? It could work, but is it what we want?

Let's try to make a simulation here:

SW X developed by A (mainCopyrightHolder).
Public Administration B decides to spend some money on it in order to customize it.
B, in order to do so, uses its provider C.
C forks X on its own GH org.

Current standard:
* mainCopyrightHolder: A
* repoOwner: C
* codiceIPA (if C is a PA): C

^^^^ The information on B, which at the end is the entity paying (if I think of the term "sponsoring" I can think of the issue opened by @bzg) and `putting that software in reuse` is lost. 

Proposed version:
* mainCopyrightHolder: A
* organizationUri: C

^^^^ Again, we are in the same situation, we are losing info on B.

Thinking aloud on this example, I think we are losing the most important information! 😃
IMHO B is the key player: the one that follows the laws, does the evaluation and decides to REUSE and not MAKE from scratch, uses public money to pay C to produce public code and at the end is not even represented! I know that in the perfect world depicted by the LLGG at the end the software should be transferred on a org directly controlled by B (so in that case B appears in the publiccode.yml) but in real life that does not happen all the time for several different reasons so I think that the Standard should reflect also this possibility.
Maybe the new triplet mainCopyrightHolder/organizationUri/sponsoredBy could be the winning one? Still not sure, since sponsors come and go so IMHO sponsoredBy should be an array and not a single entry in order to have a list of all the history of sponsors (but that's another issue).

Sorry for the extremely long stream of consciousness, please debunk it so I can definitely convince myself that this is the way to go 🚀

Copy link
Contributor Author

@bfabio bfabio Sep 5, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

codiceIPA is kind of the only way to identify (uniquely) an Italian PA. It's the only "controlled" key we have which does not change over time and we can somehow backtest against a public DB (AgID's website). So IIUC you are proposing to remove the alphanumeric code itself and use a "stable, resolvable" URI. What should that be?

We'd use an URNified IPA code, matching 1-1 the actual codiceIPA, but with a generalized format, see #229 (comment)

However, in reality, things change a lot: we have many cases where the developer keeps the control over the repository, so that's where mainCopyrightHolder != repoOwner

In those case the developer is a contracting publicly controlled company. Still a public administration entity with its own public administration identifier. In case it's a private contractor, keeping it on "their" repo is a big no-no and we want to avoid that. They are supposed to move/push the code to the PA's code hosting.

repoOwner publisher != mainCopyrightHolder yes, because...:

Now, the question becomes: what should we do with codiceIPA in such cases? [...] Shouldn't it be "the PA that is making that software available for reuse"?

...the publisher is making the software available, in the practical sense, by publishing their repo (and implicitly, by owning it - the repo).
And "legally wise" it's the mainCopyrightHolder making it available for reuse, so they are separate.

* repoOwner: C
* codiceIPA (if C is a PA): C

See how even in the example C == C? It comes naturally :)

[..]
The information on B, which at the end is the entity paying (if I think of the term "sponsoring" I can think of the issue opened by @bzg) and putting that software in reuse is lost.

Since B is writing the check, they can and should tell C to push the code to B's repo (while in case of private contractors, they should definitely demand it). If they don't, C will take the credit in publiccode.yml, that's right, but it's not like B disappears from other information sources.

If B fails to be credited, that's on B if you ask me. They have the tools, they have the leverage. They failed to do the most basic thing, and failures have do consequences. And in the end, tough, the code is reused anyway.

Copy link
Member

@libremente libremente Sep 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok for the URN-ipa, makes sense 👍

They are supposed to move/push the code to the PA's code hosting.
[...] If B fails to be credited, that's on B if you ask me.

I totally understand your point of view but I still think that the public entity spending public money for the creation/development of public code should always be represented in the publiccode.yml, so I guess it is also our role to help this process.

Anyway, I would like someone else to jump in and provide other ideas, I have the feeling that we are a bit too biased on the Italian ecosystem. How does it work in other MS for example? Is it that common to have public code repos hosted inside the walled gardens managed by private companies? Or is all the development managed in the open inside public sector owned repos?

Copy link
Member

@libremente libremente Sep 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since noone showed up I guess you can mark this as ready for discussion in the next voting round and see how it goes @bfabio

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 `organizationUri` actually
corresponds to the organization in control of the repository.
Copy link
Member

@libremente libremente Aug 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, so you are referring to the control of the repo (repoOwner) and not of the software, right?

The specific verification method depends on the implementation and policies of the
platform consuming the file.

The key can be omitted if no such URI is available.

Key ``softwareVersion``
~~~~~~~~~~~~~~~~~~~~~~~

Expand Down