Should we refer to publiccode.yml as a "spec" rather than a "standard"?

[bfabio]

It was pointed out to me that publiccode.yml is not an official standard in the formal sense, and that calling it a standard might be slightly misleading.

Thinking about it, I believe this makes sense, specification (or spec) feels more accurate for now, and would still be valid terminology even if the format is eventually adopted or formalized by an official standards body.

What do you think? Would it make sense to revisit the language used in the documentation and messaging?

[jgroenen]

Not sure, there are many "de facto" or "community" standards. I'd say this is one of them.

[bfabio]

To me "Standard" sounds a bit heavy and maybe pompous, especially for something that’s not massively used.

And thinking about it, lots of formats call themselves a "spec" or just "format", in fact: Kubernetes manifests, Cargo.toml, package.json. And they are waaaaaaaay more popular than publiccode.yml.

[bzg]

I believe "spec" would be more accurate indeed.

The goal of the publiccode.yml maintainers can be to turn this spec as a de facto (or "community") standard, but then it's up to others to call it that.

[ericherman]

Personally, I lean in the direction of (pedantically) calling it a "specification" ... however, I also realize that jgroenen's comment reflects common thinking and usage, and thus I don't see it as a big deal.

As it happens, I raised nearly this same topic with the Standard for Public Code. The reasoning given at the time was that the word "standard" is more meaningful than "specification" for a wider range of people and that the Foundation for Public Code is one entity to declare it as their standard in addition to it being the de facto standard of those using it. While I didn't find this exceptionally compelling, I didn't find it overly objectionable either. I feel the same with this case of publiccode.yml.

[jgroenen]

Regarding the "Standard for Public Code", as I am promoting it and discussing it with government architects and developers, I think a better name would have been "Developing Public Code - best practices for developing software in a public setting" or something; Standard implies two things that it is not (which always gives the same discussion): a list of checks no need to pass, and a thing decided upon you have to do.

For publiccode.yml it's a bit different, but the schema itself is a schema (a bit more formal and technical than a spec), so you could say it is the publiccode.yml schema for describing public code repositories (to make them findable, reusable, understandable, etc.)

[jgroenen]

Of course the goal behind the schema is a push on standardization...

[tomootes]

I'd acknowledge that specification is technically more accurate, but a wise man told me once that it might be smart to communicate what kind of product you would like to be in the end.

Currently there are already quote some official catalogues using it (FR/ DE/ IT/EC). Here in The Netherlands i'm proposing it to be part of the list of compulsory standards (https://www.forumstandaardisatie.nl/open-standaarden/verplicht). We're currently filling in al the mandatory forms.

The fact that we're calling it the "publiccode.yml" standard implies that it is a .yml specification. This is a hint in itself.

Like @jgroenen mentioned; standard is also a better word to use when it comes to communiting it to other audiences than developers.