Merge pull request OSGeo#11530 from elpaso/ogr_schema_docs

[doc] OGR_SCHEMA documentation
makesoftwaresafe · Dec 20, 2024 · 931c095 · 931c095
2 parents 7041096 + 21485be
commit 931c095
Show file tree

Hide file tree

Showing 3 changed files with 22 additions and 8 deletions.
diff --git a/doc/source/programs/ogr2ogr.rst b/doc/source/programs/ogr2ogr.rst
@@ -372,9 +372,7 @@ output coordinate system or even reprojecting the features during translation.
 
     Limit the number of features per layer.
 
-.. option:: -oo <NAME>=<VALUE>
-
-    Input dataset open option (format specific).
+.. include:: options/oo_vector.rst
 
 .. option:: -doo <NAME>=<VALUE>
 
@@ -496,7 +494,10 @@ output coordinate system or even reprojecting the features during translation.
     avoid typing a long SQL query. Note that this does not influence the field
     types used by the source driver, and is only an afterwards conversion.
     Also note that this option is without effects on fields whose presence and
-    type is hard-coded in the output driver (e.g KML, GPX)
+    type is hard-coded in the output driver (e.g KML, GPX).
+    For an alternative way to manipulate field types earlier in the process while they
+    are read from the input dataset see :option:`-oo` ``OGR_SCHEMA`` (only available
+    for a limited set of formats).
 
 .. option:: -mapFieldType {<srctype>|All=<dsttype>[,<srctype2>=<dsttype2>]...}
 
@@ -511,7 +512,10 @@ output coordinate system or even reprojecting the features during translation.
     Note that this does not influence the field types used by the source
     driver, and is only an afterwards conversion.
     Also note that this option is without effects on fields whose presence and
-    type is hard-coded in the output driver (e.g KML, GPX)
+    type is hard-coded in the output driver (e.g KML, GPX).
+    For an alternative way to manipulate field types earlier in the process while they
+    are read from the input dataset see :option:`-oo` ``OGR_SCHEMA`` (only available
+    for a limited set of formats).
 
 .. option:: -dateTimeTo {UTC|UTC(+|-)<HH>|UTC(+|-)<HH>:<MM>}
 

diff --git a/doc/source/programs/ogrinfo.rst b/doc/source/programs/ogrinfo.rst
@@ -168,9 +168,7 @@ edit data.
     value is ``YES``. (WKT and ``ISO_WKT`` are available starting with GDAL 2.1,
     which also changes the default to ISO_WKT)
 
-.. option:: -oo <NAME>=<VALUE>
-
-    Dataset open option (format-specific)
+.. include:: options/oo_vector.rst
 
 .. option:: -nomd
 

diff --git a/doc/source/programs/options/oo_vector.rst b/doc/source/programs/options/oo_vector.rst
@@ -0,0 +1,12 @@
+.. option:: -oo <NAME>=<VALUE>
+
+    Dataset open option (format specific).
+
+    If a driver supports the ``OGR_SCHEMA`` open option, it can be used to
+    partially or completely override the auto-detected schema (i.e. which
+    fields are read, with which types, subtypes, length, precision etc.)
+    of the dataset.
+
+    The value of this option is a JSON string or a path to a JSON file that
+    complies with the `OGR_SCHEMA open option schema definition <https://raw.githubusercontent.com/OSGeo/gdal/refs/heads/master/ogr/data/ogr_fields_override.schema.json>`_
+