Update documentation for deprecated contact_details field

docs/using/index.md

@@ -46,6 +46,30 @@ import aiod
 aiod.datasets.get_list()
 ```
 
+## Schema Note: Contact Metadata
+
+Earlier versions of the metadata schema included a `contact_details`
+field on the `Person` and `Organisation` entities which represented
+a one-to-one relationship with a contact.
+
+This field is now deprecated and has been removed from the data model.
+
+Instead, contacts should be defined using the generic contact mapping
+available at the `AIResource` level. This mapping allows multiple
+contacts to be associated with a resource using a list of contact
+identifiers.
+
+**Recommended approach**
+
+Use the `contacts` list defined on the AIResource level.
+level rather than defining contacts directly on `Person` or
+`Organisation`.
+
+**Compatibility**
+
+This change is treated as non-breaking. Existing one-to-one
+`contact_details` mappings are migrated automatically to the
+many-to-many contact link table during database migrations.
 
 ## Exploring REST API Endpoints
 By navigating to the [Swagger documentation](https://api.aiod.eu/docs), you can find information and examples on how to access the different endpoints.

docs/using/migration-v1-v2.md

@@ -109,3 +109,41 @@ Most crucially, there may be cases when a user wants to link assets by identifie
 While we can support them under different endpoints, there is no way for use to ensure a user does not (accidentally) link assets referencing old identifiers on a new endpoint, or vice versa.
 Maintaining the integrity of the data in the metadata catalogue is our highest priority, and so we decided that unfortunately we cannot support a grace period.
 We hope for your understanding and will do our best to avoid such a scenario in the future.
+
+## Contact Metadata Changes
+
+### What changed
+
+The `contact_details` field previously present on the `Person`
+and `Organisation` entities has been removed.
+
+### Why
+
+The field duplicated functionality already available through the
+generic `AIResource` contact mapping and was not part of the
+official AI-on-Demand metadata metamodel.
+
+Maintaining both systems created unnecessary redundancy and
+potential inconsistencies.
+
+### Migration behaviour
+
+Existing one-to-one `contact_details` mappings are migrated
+automatically to the many-to-many contact relationship used
+by `AIResource`.
+
+During migration:
+
+- Existing `contact_details` references are copied into the
+  AIResource contact link table.
+- The `contact_details` column is then removed.
+
+### Compatibility
+
+This change is considered non-breaking because:
+
+- Only one instance currently exists in the test server
+- The field is not used in production environments
+
+Applications should update their integrations to use the
+generic contact list instead.

docs/using/upload.md

@@ -55,6 +55,29 @@ Take a note of the identifier assigned to the asset, as you will need it to requ
 The asset is now in draft mode, which means that other users cannot see it but you can, and you may still edit it.
 To edit the asset, use the `PUT` endpoints for `/ASSET`.
 
+### Contact Metadata
+
+Contacts should be associated with assets using the generic
+contact mapping provided at the `AIResource` level.
+
+Earlier schema versions allowed defining a `contact_details`
+field on `Person` and `Organisation`. This field is now removed
+and should no longer be used when uploading metadata.
+
+Instead, contacts should be provided as a list of identifiers.
+
+Example:
+
+```json
+{
+  "name": "Example Dataset",
+  "contacts": [
+    "contact_identifier_1",
+    "contact_identifier_2"
+  ]
+}
+```
+
 ### Requesting a Review
 When you want to publish the asset, you can submit it for review. You
 can do this by making a `POST` request to the `/submissions` endpoint.