From 298635c01588bcf5addec3535113c5d7856be99a Mon Sep 17 00:00:00 2001
From: Guillaume Viger <fenekku@fenekku.com>
Date: Tue, 13 Aug 2024 14:23:27 -0400
Subject: [PATCH] metadata: document parent.access.owned_by breaking change

---
 docs/reference/metadata.md                | 10 ++--
 docs/reference/rest_api_drafts_records.md | 64 +++++++++--------------
 docs/releases/versions/version-v12.0.0.md |  1 +
 3 files changed, 29 insertions(+), 46 deletions(-)

diff --git a/docs/reference/metadata.md b/docs/reference/metadata.md
index d07554f4..f0d66578 100644
--- a/docs/reference/metadata.md
+++ b/docs/reference/metadata.md
@@ -163,7 +163,7 @@ The ``access`` is described with the following subfields:
 
 |    Field     | Cardinality | Description         |
 |:------------:|:-----------:|:--------------------|
-| ``owned_by`` |    (1-n)    | An array of owners. |
+| ``owned_by`` |    (1)    | A single owner. (*WARNING: This was changed in v12. It used to be an array.*)|
 
 Owners are defined as:
 
@@ -179,11 +179,9 @@ Example:
   "parent": {
     "id": "fghij-12345",
     "access": {
-      "owned_by": [
-        {
-          "user": 2
-        }
-      ],
+      "owned_by": {
+        "user": 2
+      }
     }
   },
 }
diff --git a/docs/reference/rest_api_drafts_records.md b/docs/reference/rest_api_drafts_records.md
index 86c924dc..6e617a2b 100644
--- a/docs/reference/rest_api_drafts_records.md
+++ b/docs/reference/rest_api_drafts_records.md
@@ -151,11 +151,9 @@ Content-Type: application/json
   "parent": {
     "id": "{parent-id}",
     "access": {
-      "owned_by": [
-        {
-          "user": {user-id}
-        }
-      ],
+      "owned_by": {
+        "user": {user-id}
+      },
       "links": []
     }
   },
@@ -259,11 +257,9 @@ Content-Type: application/json
   "parent": {
     "id": "{parent-id}",
     "access": {
-      "owned_by": [
-        {
-            "user": {user-id}
-        }
-      ],
+      "owned_by": {
+        "user": {user-id}
+      },
       "links": []
     }
   },
@@ -410,11 +406,9 @@ Content-Type: application/json
   "parent": {
     "id": "{parent-id}",
     "access": {
-      "owned_by": [
-        {
-            "user": {user-id}
-        }
-      ],
+      "owned_by": {
+        "user": {user-id}
+      },
       "links": []
     }
   },
@@ -513,11 +507,9 @@ Content-Type: application/json
   "parent": {
     "id": "{parent-id}",
     "access": {
-      "owned_by": [
-        {
-            "user": {user-id}
-        }
-      ],
+      "owned_by": {
+        "user": {user-id}
+      },
       "links": []
     }
   },
@@ -618,11 +610,9 @@ Content-Type: application/json
   "parent": {
     "id": "{parent-id}",
     "access": {
-      "owned_by": [
-        {
-            "user": {user-id}
-        }
-      ],
+      "owned_by": {
+        "user": {user-id}
+      },
       "links": []
     }
   },
@@ -1081,11 +1071,9 @@ Content-Type: application/json
   "parent": {
     "id": "{parent-id}",
     "access": {
-      "owned_by": [
-        {
-            "user": {user-id}
-        }
-      ],
+      "owned_by": {
+        "user": {user-id}
+      },
       "links": []
     }
   },
@@ -1361,11 +1349,9 @@ Content-Type: application/json
   "parent": {
     "id": "{parent-id}",
     "access": {
-      "owned_by": [
-        {
-            "user": {user-id}
-        }
-      ],
+      "owned_by": {
+        "user": {user-id}
+      },
       "links": []
     }
   },
@@ -1559,11 +1545,9 @@ Content-Type: application/json
   "parent": {
     "id": "{parent-id}",
     "access": {
-      "owned_by": [
-        {
-            "user": {user-id}
-        }
-      ],
+      "owned_by": {
+        "user": {user-id}
+      },
       "links": []
     }
   },
diff --git a/docs/releases/versions/version-v12.0.0.md b/docs/releases/versions/version-v12.0.0.md
index c93309c6..0a700b10 100644
--- a/docs/releases/versions/version-v12.0.0.md
+++ b/docs/releases/versions/version-v12.0.0.md
@@ -151,6 +151,7 @@ Here is a quick summary of the myriad other improvements in this release:
 - Although not immediately breaking, the [`subject_nested` facet](https://github.com/inveniosoftware/invenio-rdm-records/blob/master/invenio_rdm_records/services/facets.py#L87) is deprecated in favor of [`subject_combined`](https://github.com/inveniosoftware/invenio-rdm-records/blob/master/invenio_rdm_records/services/facets.py#L103) to provide proper nested subject aggregation
 - The Python module `flask_babelex` has been replaced by `invenio_i18n`
     - Any imports should be replaced: `from flask_babelex import lazy_gettext as _` -> `from invenio_i18n import lazy_gettext as _`
+- The cardinality of the Drafts and Records Metadata/REST API field `parent.access.owned_by` changed from `(1-n)` (an array of objects) to `(1)` (a single object).
 
 ## Limitations and known issues