Add machine-readable export of QA findings

[adiatmad]

Problem

MapathonQA already performs several useful QA checks and identifies the affected OSM objects internally. The current primary output is the human-readable PDF report.

However, there is currently no simple, stable, machine-readable representation of the individual QA findings.

This makes it difficult for other tools to consume MapathonQA's existing findings without either:

• depending on MapathonQA's internal Java/JOSM implementation;
• parsing the human-readable report; or
• reimplementing the same QA logic.

Reimplementing the checks elsewhere would create unnecessary duplication and could cause different tools to produce different interpretations of the same QA rules.

Proposed capability

Add an optional machine-readable export of the existing QA findings.

The exported result should, at minimum, allow a downstream consumer to determine:

• which QA check produced each finding;
• which OSM primitives are affected; and
• enough basic metadata to identify the QA run.

Affected OSM primitives should use stable identifiers, for example:

node/123456
way/123456
relation/123456

A conceptual example:

{
  "format": "mapathonqa-results",
  "version": 1,
  "project_id": 50430,
  "mapathon_name": "Example Mapathon",
  "findings": [
    {
      "check": "non_yes_building_tags",
      "object_ids": ["way/123456"]
    },
    {
      "check": "overlapping_buildings",
      "object_ids": ["way/123456", "way/987654"]
    }
  ]
}

The example above is illustrative only. The exact schema and implementation should be determined after inspecting the existing MapathonQA architecture.

Downstream use case

One immediate use case is OSM QA Buddy, an independent QA workflow tool that can consume findings from existing QA engines and associate them with mapping tasks.

The intention is not to make MapathonQA dependent on OSM QA Buddy, nor to make OSM QA Buddy part of this plugin.

Instead, the desired relationship is a small interoperability boundary:

                    MapathonQA
                        │
                        │ machine-readable findings
                        ▼
              interoperability boundary
                   │           │
                   ▼           ▼
              OSM QA Buddy   Other tools

MapathonQA should remain fully useful on its own, while its existing QA findings become reusable by other quality-assurance workflows.

Important constraints

This proposal is about exposing existing QA results, not changing how MapathonQA performs QA.

Please preserve the following:

• Existing QA checks remain the source of truth.
• Existing check behaviour and semantics remain unchanged.
• The existing PDF/report workflow continues to work.
• MapathonQA must not depend on OSM QA Buddy or another downstream application.
• No API, database, or external service is required for this capability.
• The exported format should use stable OSM identifiers rather than Java object identity.
• The format should be documented and versioned.
• The solution should introduce the smallest reasonable amount of new code.
• Avoid refactoring unrelated parts of the plugin.
• Avoid creating a second, parallel QA-result architecture if the existing QAResults structure can cleanly serve as the source of truth.

Implementation guidance

Since this issue may be implemented with Claude/Codex, please inspect the repository and existing architecture before proposing or writing code.

In particular, first investigate:

1. How QAResults currently represents the findings.
2. How the existing QA checks populate QAResults.
3. Where the current report-generation flow receives the completed results.
4. Whether the existing result structure already contains enough information to produce stable OSM primitive IDs.
5. What the smallest clean extension point is for an optional machine-readable export.
6. Whether the proposed approach can preserve the current PDF/report behaviour without modifying the semantics of the checks.

The implementation should then be based on that investigation rather than introducing a new abstraction simply because it is convenient for the implementation agent.

If the repository reveals a materially better approach than the conceptual JSON example above, that approach should be preferred.

Acceptance criteria

A solution should satisfy the following:

• A normal MapathonQA run can optionally produce a machine-readable representation of its findings.
• Each exported finding identifies its originating QA check.
• Affected OSM primitives can be identified using stable OSM IDs.
• Basic run metadata can be associated with the result.
• The output format is documented.
• The output format has an explicit version.
• Existing QA check behaviour and semantics are unchanged.
• Existing PDF/report generation continues to work.
• A downstream application can consume the findings without depending on MapathonQA's internal Java classes.
• MapathonQA remains independently usable without OSM QA Buddy.
• The implementation does not introduce an unnecessary API, database, service, or large architectural refactor.

Out of scope

This issue does not request:

• new QA checks;
• changes to existing QA rules;
• changes to JOSM Validator;
• integration with OSM QA Buddy;
• Tasking Manager integration;
• automatic task attribution;
• new scoring or ranking logic;
• replacement of the existing PDF report;
• a new API or database;
• a rewrite of the existing QA architecture.

Those can be considered separately if a demonstrated need arises.

Expected workflow

The preferred workflow is:

Understand existing architecture
        ↓
Identify smallest clean extension point
        ↓
Define/document minimal output contract
        ↓
Implement optional export
        ↓
Verify existing QA behaviour is unchanged
        ↓
Verify existing PDF/report workflow still works
        ↓
Test machine-readable output

The goal is deliberately modest:

Make MapathonQA's existing QA findings consumable by other tools without duplicating the QA logic or coupling MapathonQA to any particular downstream application.

[Patrik-Br]

Hello @adiatmad this is definitely possible to implement within next update. Just few questions to make sure I understand it correctly

• So the classic checking mapathon quality workflow would output additional file with listed objects, their geometry, possibly their OSM version but I think thats unrelated, reasoning why they got flagged
  -- The export lists flagged objects, not individual issues. Overlapping buildings stores the flagged buildings but not which pairs overlap. Shared nodes stores the affected buildings, not the shared nodes.
• do you have a preffered file type? Would GeoJSON works for you?
• as this is something niche I would put a toggle on/off for creating this file in advanced JOSM preferences, off by default so regular user doesn't notice

[adiatmad]

Thanks Patrik! Yes, that matches what I had in mind.

For the finding semantics, object-level export is enough for the current use case. We don't need to represent relationships such as which two buildings overlap or exactly which node is shared. Having the affected OSM primitives is sufficient for downstream review.

I also don't think OSM version information is necessary for the first iteration. The important part for us is a stable primitive identifier such as way/123456, together with the originating QA check and, if already available from the existing results, a human-readable reason.

GeoJSON would work well as a machine-readable representation of the QA findings. However, I would separate that from the actual JOSM/BetterWorkspace handoff. In QA Buddy, the current interoperability approach uses the existing QA findings GeoJSON as the input, then produces a plain OSM layer containing the candidate Ways and their referenced Nodes. The QA metadata stays in a separate versioned JSON manifest rather than being written into OSM tags. This lets JOSM open the candidates directly, after which BetterWorkspace can use its existing multi-validation workflow.

So I wouldn't want MapathonQA to implement anything specifically for QA Buddy. A small, documented export of the existing results is enough, and the exact schema can follow whatever fits the existing QAResults architecture best.

The advanced JOSM preference toggle being off by default also makes sense to me. It keeps the normal mapathon workflow unchanged while making the export available for users who need it.

The main things I'd consider useful in the export are:

• stable OSM primitive ID;
• originating QA check/type;
• human-readable reason, if already available;
• geometry;
• basic run/project metadata where it already exists.

No need for a new result system or downstream-specific fields.

That should give QA Buddy and other tools a clean boundary without MapathonQA needing to know anything about how they consume the data.

Thanks again for being open to adding this in the next update!