doc: JSON schema for cockpit manifest.json

[Venefilyn]

Our manifest.json is currently only documented through our docs, and
in there it can be quite confusing. We tend to instead copy from other
repos or pages and I assume other projects do too. But modifying it can
be tedious.

Setting this JSON schema as a $schema property in your manifest.json
file will make all properties validated against.

I feel like having it in this repo is better than the website repo given it is
code-related.

We might also want to version the schema file and add an optional
version property in the schema itself. That way we can even have
(automated) scripts to migrate future changes to the manifest.json

Assisted-by: ramalama+olmo2:7b-1124-instruct-q8_0
Signed-off-by: Freya Gustavsson [email protected]

[Venefilyn]

Then we can have it on the website as a recommendation:

{
    "$schema": "https://cockpit-project.org/doc/guide/static/manifest.schema.json"
    ...
}

And to test locally before it's published:

cockpit/pkg/networkmanager/manifest.json

{
    "$schema": "../../doc/guide/static/manifest.schema.json",
    "name": "network",
    "conditions": [
        {"path-exists": "/usr/share/dbus-1/system.d/org.freedesktop.NetworkManager.conf"}
    ],
    "menu": {
        "index": {
            "label": "Networking",
            "order": 40,
            "docs": [
                {
                    "label": "Managing networking bonds",
                    "url": "https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_and_managing_networking/configuring-network-bonding_configuring-and-managing-networking#proc_configuring-a-network-bond-by-using-the-rhel-web-console_configuring-network-bonding"
                },
                {
                    "label": "Managing networking teams",
                    "url": "https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_and_managing_networking/configuring-network-teaming_configuring-and-managing-networking#proc_configuring-a-network-team-by-using-the-rhel-web-console_configuring-network-teaming"
                },
                {
                    "label": "Managing networking bridges",
                    "url": "https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_and_managing_networking/configuring-a-network-bridge_configuring-and-managing-networking#proc_configuring-a-network-bridge-by-using-the-rhel-web-console_configuring-a-network-bridge"
                },
                {
                    "label": "Managing VLANs",
                    "url": "https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_and_managing_networking/configuring-vlan-tagging_configuring-and-managing-networking#proc_configuring-vlan-tagging-by-using-the-rhel-web-console_configuring-vlan-tagging"
                },
                {
                    "label": "Managing firewall",
                    "url": "https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_firewalls_and_packet_filters/using-and-configuring-firewalld_firewall-packet-filters#enabling-services-on-firewall-using-the-web-console_controlling-network-traffic-using-firewalld"
                }
            ],
            "keywords": [
                {
                    "matches": ["network", "interface", "bridge", "vlan", "bond", "team", "port", "mac", "ipv4", "ipv6"]
                },
                {
                    "matches": ["firewall", "firewalld", "zone", "tcp", "udp"],
                    "goto": "/network/firewall"
                }
            ]
        }
    }
}

[mvollmer]

"tools" and "dashboard" should be the same as "menu", i.e."#/$defs/menu-type".

[Venefilyn]

Ack thanks! Lots of lines so explains why I missed a few things

[mvollmer]

This seems to still be draft, right?

[mvollmer]

@Venefilyn, in case you haven't already, please have a look at pkg/shell/manifests.ts, which validates those parts of the manifests that are of interest to the Shell. (I.e., not the "bridges" and "conditions" fields, for example.)

[mvollmer]

I like this! We should validate our own manifests according to this schema in test/common/static-code.

[Venefilyn]

This seems to still be draft, right?

Depends. What do we want to accomplish with this? For now I would say we stick to just recommending this schema and over time move our manifest validation script over to use the schema. But need tests for that which I'm not sure we have

@Venefilyn, in case you haven't already, please have a look at pkg/shell/manifests.ts, which validates those parts of the manifests that are of interest to the Shell. (I.e., not the "bridges" and "conditions" fields, for example.)

Ack. Anything missing at the moment that you can think of?

I like this! We should validate our own manifests according to this schema in test/common/static-code.

Shouldn't be too difficult. There is a python package for this that we could use https://github.com/python-jsonschema/jsonschema

Since I assume we don't have limitations on what test dependencies we have this would be fine to use right?

[allisonkarlitskaya]

I know this sounds ridiculous but could we write this file in yaml? It would be a lot easier to read...

Otherwise: before we commit to this I think I want a firmer idea of where the schema will live. In particular:

• we need to run our linters and stuff offline, which implies that the schema needs to live in the cockpit repo in a place where the subprojects can also hit it
• you seemed to suggest that we'll replace the relative path with a URL during publishing but we don't perform any transformations on our manifest.json files anymore (which was a hard-fought victory). Will the symlink be broken when the file is installed? Will we install the schema on the system?
• will the bridge break if it notices this field and doesn't recognize it? I guess/hope not?

[Venefilyn]

I know this sounds ridiculous but could we write this file in yaml? It would be a lot easier to read...

There aren't really yaml schema validation AFAIK.

Otherwise: before we commit to this I think I want a firmer idea of where the schema will live. In particular:

* we need to run our linters and stuff offline, which implies that the schema needs to live in the cockpit repo in a place where the subprojects can also hit it

* you seemed to suggest that we'll replace the relative path with a URL during publishing but we don't perform any transformations on our manifest.json files anymore (which was a hard-fought victory).  Will the symlink be broken when the file is installed?  Will we install the schema on the system?

* will the bridge break if it notices this field and doesn't recognize it?  I guess/hope not?

This wouldn't really change the existing syntax whatsoever though. But I also hope that we don't break cockpit if it detects a top level property "$schema" on a manifest.json.

• Schema validation is supposed to be done either live as you're editing (as it can also give descriptions when you're editing) or through a tool that reads the schema and validates against it
• One change is suggested to manifest.json in which other applications should be allowed to have a $schema top level property
• If validation fails, it wouldn't cause any issues currently. But if we change our validation script to use the schema then I suppose yes it would. But having tests to cover the current manifest validation implementation then migrating the validation to use the schema should not cause any tests to fail. It should not cause any breaking changes.

But yeah I don't suggest we throw out our validation we have now for this, but rather recommend to use this schema for your manifest.json to have it much easier to know if something is broken or not and what fields exist to use.

[Venefilyn]

We discussed a bit in calls and I forgot to make a note about it. In short:

• Keeping the manifest JSON schema next to the code it documents is best, so keeping it in cockpit repo makes sense.
• We should recommend using the schema as a URL. Which with Antora would make it possible to have versioning too.
• For CI we should use local files instead of URL. Which is possible to override in a lot of the tools available -- For Fedora and CI I think python jsonschema is the easiest to get and we can use it with a simple python script

[Venefilyn]

We can also generate AsciiDoc files from JSON Schema using something like https://github.com/CesiumGS/wetzel

[Venefilyn]

I'm gonna block this on #21515 to make things easier for myself