doc(standard): deprecate usedBy

[bfabio]

So, here are the raw points I collected over the years. I can expand on each of them if needed:

• Nothing proves the person opening the PR is who they claim to be, nor that the named PA actually uses the software
• The process is hostile to normal users:
  • a PR is alien to non technical people
  • it requires an account on the hosting platform, typically GitHub but not only
  • the maintainer can be unresponsive and never merge (happens a lot)
  • PRs can be disabled altogether
• When the person who added one leaves the PA, the knowledge leaves with them and nobody will ever remove it.
• The maintainer is a bad gatekeeper and they have a conflict of interest: a longer list means satisfaction and promotion, and they can edit the list themselves if they want.
• Removal is done even less diligently than addition (ie. never done).
• It is free text: no established format for the entity names, no Europe wide registry to normalize them (at best country level ones, all different), so entries cannot be joined or analyzed programmatically.
• I think the right layer is the catalog level, typically managed by each country (or a local entity anyway). They can define their controlled vocabulary of PAs.

As a substitute for the key, I propose: software-catalog-api adds a usedBy field to /v1/software:

• a catalog can authenticate users, possibly recognizing them as PA employees through the national identity and attribute systems, which solves the identity problem
• declaring usage is a checkbox, much easier than a PR that may never be merged
• removing yourself is one click too
• bonus: an inventory of the software each PA uses, something Italy for example asks for periodically

And one last thought experiment supporting it doesn't work: important software should have a publiccode.yml right? Give Firefox one and a truthful usedBy holds tens of thousands of entries. What protects the key today is that nobody fills it exhaustively: a field that has to stay incomplete to look useful.

Fix#61.

[bzg]

Hi Fabio, I probably missed some previous conversation about this: why is usedBy deprecated? This is something we use in https://github.com/codegouvfr/awesome-codegouvfr/ and this is a useful information we want to promote. Is it replaced by something else?

Copying my colleague @hjonin on this.

[bfabio]

Hi @bzg, it's a proposal that has been cooking for a while now because usedBy comes with many pitfalls. I marked it as a draft while I'm writing the rationale and the various thoughts we've had over the years, so we can have a single place with all feedback we gathered.

It's not final of course, there's still the discussion and voting to be had.

While we're at it, I think we can try and vote the proposals for v0.3.1 of the Standard this month (leaving this one out if there's no clear consensus).

[bvhme]

I saw the usedBy also used in the prototype JoinUp catalogue. I like it, but understand there are some pitfalls with a key like this and that it might not completely fit the concept of the standard.

[libremente]

I saw the usedBy also used in the prototype JoinUp catalogue. I like it, but understand there are some pitfalls with a key like this and that it might not completely fit the concept of the standard.

Do you have any idea on how that field is used in that context? Just curiosity

[libremente]

I saw the usedBy also used in the prototype JoinUp catalogue. I like it, but understand there are some pitfalls with a key like this and that it might not completely fit the concept of the standard.

Since the EU catalogue is now live I can see that they are displaying the usedBy entry at the bottom of the page. Unfortunately, as of today, the catalogue's code has not been released anywhere so I have no idea how they implemented this feature but checking a few entries in the catalogue it looks consistent (i.e., if that array is populated then its entries are displayed in the webpage or in a modal window if the list is too long).

[bzg]

FWIW we are still reading usedBy entries from publiccode.yml files when displaying the Awesome code.gouv.fr list.

We could replace it with a new property instances as an optional array of URLs to list public instances.

Do you think instances (or equivalent) would be of interest?

[libremente]

FWIW we are still reading usedBy entries from publiccode.yml files when displaying the Awesome code.gouv.fr list.

We could replace it with a new property instances as an optional array of URLs to list public instances.

Do you think instances (or equivalent) would be of interest?

I think usedBy was a sort of compromise, a simple and static way to get some stats regarding the "reuse" of any given solution.
However, it has too many drawbacks as we discussed many times in the past since it's one of the only parts of the standard that cannot be easily controlled by the repoOwner.
Something like instances could be a nice addition since it is also easier for the repoOwner to check if the URL inserted in a specific PR is valid or not.
However I see other possible pitfalls, like e.g.:

• it kind of moves the focal point from the "who" is using it (in Italy it's an Italian PA) to the "how" (tech implementation). This can definitely be beneficial especially during the tech evaluation of a tool but it's different from the original usedBy key. But then what happens when an administration deploys a software in a private intranet without exposing anything to the outside world? Everything is working, no licenses are breached (hopefully) but no links are available.
• It's kind of linked to a web/backend/library softwareType. I mean, if you think at a standalone/desktop application it is hard to have URL resolving an "instance" of that software.
• It could introduce other issues linked with URLs, specifically on the validation side. What happens if some of the URLs don't resolve anymore for different reasons? The publiccode.yml will still be considered valid or not? What should the publiccode.yml maintainer do since she/he is not directly controlling those deployments?

As such I don't see it as a perfect substitute of usedBy per se, they look complementary to me.

[lsmith77]

I am working on a proposal to use .well-known as a mechanism for declare usage of specific open source projects. This data could then be crawled for a more up to date data source. Obviously there is room for intentional misrepresentation but I see this as the responsibility of the crawler. For example the crawler could decide to trust certain domains (f.e. domains owned by the public sector or based on some allow list).

[lsmith77]

Building on my earlier comment — the staleness problem is a symptom of something deeper: a project doesn't have authority over who uses it. usedBy made more sense in the standard's original scope (Italian PAs sharing software, a bounded universe). I wish for publiccode.yml to expand to the open source community at large, and then maintaining this field becomes impossible by design.

The concrete replacement: deploying organizations publish /.well-known/publiccode-usage.json on their own domain. Domain control is the identity proof; no project PR needed. This also addresses @libremente's objection to instances — the declaration doesn't require a public-facing URL, so it works for private deployments and desktop software alike.

For this PR: the deprecation notice should link to a replacement mechanism rather than just marking the field deprecated, and the validator should warn rather than error so existing files stay valid during transition. I have a working draft of the .well-known spec — fuller context in this proposal — and am happy to share it here or in a companion discussion.

[bfabio]

Added my rationale.

[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 next eligible voting round will take place on September 30, 2026

cc @publiccodeyml/steering-committee

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

[tomootes]

I see it used seldomly in our catalogue (https://oss.developer.overheid.nl). The proposal @bfabio sketches, in which this is managed in the catalogue seems like the way to go to me.

It reminds me of another feature that i have been thinking of which is the listing of open source suppliers who can service/ implement a specific open source product. I think its vital to the open source ecosystem that people seeking to purchase an open source product/ service know who to contact for this. In this case an external listing seems logical as well. @lsmith77

[lsmith77]

I think adding capability into the catalog to consume and display such data is super critical for procurement offices. I would, however, propose a solution in the spirit of how publiccode.yml already works: decentralized with crawlers.

So I would propose a .well-known format with which users can publish this fact (ideally OSS systems publish these by default, ie. Moodle just publishes it when deploying). Conversely, OSS projects could do the same to publish their known vendors that are working with upstream (or provide an API to this like Drupal does with their credits system)

[lsmith77]

here is the relevant part of the proposal:
https://codeberg.org/open-source-ecosystem/publiccode-metadata/src/branch/main/PROPOSAL.md#organization-level-usage-declarations