Provide YAML/JSON schema file

[rklec]

Being new to this standard it would be very helpful if you could provide a YAML schema file.

Problem

I used https://editor.opencode.de but apparently that is outdated as it only generates a publiccodeYmlVersion: '0.2'.
There is v0.5.0 here already though?

Proposed solution

Could you provide a YAML/JSON schema file, so that in compatible IDEs it can be used directly?

And link it here form the Readme?

[rklec]

Whole writing this, found out that at least JetBrains IDEs already use https://www.schemastore.org/publiccode.json from https://www.schemastore.org - this is linked/documented nowhere though, as far as see?

Is this the official schema and if so, is it up-to-date? I guess maintaining it in this repo would make much more sense?

[tomootes]

hi @rklec i've got the same interest.

I found this repository a while ago an filed an issue: teamdigitale/publiccode-json-schema#1 (comment). In the answer that @Lorezz put he states that Developer Italia is working on a JSON Schema so that's good news.

In the meanwhile i would like to point you to the editor that we build at developer.overheid.nl: https://developer-overheid-nl.github.io/publiccode-checker/#/pc

If you paste an URL to a .yml in the topbar in converts the YAML it to JSON instantly and you can check the integrity of your publiccode.yml.

[bfabio]

Hey @rklec, the opencode.de editor is indeed outdated, it should ideally be updated by its authors.

The defacto official JSON Schema is the one published on schemastore (publiccode.json), which is why JetBrains and VS code already pick it up automatically. Keeping it in sync is already part of the release checklist. When we cut a new version of the spec, the JSON Schema gets updated accordingly: see #256 for an example.

Of course it can always be improved by contributing to the schemastore's repo.

On our side, we could mention it in the README, maybe in a new "Tooling" section, where we could list the "officially maintained" tools (in a loose sense, i.e. tools that are actively kept in sync with the spec and part of the release process)

WDYT?

[Lorezz]

as @bfabio said, the official schema is on schema.org, the purpose of the repo https://github.com/teamdigitale/publiccode-json-schema is to maintain the schema and produce the next releases, which will be driven by changes in the publicode standard, as well as giving the possibility to other countries to extend the language configurable part for their own needs.

Another feature that we are working on is the ability to generate the editor form, and some validations with an augmented json associated to the schema's props.

[rklec]

When we cut a new version of the spec, the JSON Schema gets updated accordingly: see #256 for an example.

If possible I'd suggest automating this, and if it is just creating a (draft) PR in some third-party repo (that just uploads the changed JSON etc.). 😉 (Of course that's only possible if it exists in some repo updated already, which seems to be the case though...)

the purpose of the repo https://github.com/teamdigitale/publiccode-json-schema is to maintain the schema and produce the next releases

Okay, but why is the repo not in the https://github.com/publiccodeyml namespace/org to mark it as "official"? Currently, this could be/looks like some third-party contribution?
(And as said above, a CI/CD for releasing it would sound good.)

Of course it can always be improved by contributing to the schemastore's repo.

...which stands to question now given the other repo. Contributors also need to know, where to contribute. It sounds as if https://github.com/teamdigitale/publiccode-json-schema would be the better place/single source of truth here. (I'd suggest to try to improve/keep clarity of what resides in which repo, as #276 highlights/demonstrates.) A CONTRIBUTION.md could e.g. clarify this, too.

On our side, we could mention it in the README, maybe in a new "Tooling" section, where we could list the "officially maintained" tools (in a loose sense, i.e. tools that are actively kept in sync with the spec and part of the release process)

Please absolutely do so! The point of me creating this issue also was the discrepancy between "my IDE uses this schema" and "this repo has (apparently) no official schema", so questions like "Is this official" even arise? A schema is only good if people can trust that the recommendations it does, are official. Only in this way I have noticed this issue, e.g..

It's of course your decision whether you want to maintain that schema in this repo, a separate repo or a third-party repo (schemastore) and how to potentially sync it between them. Without knowing details I, personally, would have a slight bias towards the first option, just for simplicity and allowing one to provide PRs/commits that directly update all files including the JSON schema.

[Lorezz]

Thanks for your suggestions @rklec , they will definitely be taken into consideration. As for the new repository, we're still in the early stages; we'll be adding information about how to contribute and the tool's goals.

[bfabio]

as @bfabio said, the official schema is on schema.org,

I think you mean schemastore.org, schema.org is a completely different thing.

the purpose of the repo https://github.com/teamdigitale/publiccode-json-schema is to maintain the schema and produce the next releases

That repo is new to me. What do you mean by "next releases"? Definitely not publiccode.yml spec releases.

which will be driven by changes in the publicode standard,

I opened that repo and was genuinely surprised to see a non-spec version (0.5.1! The list of actual releases is here) plus extra keys and even a key named "itegrations".

That's a big no-no if the intent is to collaborate constructively with the standard.

But then again, there's no need for another JSON schema, as the schema is already on schemastore.org.

as well as giving the possibility to other countries to extend the language configurable part for their own needs.

With "extend the language", do you mean extending the spec/standard itself? Because there is no extension mechanism in the spec

Another feature that we are working on is the ability to generate the editor form, and some validations with an augmented json associated to the schema's props.

What do you mean with "augmented json associated to the schema's props"?

Community contributions in repos outside the project are welcome, of course, but I'm genuinely confused by this whole message: can you explain what's the workflow of your repo?

[jgroenen]

Of course there can be downstream "experiments" to try out things and push them back as suggestions, but I'd be careful not to decentralize the efforts and discussions on the standard.

[tomootes]

Hey @rklec, the opencode.de editor is indeed outdated, it should ideally be updated by its authors.

The defacto official JSON Schema is the one published on schemastore (publiccode.json), which is why JetBrains and VS code already pick it up automatically. Keeping it in sync is already part of the release checklist. When we cut a new version of the spec, the JSON Schema gets updated accordingly: see #256 for an example.

Of course it can always be improved by contributing to the schemastore's repo.

On our side, we could mention it in the README, maybe in a new "Tooling" section, where we could list the "officially maintained" tools (in a loose sense, i.e. tools that are actively kept in sync with the spec and part of the release process)

WDYT?

I wasn't aware that the JSON Schema at schemastore is part of the checklist. I'm happy to hear that 👍 I'll keep linking to it as the official JSON Schema release for publiccode.yml.

I'm also fond of the idea to mention this in a tools section in the readme.md. It's good to keep track of the ecosystem, and to point users to tools that are actually maintained.

I would also like to propose to add a section with tools to the docs website: https://yml.publiccode.tools/, pointing to the JSON Schema. I use the website quite often myself.

[tomootes]

as @bfabio said, the official schema is on schema.org, the purpose of the repo https://github.com/teamdigitale/publiccode-json-schema is to maintain the schema and produce the next releases, which will be driven by changes in the publicode standard, as well as giving the possibility to other countries to extend the language configurable part for their own needs.

Another feature that we are working on is the ability to generate the editor form, and some validations with an augmented json associated to the schema's props.

Great to hear this! I'm very fond of the refactor which is bases on the JSON Schema + some validations. I suppose it makes it a lot more maintainable.

[tomootes]

as @bfabio said, the official schema is on schema.org,

I think you mean schemastore.org, schema.org is a completely different thing.

the purpose of the repo https://github.com/teamdigitale/publiccode-json-schema is to maintain the schema and produce the next releases

That repo is new to me. What do you mean by "next releases"? Definitely not publiccode.yml spec releases.

which will be driven by changes in the publicode standard,

I opened that repo and was genuinely surprised to see a non-spec version (0.5.1! The list of actual releases is here) plus extra keys and even a key named "itegrations".

That's a big no-no if the intent is to collaborate constructively with the standard.

But then again, there's no need for another JSON schema, as the schema is already on schemastore.org.

as well as giving the possibility to other countries to extend the language configurable part for their own needs.

With "extend the language", do you mean extending the spec/standard itself? Because there is no extension mechanism in the spec

Another feature that we are working on is the ability to generate the editor form, and some validations with an augmented json associated to the schema's props.

What do you mean with "augmented json associated to the schema's props"?

Community contributions in repos outside the project are welcome, of course, but I'm genuinely confused by this whole message: can you explain what's the workflow of your repo?

@Lorezz it seems you this repo: teamdigitale/publiccode-json-schema to provide a way to automatically create a JSON Schema? If so, i think this should be a shared effort with @bfabio. And if we build a script like that, it should be part of this repository, or at least in this Github namespace.