docs(standard): add organisationUri

[bfabio]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
publiccode-yml	Ready	Preview	Comment	Sep 29, 2025 6:40am

[bfabio]

See #218.

cc @tomootes @bzg @hidde @jgroenen @bvhme

[bfabio]

@mfortini this can also replace the Italian codiceIpa with something like "urn:x-italian-pa:pcm", wdyt? The custom namespace is kinda unfortunate, but I don't expect agid to register a proper namespace, they'd need to realize how to turn on a computer first.

cc @giorgialodi as well to see if it makes sense.

[bfabio]

@yaml-9000 minor

[yaml-9000]

Thanks for your contribution 🙏

This is now marked as a minor-change proposal to the standard,
this means that old versions of publiccode.yml will still be valid with this change.

Example of minor changes are additions of new keys or making keys optional.

The Chair will eventually pick up this proposal and start the voting procedure using @yaml-9000 vote-start

cc @publiccodeyml/chair @publiccodeyml/steering-committee

_{📄 Voting procedure | 📄 Working Group Charter | 🤖 bot commands}

[tomootes]

Happy this idea is a PR now 😄 @bfabio let me know if there is any input required still

[bfabio]

@tomootes the only thing could be to check the wording and polish it a bit if you feel like it might be improved

Also we should probably deprecate it.riuso.codiceIPA in favor of this key. Pushing an update ASAP.

[libremente]

I guess a bit of rework on the terminology is needed for coherence with the rest of the keys, WDYT @bfabio?

[libremente]

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}

[bfabio]

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.

[libremente]

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 🚀

[bfabio]

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.

[libremente]

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?

[libremente]

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

[libremente]

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

[bfabio]

Minor: it should be organisationUri, with the British spelling, for consistency with the rest of the spec.

[libremente]

Adding just other 2cents here.
As stated above, I think that this change is somehow related to #220, so probably it could be beneficial to discuss the two proposals together in the next round and hopefully merge them at the same time. In this way I believe we won't lose information also in the corner cases depicted above.

[bfabio]

Added clarifications and deprecations following the discussion

[bfabio]

@yaml-9000 vote-start

[yaml-9000]

Voting is now open on this proposal!

If you are a member of the Steering Committee you can now vote!

The polls will stay open for 14 days, until Tue, 14 Oct 2025 07:13:57 GMT.
At the end of that period the Chair (@publiccodeyml/chair) will mark the voting period as over using @yaml-9000 vote-end

Leave a 👍 (thumbs up) on this comment to accept the proposal or a 👎 (thumbs down) to reject it.

cc @publiccodeyml/steering-committee

_{📄 Voting procedure | 📄 Working Group Charter | 🤖 bot commands}

[bfabio]

No votes here yet. Just checking whether it's an oversight or a deliberate abstention.

cc @publiccodeyml/steering-committee @bzg @cknebel @ShimonShore @zorp @dptdgi