GRENML Repository

GRENML topologies of research and education networks. The RENMAP/ folder is the source of truth for the map at renmap.rnp.br: anyone can propose a correction with a pull request, and once it is merged the map picks it up automatically.

1. Propose: edit the JSON files in RENMAP/data/ and open a pull request.
2. Automatic check: the Validate topology workflow checks the data, generates the GRENML and posts a summary of what changed (nodes and links added, removed or moved) on the workflow run page. The generated XML is attached as an artifact.
3. Review: a maintainer reviews and merges the pull request.
4. Publish: on main, the Publish GRENML workflow regenerates RENMAP/topologies.xml and RENMAP/topologies/ and commits them.
5. Map update: the renmap.rnp.br server checks RENMAP/topologies.xml every 10 minutes and imports it when it changes. Institution popup texts are kept.

You only ever edit files under RENMAP/data/. The XML files are generated, so don't edit them by hand: the next publish overwrites them.

RENMAP/data/
  institutions.json   every institution (network operator)
  nodes/<id>.json     the nodes of one network
  links/<id>.json     the links of one network

File names are just a way to organise the data; what ties nodes and links to an institution is the owners field.

[
  { "id": "rnp", "name": "RNP", "tag": "nren" }
]

Most of this data was compiled semi-automatically and partly extracted with AI. The map says so: every network shows an AI-generated badge until someone checks it by hand. After checking a network's nodes and links against a reliable source, open a pull request that adds both fields to its entry:

{ "id": "rnp", "name": "RNP", "tag": "nren", "verified_by": "hugoromao", "verified_on": "2026-11-10" }

The map then shows a Verified badge with who checked it and when. Remove the two fields if the data is found to be unreliable again.

The map also shows when each network's data last changed, with a link to that change. Nobody fills this in: the generator takes it from the git history of main (the last merged change to the network's entry in institutions.json or to any node or link it owns, in any file). Changes to scripts or documentation don't count.

Renaming an institution resets its map popup. The GRENML ID is derived from the name, so the server treats a renamed institution as a new one. After the rename is published, the popup text has to be entered again in the map's admin.

[
  { "name": "Boa Vista", "lat": 2.82, "lon": -60.67, "owners": ["rnp"], "networks": "RNP" }
]

[
  { "a": "Boa Vista", "b": "Manaus", "owners": ["rnp"], "networks": "RNP" }
]

The same link written twice in the same direction is an error. The same pair in opposite directions (a→b and b→a) is accepted as a parallel circuit but reported as a warning.

Optional: the pull request workflow runs the same checks. You need uv.

uv run --project RENMAP RENMAP/scripts/validate.py   # check the data
uv run --project RENMAP RENMAP/scripts/generate.py --output-dir /tmp/grenml   # generate the XML
uv run --project RENMAP pytest -q RENMAP   # test the scripts

The generator is deterministic: the same data and git history always produce byte-identical XML. It needs the full history to date each network's last change; in a shallow clone it warns and leaves the dates out.

NRENs/ and the [POC] files are earlier hand-made topologies. They are not part of the automated flow.