DOC: Add schema versioning scheme

docs/src/conf.py

@@ -30,9 +30,6 @@ def filter(self, record: logging.LogRecord) -> bool:
 
 # -- General configuration ---------------------------------------------
 
-# The full version, including alpha/beta/rc tags.
-release = fmu.dataio.__version__
-
 extensions = [
     "myst_parser",
     "pydantic_autosummary",
@@ -111,17 +108,21 @@ def set_myst_substitutions() -> dict[str, str]:
 # The master toctree document.
 master_doc = "index"
 
-# General information about the project.
-project = "fmu.dataio"
-current_year = date.today().year
-copyright = f"Equinor {current_year} (fmu-dataio release {release})"
-
-
 exclude_patterns = ["_build"]
 
 pygments_style = "sphinx"
 
+# General information about the project.
+project = "fmu-dataio"
+current_year = date.today().year
+# The full version, including alpha/beta/rc tags.
+release = fmu.dataio.__version__
+# The short version, like 3.0
+version = ".".join(release.split(".")[:2])
+
 html_theme = "furo"
+html_title = f"{project} {version}"
+copyright = f"Equinor {current_year} ({project} release {release})"
 # html_logo = "images/logo.png"
 
 # The name of an image file (within the static path) to use as favicon

docs/src/exported_data_products.md

@@ -1,4 +1,4 @@
-# Data Product Exports
+# Data product exports
 
 fmu-dataio exposes functions for the export of data products. These are
 _standardized results_ that must conform to particular data shapes defined in

docs/src/index.rst

@@ -41,6 +41,13 @@ post-processing services, new and improved cloud-only version of Webviz and much
    preparations
    examples
    exported_data_products
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Developer Guides
+
+   schema_versioning
+   datamodel/index
    dataio_3_migration
    apiref/modules
-   datamodel/index

docs/src/products/initial_inplace_volumes.md

@@ -1,4 +1,4 @@
-# Initial Inplace Volumes
+# Initial inplace volumes
 
 This exports the initial inplace volumes of a single grid from within RMS.
 
@@ -71,7 +71,7 @@ The payload may contain other columns than the standard columns listed above.
 However, when these columns are present, their type is validated.
 ```
 
-## Product Schema
+## Product schema
 
 This product is made available with a validation schema that can be used by
 consumers. A reference to the URL where this schema is present within the
@@ -85,7 +85,7 @@ consumers. A reference to the URL where this schema is present within the
    :exclude-members: dump
 ```
 
-### JSON Schema
+### JSON schema
 
 You can view the schema embedded here:
 

docs/src/schema_versioning.md

@@ -0,0 +1,85 @@
+# Schema versioning
+
+This document describes how schemas produced by fmu-dataio are versioned,
+under what circumstances version numbers change, and provides criteria for the
+kind of version change (patch, minor, major) a schema change causes.
+
+```{note}
+The version of fmu-dataio is decoupled from the versions of schemas it produces.
+This means that a new version of fmu-dataio may cause no schema changes at
+all. Similarly, a new version of fmu-dataio may cause just one schema version
+to change, or even _all_ of them.
+
+There is no direct relationship between an fmu-dataio version and schema
+versions aside from the fact that a schema version may have changed _with_ a
+new fmu-dataio version.
+```
+
+## Schema version changes
+
+Schema versions follow [semantic versioning](http://semver.org/). This gives
+every schema version a specific number in the form `X.Y.Z` where
+
+- `X` is the major version number,
+- `Y` is the minor version number,
+- `Z` is the patch version number (sometimes called the _micro_ version).
+
+Schema version numbers change when a schema is changed. When deciding what
+version a changed schema should become the primary concern should be whether
+or not the change being made is backward compatible. Backwards compatibility
+is broken if metadata generated for and valid against a previous version is
+invalid against the updated version.
+
+Therefore schema version numbers change like so.
+
+### Major
+
+Any schema change that **breaks backward compatibility** with metadata created
+using the previous schema version. These scenarios are candidates for a major
+version change:
+
+- Adding a new required field
+- Removing a required or optional field
+- Moving an optional field to a required field
+- Adding a regular expression or stricter validation to a field
+  - **Example**: A string field applies a maximum length validation check
+- Changing the name of a field
+  - **Example**: `datetime` is changed to `timestamp`
+- Changing the type of a field
+  - **Example**: A float field is changed is changed to a float string
+- Changing the data format of a field
+  - **Example**: A date field is changed from Unix timestamp to ISO 8601 string
+- Splitting or merging fields
+  - **Example**: A `version` field is changed to `major`, `minor`, `patch` (or
+      vice versa)
+- Removing a value from a controlled vocabulary
+  - **Example**: `OWC` is no longer a valid contact (_unlikely, but an example!_)
+- Changing the cardinality of field
+  - **Example**: An array field of length 4 becomes an array of length 8
+
+### Minor
+
+Any schema change that **retains backward compatibility** with metadata created
+using the previous version.
+
+- Adding an optional field
+- Making a required field optional
+- Changing a field from a controlled vocabulary to free text without changing
+    the field type
+- Removing a regular expression or validation from a field
+- Adding alternative formats for the same data
+  - **Example**: `"YYYY-MM-DD"` exists, and now `"YYYY/MM/DD"` is allowed
+- Adding a computed or derived field that _is not required to be present_.
+  - **Example**: A sha1 hash is computed on an object metadata is representing
+  - **Example**: A _deterministic_ UUID is computed on an object and its metadata
+
+### Patch
+
+Any change to **auxiliary information** that does not affect the structure or
+semantics of the schema itself. Also, any bug fixes to the schema.
+
+- Adding or updating the field description to improve readability, add
+    context, or correct an error
+- Adding or updating the field example, comment, or user-friendly name
+- Extending a controlled vocabulary enumeration
+- Fixing an incorrect regular expression or validation