Kart status JSON output changes for point clouds

[olsen232]

Kart status includes information about the working copy. The structure of the working copy is going through some major changes as we add support for Point Clouds - specifically, the current tabular / database-shaped / vector working copy is only going to be part of the Kart working copy - there will also be a file-based part where point cloud tiles can fit.

This means the current JSON status output, where workingCopy is simply "None" if no tabular working copy currently exists, will not be sufficient. More detailed specification follows:

Difference between old status and new status output:

{
- "kart.status/v1": {
+ "kart.status/v2": {
    "commit": "3c1e3c3487a6313d46896751e9db2dd5e91d97c2",
    "abbrevCommit": "3c1e3c3",
    "branch": "main",
    "upstream": null,
    "spatialFilter": null,
    "workingCopy": {
-     "path": "example.gpkg",
+     "parts": {
+       "tabular": {
+         "location": "example.gpkg",
+         "type": "gpkg",
+         "status": "ok"
+       }
      },
      "changes": ...
    }
  }
}

JSON version number is bumped from v1 to v2

The field "workingCopy" is now null only if the repo is bare. Otherwise, it is always present and contains two fields, "parts" and "changes". The field "path" is removed and replaced with the field "parts", which contains info about all of the different dataset parts. In practice there is currently one part, called "tabular" - this is where vector / tabular data is stored. This part will always be present. More parts are to come.

The tabular part always contains these 3 fields:

• a location (eg path or db server URL - this is the same info as was previously in "path"). This is where the tabular part is configured to be - it may not actually exist or be contactable. Can also be null if tabular WC is not configured
• type - one of "gpkg", "postgresql", "mssql", or "mysql". Can also be null if tabular WC is not configured
• status - either "ok" or "notFound".

The status field currently distinguishes between whether the WC part exists or not. Other distinctions may be added later if requested by clients. Be aware that not having tabular WC configured but not currently existing is allowed, although it prevents certain operations, so don't be too strict in preventing user's from using Kart if the tabular status is "notFound"

Here are three reasons the tabular WC may be "notFound"

• repo is new and empty, no tabular WC is yet created
• repo has only point clouds, no tabular WC is yet created
• repo had a tabular WC, but the user deleted it for some reason - maybe it was the easiest way they could think of to revert uncommitted changes

The changes field is as before, but it note that it can now be present even if tabular part of the WC is non-existent - one day there will be other changes that come from other WC parts.

[pfw]

My first thought here is if there a way to make the change 'additive' only, ie. the existing workingCopy value remains and new data is added. Does a 'client' like a plugin or app run the risk of messing things up if it doesn't understand the working copy changes or can it keep going with the old path and then some new data alongside it that it can optionally understand. If it can work with partial understanding then the plugins etc. can be updated at different points.

[olsen232]

As of point-cloud release 0.12, info about another part will also always present in the status output, but currently with very little actual info. The part is called "workdir" and the only info given about it is simply its status - one of either "ok" or "notFound". As with tabular, it being "notFound" is allowed for much the same reasons.

Here is an example status output:

 "kart.status/v2": {
   "commit": "3c1e3c3487a6313d46896751e9db2dd5e91d97c2",
   "abbrevCommit": "3c1e3c3",
   "branch": "main",
   "upstream": null,
   "spatialFilter": null,
   "workingCopy": {
      "path": "example.gpkg",
      "parts": {
        "tabular": {
          "location": "example.gpkg",
          "type": "gpkg",
          "status": "ok"
         },
         "workdir": {
           "status": "ok"
         }
      },
      "changes": ...
    }
  }
}