Unclear format for map json data, add a "nodeMapsData"?

[T-X]

Background: Currently both the Gluon census-exporter for the Gluon Census and the meshviewer-collector for multi.meshviewer.org maintain their own lists for JSON sources:

• https://github.com/freifunk-gluon/census-exporter/blob/master/communities.json
• https://github.com/genofire/meshviewer-collector/blob/develop/config.toml

Most communities also provide map JSON data via api.freifunk.net, however their current, aggregated state is pretty unusable for both the gluon-census and the meshviewer-collector at the moment: freifunk-gluon/census-exporter#4 (comment)

I'm wondering if this might be due to an unclear specification regarding a meshviewer.json or a Hopglass nodes.json. At least all four entries with a meshviewer.json in the Freifunk API all use a different format: freifunk-gluon/census-exporter#4 (comment)

---

Suggestion A):

1. Clarify that nodeMaps is only for HTML rendered maps. 2) deprecate "nodelist" in nodeMaps. 3) add a new nodeMapData like the following:

        "nodeMapData": {
            "type": "array",
            "title": "Node map data sources",
            "description": "Machine-readable node map data of nodes or topology your community provides",
            "items": {
                "type": "object",
                "title": "node",
                "properties": {
                    "url": {
                        "$ref": "#/definitions/url",
                        "title": "URL of the map",
                        "description": "The URL where the map data is located"
                    },
                    "interval": {
                        "type": "string",
                        "title": "interval",
                        "description": "How often the map data will be refreshed"
                    },
                    "mediaType": {
                        "type": "string",
                        "title": "Media Type as registered at IANA: https://www.iana.org/assignments/media-types/media-types.xhtml",
                        "description": "",
                        "enum": [ "", "text/csv", "application/json" ],
                        "default": ""
                    }
                    "mapDataFormat": {
                        "type": "string",
                        "title": "Map Data Format",
                        "description": "The format of the provided map data",
                        "enum": [ "", "nodelist", "meshviewer", "meshviewer/old", "hopglass/v1", "hopglass/v2" ],
                        "default": ""
                    }
                },
                "additionalProperties": false

If mapDataType is "nodelist", "meshviewer", "meshviewer/old", "hopglass/v1" or "hopglass/v2" then only mediaType: "application/json" should be allowed. (If such a constraint is not possible then maybe split this into "nodeMapDataJSON" and "nodeMapDataCVS"?)

I'd suggest / tend to having nodeMapData adjacent to instead of within nodeMap. As some communities for instance have two nodeMapData for one meshviewer instance, where one points to the geographical map tab and the other to the topology graph tab.

[T-X]

Suggestion B):

Same as the suggestion above, but add a "geographical+structural" to nodeMaps->mapType to avoid "duplicate" meshviewer/hopglass entries, then have nodeMapData as a sub object of nodeMap.

[T-X]

Suggestion C):

No new nodeMapData, instead add new technicalType values of: "meshviewerJSON", "meshviewerJSON/old", "hopglassJSON/v1", "hopglassJSON/v2". Define/clarify that technicalType values "meshviewer" and "hopglass" are supposed to point to the HTML rendered map.

[T-X]

And another thing I just noticed that might be a bit ambiguous / unclear: Some have a nodeMaps with several array entries for the same map but different types, like nodelist and meshviewer. While others have for instance multiple nodelist entries with distinct nodes, just from different gateways.

So for automation it might be unclear if they should pick one, whichever they can reach and parse. Or if they should get and merge all.

[andibraeu]

as api.freifunk.net is mainly a schema definition, and other tools collect decentralized API files from communities, it's not possible to check any constraints based on the communities data. It would be possible the have checks at a validation point of time. But that's not the scope of that schema.

I think the easiest would be to add new technical types, but you need to push people to update their files then :)

[awlx]

Yes, keeping the data up to date is also what we discovered is the biggest issue. That's why we also called it out in our federated map journey :).

https://ffmuc.net/freifunk/karte/community/2026/02/24/neue-federated-knotenkarte/#en