improve add-on metadata fields docs

Author: ntarocco

docs/operate/customize/metadata/optional_fields.md

@@ -12,7 +12,7 @@ The current optional fields are:
 - Meeting (Conference)
 - Software (CodeMeta)
 
-You can see more details about each field group in [the metadata documentation](../../../use/records/custom-fields.md)
+You can see more details about each field group in [the metadata documentation](../../../reference/metadata.md#custom-fields).
 
 Metadata fields in InvenioRDM are defined by three configuration variables:
 

docs/reference/metadata.md

@@ -6,9 +6,9 @@ InvenioRDM's bibliographic records are stored as JSON documents in a structure
 that is aligned with DataCite's Metadata Schema v4.x with minor additions
 and modifications.
 
-!!! info "Datacite references"
+!!! info "DataCite references"
 
-    This document refers to Datacite schema properties for the reader's convenience (e.g., "*2. Creator* in DataCite"). The corresponding Datacite document can be found under <https://schema.datacite.org/>. The currently supported version is [v4.3](https://schema.datacite.org/meta/kernel-4.3).
+    This document refers to DataCite schema properties for the reader's convenience (e.g., "*2. Creator* in DataCite"). The corresponding DataCite document can be found under <https://schema.datacite.org/>. The currently supported version is [v4.3](https://schema.datacite.org/meta/kernel-4.3).
 
 
 ## Top-level fields
@@ -21,6 +21,7 @@ and modifications.
 |   ``parent``    | Related parent information.                                                        |
 |   ``access``    | Access control information.                                                        |
 |  ``metadata``   | Descriptive metadata.                                                              |
+|  ``custom_fields``   | Descriptive metadata extensions.                                                              |
 |    ``files``    | Associated files information.                                                      |
 |  ``tombstone``  | Tombstone information.                                                             |
 |   ``created``   | Database-level creation timestamp (UTC).                                           |
@@ -39,6 +40,7 @@ A record thus looks like:
     "parent": { ... },
     "access" : { ... },
     "metadata" : { ... },
+    "custom_fields" : { ... },
     "files" : { ... },
     "tombstone" : { ... },
     "created" : "...",
@@ -232,9 +234,9 @@ The abbreviation `CV` stands for *Controlled Vocabulary*.
 
 The type of the resource described by the record. The resource type must be selected from a controlled vocabulary which can be customized by each InvenioRDM instance.
 
-When interfacing with Datacite, this field is converted to a format compatible with *10. Resource Type*  (i.e. ``type`` and ``subtype``). DataCite allows free text for the subtype, however InvenioRDM requires this to come from a customizable controlled vocabulary.
+When interfacing with DataCite, this field is converted to a format compatible with *10. Resource Type*  (i.e. ``type`` and ``subtype``). DataCite allows free text for the subtype, however InvenioRDM requires this to come from a customizable controlled vocabulary.
 
-The resource type vocabulary also defines mappings to other vocabularies than Datacite such as Schema.org, Citation Style Language, BibTeX, and OpenAIRE. These mappings are very important for the correct generation of citations due to how different types are being interpreted by reference management systems.
+The resource type vocabulary also defines mappings to other vocabularies than DataCite such as Schema.org, Citation Style Language, BibTeX, and OpenAIRE. These mappings are very important for the correct generation of citations due to how different types are being interpreted by reference management systems.
 
 Subfields:
 
@@ -503,7 +505,7 @@ Example:
 
 Rights management statement for the resource.
 
-When interfacing with Datacite, this field is converted to be compatible with *16. Rights*.
+When interfacing with DataCite, this field is converted to be compatible with *16. Rights*.
 
 The rights field is intended to primarily be linked to a customizable vocabulary
 of licenses (defaults [SPDX](https://spdx.org/licenses/)). It should however also be possible to provide
@@ -844,7 +846,7 @@ Example:
 
 Technical format of the resource.
 
-This field is compatible with *14. Format* in Datacite.
+This field is compatible with *14. Format* in DataCite.
 
 Example:
 
@@ -1012,6 +1014,68 @@ Example:
 }
 ```
 
+## Custom fields
+Custom fields are the recommended way to extend the internal data model to fit your specific needs.
+In addition to supporting your own custom extensions, InvenioRDM provides a set of ready-to-use add-on fields—implemented via custom fields—that can be enabled without advanced configuration.
+
+See the [related documentation](../operate/customize/metadata/optional_fields.md) on how to enable them.
+
+### Journal
+Describe the scholarly journal in which the article was published.
+
+|    Field   | Description                                                                   |
+|:----------:|:------------------------------------------------------------------------------|
+| ``title``  | The full name of the journal (e.g., Journal of Environmental Studies).        |
+| ``issn``   | The journal's International Standard Serial Number (e.g., 2077-9550).         |
+| ``volume`` | The volume in which the article appeared (e.g., 645).                         |
+| ``issue``  | The issue number (e.g., 7).                                                   |
+| ``pages``  | Enter either the page range (e.g., 15-23) or article identifier (e.g., A29).  |
+
+### Imprint
+Describe publications that are part of a book or report, such as chapters, contributions, or institutional publications.
+
+|    Field      | Description                                                                                |
+|:-------------:|:-------------------------------------------------------------------------------------------|
+| ``title``     |  Title of the larger work your submission is part of (e.g., Handbook of Bioethics).        |
+| ``place``     |  The city and country where the book/report was published (e.g., Oxford, United Kingdom).  |
+| ``pages``     |  Specific page numbers or page range (e.g., 15-23 or 158).                                 |
+| ``isbn``      |  The book's International Standard Book Number (e.g., 0-06-251587-X).                      |
+| ``edition``   |  The edition number, if applicable (e.g., 3 for third edition).                            |
+
+### Thesis
+Describe a bachelor's, master's, or doctoral thesis, including details such as the awarding university, department, thesis type, and key dates.
+
+|        Field        | Description                                                                         |
+|:-------------------:|:------------------------------------------------------------------------------------|
+| ``university``      | Full name of the institution that granted the degree (e.g., University of Geneva).  |
+| ``department``      | Name of the faculty or department (e.g., Department of Computer Science).           |
+| ``type``            | The level of the thesis (e.g., PhD, Masters, Bachelors).                            |
+| ``date_submitted``  | The date the thesis was officially submitted (format: YYYY-MM-DD).                  |
+| ``date_defended``   | The date the thesis was defended (format: YYYY-MM-DD).                              |
+
+### Meeting
+Use this field to describe a meeting or conference.
+
+|        Field      | Description                                              |
+|:-----------------:|:---------------------------------------------------------|
+| ``title``         | Meeting or conference title.                             |
+| ``acronym``       | Acronym that represents the conference.                  |
+| ``dates``         | Dates when the meeting took place.                       |
+| ``place``         | Location where the meeting took place.                   |
+| ``session``       | Session within the meeting or conference.                |
+| ``session_part``  | Part within the session.                                 |
+| ``url``           | Link of the conference website.                          |
+| ``identifiers``   | Meeting identifiers, a list of identifier/scheme pairs.  |
+
+### CodeMeta
+This group of fields contains metadata to describe a software record based on the [CodeMeta standard](https://codemeta.github.io/index.html).
+
+|        Field              | Description                                 |
+|:-------------------------:|:--------------------------------------------|
+| ``codeRepository``        | `URL`: Link to the repository where the related code is located (e.g. Github).               |
+| ``programmingLanguage``   | `Vocabulary`: Name of the programming language used to develop the software from the [vocabulary](https://github.com/inveniosoftware/invenio-rdm-records/blob/e64dd0b81757a391584e63d162d5e6caf6780637/invenio_rdm_records/fixtures/data/vocabularies/contrib/codemeta/programming_languages.yaml).     |
+| ``developmentStatus``     | `Vocabulary`: Description of the development status (e.g. "Active"). Uses a controlled vocabulary defined in [repostatus](http://www.repostatus.org/).          |
+
 ## Files
 
 Records may have associated digital files. A record is not meant to be associated

docs/releases/v12/version-v12.0.0.md

@@ -115,7 +115,7 @@ Here is a quick summary of the myriad other improvements in this release:
 - Enable/disable restricted records at the instance-level via the `RDM_ALLOW_RESTRICTED_RECORDS` configuration variable
 - [New export formats](../../use/records/export-formats.md) such as DACT-AP and GeoJSON
 - [Signposting](https://zenodo.org/doi/10.5281/zenodo.12554415) has been integrated in a record's API responses and using the `Accept: application/linkset+json` header for a `/api/records/<record_id>` call returns the Linkset.
-- [Optional metadata fields](../../use/records/custom-fields.md) that are easy to enable
+- [Optional metadata fields](../../operate/customize/metadata/optional_fields.md) that are easy to enable
 - Improvements to the `invenio rdm rebuild-all-indices` command
 - Mathematical formulas in a deposit can be rendered on the landing page via
   - `THEME_MATHJAX_CDN = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"` and

docs/use/imgs/records/codemeta_deposit_form.png

@@ -40,44 +40,16 @@ For a deeper understanding of the high-level architecture behind records, **refe
 
 InvenioRDM offers **add-on metadata fields** that are not enabled by default. To utilize these, you will need to **add them to your configuration**. These specialized fields are designed for specific publication types, including:
 
-- **Journal articles**
-- **Book chapters/reports**
-- **Theses**
+- [Journal](../../reference/metadata.md#journal): describe a scholarly journal.
+- [Imprint](../../reference/metadata.md#imprint): describe chapters and contributions of a book or a report.
+- [Thesis](../../reference/metadata.md#thesis): describe a dissertation.
+- [Meeting](../../reference/metadata.md#meeting): describe a meeting or a conference.
+- [CodeMeta](../../reference/metadata.md#codemeta): set of fields to describe software.
 
 These add-on fields are particularly valuable for institutions like **universities, research institutes, and repositories** that manage diverse scholarly outputs.
 
 ![Publishing info](../imgs/records/publishing-info.png)
 
-📰 Journal (for journal articles)
-
-Fill this section if your upload was published in a scholarly journal.
-
-- Title: The full name of the journal (e.g., Journal of Environmental Studies).
-- ISSN: The journal’s International Standard Serial Number (e.g., 2077-9550).
-- Volume: The volume in which the article appeared (e.g., 645).
-- Issue: The issue number (e.g., 7).
-- Page range or article number: Enter either the page range (e.g., 15–23) or article identifier (e.g., A29).
-
-📖 Imprint (for books, chapters, or reports)
-
-Use this if your upload is part of a book or report (e.g., a chapter, contribution, or institutional publication).
-
-- Book or report title: Title of the larger work your submission is part of (e.g., Handbook of Bioethics).
-- Place: The city and country where the book/report was published (e.g., Oxford, United Kingdom).
-- Pagination: Specific page numbers or page range (e.g., 15–23 or 158).
-- ISBN: The book’s International Standard Book Number (e.g., 0-06-251587-X).
-- Edition: The edition number, if applicable (e.g., 3 for third edition).
-
-🎓 Thesis (for academic theses)
-
-If your upload is a bachelor’s, master’s, or doctoral thesis, use this section.
-
-- Awarding university: Full name of the institution that granted the degree (e.g., University of Geneva).
-- Awarding department: Name of the faculty or department (e.g., Department of Computer Science).
-- Thesis type: The level of the thesis (e.g., PhD, Masters, Bachelors).
-- Submission date: The date the thesis was officially submitted (format: YYYY-MM-DD)
-- Defense date: The date the thesis was defended (if applicable).
-
 Once the fields are filled and the record is published, publishing information will be displayed on the record landing page on the right side panel, as follows:
 
 ![Landing page publishing information](../imgs/records/publishing-info-landing-page.png)