gdal CLI: surface `GDAL_OF_UPDATE` in `--json-usage`

[brownag]

Feature description

GetUsageAsJSON() currently drops the GDAL_OF_UPDATE bitmask. Downstream bindings thus cannot tell from JSON usage if an algorithm modifies a dataset in-place.

I propose adding "open_for_update": true (or similar*) to the JSON schema for when GDAL_OF_UPDATE is set.

Additional context

In-place modifications break idempotency. Adding this property will help bindings know when a file is being mutated to maintain reproducibility.

*This request is complicated by the fact that mutating behavior can come from a base algorithm (e.g. gdal raster edit) or an optional mode within an algorithm (e.g. --update in gdal vector concat).

To resolve this, perhaps conditional mutation could be handled with an argument-level property containing an array of other argument names?

For example, in the output dataset argument for vector concat "open_for_update": ["update", "append"] would imply: "this dataset opens for update if the --update or --append flags are present."

Something like:

...
  "input_output_arguments":[
    {
      "name":"output",
      "type":"dataset",
      "description":"Output vector dataset",
      "required":true,
      "category":"Base",
      "dataset_type":[
        "vector"
      ],
      "input_flags":[
        "name",
        "dataset"
      ],
      "output_flags":[
        "dataset"
      ],
+     "open_for_update": [
+       "update", 
+       "append"
+     ]
    }
  ],
  ...

I can provide draft PR if needed and idea is acceptable to maintainers. Thanks in advance for your consideration and excellent work on GDAL.

[rouault]

I can provide draft PR if needed and idea is acceptable to maintainers

that sounds reasonable. There's a subtely though. For example, gdal raster edit has a --auxiliary argument (that has an hidden alias to GDAL_ARG_NAME_READ_ONLY), or gdal raster overview add has a --external argument (also with hidden alias to GDAL_ARG_NAME_READ_ONLY), that instructs the logic that opens dataset to not open in update mode.

So maybe

For vector concat output:

"open_for_update": {
     "by_default": False
     "if_any_of": [ "update", "append" ],
}

For raster edit dataset:

"open_for_update": {
     "by_default": True,
     "unless_any_of": ["auxiliary"]
}