openapi.json

{
    "openapi": "3.2.0",
    "info": {
        "title": "ERNIE API",
        "summary": "Read-only metadata, vocabulary, and citation endpoints for ERNIE integrations.",
        "version": "1.0.0",
        "description": "REST API for ERNIE (Earth Research Notary for Information Editing) - A metadata editor for reviewers of research data at GFZ Helmholtz Centre for Geosciences. This API provides read-only access to metadata types and controlled vocabularies for integration with ELMO and other external systems.",
        "termsOfService": "https://ernie.rz-vm182.gfz.de/legal-notice",
        "contact": {
            "name": "Holger Ehrmann",
            "url": "https://www.gfz.de/staff/holger.ehrmann/sec51",
            "email": "ehrmann@gfz.de"
        },
        "license": {
            "name": "GNU General Public License v3.0 or later",
            "identifier": "GPL-3.0-or-later"
        }
    },
    "externalDocs": {
        "description": "ERNIE Project Documentation",
        "url": "https://github.com/McNamara84/ernie"
    },
    "servers": [
        {
            "name": "Current ERNIE deployment",
            "url": "https://ernie.rz-vm182.gfz.de",
            "description": "The currently configured ERNIE instance"
        }
    ],
    "tags": [
        {
            "name": "Editor Configuration",
            "summary": "Metadata types and editor option endpoints",
            "description": "Endpoints for retrieving metadata types and roles configuration used by external editors like ELMO"
        },
        {
            "name": "Vocabularies",
            "summary": "Controlled vocabularies and availability endpoints",
            "description": "Endpoints for accessing controlled vocabularies from NASA GCMD (Global Change Master Directory), PID registries (b2inst and RAiD), and ROR (Research Organization Registry)"
        },
        {
            "name": "DataCite",
            "summary": "Citation and DOI metadata lookup endpoints",
            "description": "Endpoints for retrieving citation metadata and author information for DOIs via the DataCite API and doi.org Content Negotiation"
        },
        {
            "name": "IGSN Imports",
            "summary": "Authenticated IGSN import operations",
            "description": "Session-authenticated endpoints for discovering legacy datacenter groups and starting IGSN imports from DataCite."
        },
        {
            "name": "Portal",
            "summary": "Public data portal endpoints",
            "description": "Public endpoints used to discover published ERNIE resources."
        }
    ],
    "security": [],
    "paths": {
        "/api/v1/resource-types/elmo": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List resource types enabled for ELMO",
                "description": "Returns all resource types that are enabled for ELMO. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of resource types",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/ElmoResourceType"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                }
            }
        },
        "/api/v1/title-types/elmo": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List title types enabled for ELMO",
                "responses": {
                    "200": {
                        "description": "List of title types",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/TitleType"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                },
                "description": "Returns all title types that are enabled for ELMO. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ]
            }
        },
        "/api/v1/licenses/elmo": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List licenses enabled for ELMO",
                "responses": {
                    "200": {
                        "description": "List of licenses",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/License"
                                    }
                                },
                                "example": [
                                    {
                                        "id": 1,
                                        "identifier": "CC-BY-4.0",
                                        "name": "Creative Commons Attribution 4.0 International",
                                        "uri": "https://creativecommons.org/licenses/by/4.0/",
                                        "scheme_uri": "https://spdx.org/licenses/"
                                    }
                                ]
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                },
                "description": "Returns all licenses that are enabled for ELMO. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ]
            }
        },
        "/api/v1/licenses/elmo/{resourceTypeSlug}": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List licenses enabled for ELMO filtered by resource type",
                "description": "Returns all licenses that are enabled for ELMO and available for the specified resource type. Licenses that have the resource type in their exclusion list will not be returned. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "parameters": [
                    {
                        "name": "resourceTypeSlug",
                        "in": "path",
                        "required": true,
                        "description": "The slug of the resource type (e.g., 'software', 'dataset', 'book-chapter')",
                        "schema": {
                            "type": "string",
                            "example": "software"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of licenses available for the resource type",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/License"
                                    }
                                },
                                "example": [
                                    {
                                        "id": 1,
                                        "identifier": "MIT",
                                        "name": "MIT License",
                                        "uri": "https://spdx.org/licenses/MIT.html",
                                        "scheme_uri": "https://spdx.org/licenses/"
                                    },
                                    {
                                        "id": 2,
                                        "identifier": "GPL-3.0-or-later",
                                        "name": "GNU General Public License v3.0 or later",
                                        "uri": "https://spdx.org/licenses/GPL-3.0-or-later.html",
                                        "scheme_uri": "https://spdx.org/licenses/"
                                    }
                                ]
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "Resource type not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Resource type not found."
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/date-types/elmo": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List date types enabled for ELMO",
                "description": "Returns all date types that are enabled for ELMO. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of date types",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/DateType"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                }
            }
        },
        "/api/v1/description-types": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List all description types",
                "description": "Returns all description types defined in the system, regardless of their activation status. No authentication required.",
                "responses": {
                    "200": {
                        "description": "List of all description types",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/DescriptionType"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/description-types/elmo": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List description types enabled for ELMO",
                "description": "Returns all description types that are enabled for ELMO (both `is_active` and `is_elmo_active` must be true). Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of description types enabled for ELMO",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/DescriptionType"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                }
            }
        },
        "/api/v1/description-types/ernie": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List description types enabled for ERNIE",
                "description": "Returns all description types that are active for the ERNIE editor. No authentication required.",
                "responses": {
                    "200": {
                        "description": "List of active description types",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/DescriptionType"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/languages/elmo": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List languages enabled for ELMO",
                "responses": {
                    "200": {
                        "description": "List of languages",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/Language"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                },
                "description": "Returns all languages that are enabled for ELMO. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ]
            }
        },
        "/api/v1/roles/authors/elmo": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List author roles active for ELMO",
                "description": "Returns all author roles that are active for ELMO. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of roles",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/Role"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                }
            }
        },
        "/api/v1/roles/contributor-persons/elmo": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List contributor person roles active for ELMO",
                "description": "Returns all contributor person roles that are active for ELMO. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of roles",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/Role"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                }
            }
        },
        "/api/v1/roles/contributor-institutions/elmo": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List contributor institution roles active for ELMO",
                "description": "Returns all contributor institution roles that are active for ELMO. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of roles",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/Role"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                }
            }
        },
        "/api/v1/relation-types": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List all relation types",
                "description": "Returns all DataCite relation types defined in the system, regardless of their activation status. No authentication required.",
                "responses": {
                    "200": {
                        "description": "List of all relation types",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/RelationType"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/relation-types/ernie": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List relation types enabled for ERNIE",
                "description": "Returns all relation types that are active for the ERNIE editor (`is_active` is true). No authentication required.",
                "responses": {
                    "200": {
                        "description": "List of active relation types",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/RelationType"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/relation-types/elmo": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List relation types enabled for ELMO",
                "description": "Returns all relation types that are enabled for ELMO (both `is_active` and `is_elmo_active` must be true). Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of relation types enabled for ELMO",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/RelationType"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                }
            }
        },
        "/api/v1/identifier-types": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List all identifier types with patterns",
                "description": "Returns all DataCite identifier types defined in the system with their active validation and detection regex patterns. Only patterns that are currently active are included. No authentication required.",
                "responses": {
                    "200": {
                        "description": "List of all identifier types with active patterns",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/IdentifierType"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/identifier-types/ernie": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List identifier types enabled for ERNIE",
                "description": "Returns all identifier types that are active for the ERNIE editor (`is_active` is true) with their active patterns. No authentication required.",
                "responses": {
                    "200": {
                        "description": "List of active identifier types with active patterns",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/IdentifierType"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/identifier-types/elmo": {
            "get": {
                "tags": ["Editor Configuration"],
                "summary": "List identifier types enabled for ELMO",
                "description": "Returns all identifier types that are enabled for ELMO (both `is_active` and `is_elmo_active` must be true) with their active validation and detection regex patterns. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of identifier types enabled for ELMO with patterns",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/IdentifierType"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                }
            }
        },
        "/api/v1/vocabularies/gcmd-science-keywords": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Get GCMD Science Keywords vocabulary",
                "description": "Returns the complete GCMD (Global Change Master Directory) Science Keywords vocabulary as a hierarchical JSON structure. The vocabulary is loaded from NASA's KMS (Keyword Management System) API. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "GCMD Science Keywords vocabulary",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GcmdScienceKeywords"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "Vocabulary file not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Vocabulary file not found. Please run: php artisan get-gcmd-science-keywords"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/vocabularies/gcmd-platforms": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Get GCMD Platforms vocabulary",
                "description": "Returns the complete GCMD (Global Change Master Directory) Platforms vocabulary as a hierarchical JSON structure. The vocabulary is loaded from NASA's KMS (Keyword Management System) API. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "GCMD Platforms vocabulary",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GcmdPlatforms"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "Vocabulary file not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Vocabulary file not found. Please run: php artisan get-gcmd-platforms"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/vocabularies/gcmd-instruments": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Get GCMD Instruments vocabulary",
                "description": "Returns the complete GCMD (Global Change Master Directory) Instruments vocabulary as a hierarchical JSON structure. The vocabulary is loaded from NASA's KMS (Keyword Management System) API. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "GCMD Instruments vocabulary",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GcmdInstruments"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "Vocabulary file not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Vocabulary file not found. Please run: php artisan get-gcmd-instruments"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/vocabularies/msl-laboratories": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Get MSL laboratories vocabulary",
                "description": "Returns the locally stored Originating Multi-Scale Laboratories vocabulary with version metadata. Each laboratory contains the seven fields from the canonical Utrecht University vocabulary. Internal source and Git SHA metadata are never included. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "MSL laboratories vocabulary",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MslLaboratoriesResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "Thesaurus is disabled or the local vocabulary file is missing",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Vocabulary file not found. Please run: php artisan get-msl-laboratories"
                                        }
                                    },
                                    "required": ["error"]
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "The local vocabulary file is unreadable or corrupted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "The local MSL laboratories vocabulary contains invalid JSON."
                                        }
                                    },
                                    "required": ["error"]
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/vocabularies/chronostrat-timescale": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Get ICS Chronostratigraphic Timescale vocabulary",
                "description": "Returns the International Chronostratigraphic Chart (ICS) as a hierarchical JSON structure. The vocabulary is loaded from the ARDC (Australian Research Data Commons) Linked Data API and contains geologic time intervals (eons, eras, periods, epochs, ages). Boundary and GSSP concepts are filtered out. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ICS Chronostratigraphic Timescale vocabulary",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ChronostratTimescale"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "Thesaurus is disabled or vocabulary file not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Vocabulary file not found. Please run: php artisan get-chronostrat-timescale"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/vocabularies/gemet": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Get GEMET Thesaurus vocabulary",
                "description": "Returns the GEMET (GEneral Multilingual Environmental Thesaurus) as a hierarchical JSON structure. The vocabulary is loaded from the EIONET GEMET REST API and contains environmental concepts organized in SuperGroups, Groups, and Concepts. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "GEMET Thesaurus vocabulary",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GemetThesaurus"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "Thesaurus is disabled or vocabulary file not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Vocabulary file not found. Please run: php artisan get-gemet-thesaurus"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/vocabularies/analytical-methods": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Get Analytical Methods for Geochemistry vocabulary",
                "description": "Returns the 'Analytical Methods for Geochemistry and Cosmochemistry' vocabulary as a hierarchical JSON structure. The vocabulary is loaded from the ARDC (Australian Research Data Commons) Linked Data API and contains analytical methods (e.g., Mass Spectrometry, ICP-MS) with notation codes and definitions. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Analytical Methods vocabulary",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AnalyticalMethodsVocabulary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "Thesaurus is disabled or vocabulary file not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Vocabulary file not found. Please run: php artisan get-analytical-methods"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/vocabularies/euroscivoc": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Get European Science Vocabulary (EuroSciVoc)",
                "description": "Returns the European Science Vocabulary (EuroSciVoc) as a hierarchical JSON structure. EuroSciVoc is a taxonomy of fields of science based on OECD's 2015 Frascati Manual, extended with categories from CORDIS content. The vocabulary is published by the Publications Office of the European Union. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "EuroSciVoc vocabulary",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EuroSciVocVocabulary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "Thesaurus is disabled or vocabulary file not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Vocabulary file not found. Please run: php artisan get-euroscivoc"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/vocabularies/cgi-simple-lithology": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Get CGI Simple Lithology vocabulary",
                "description": "Returns the CGI Simple Lithology vocabulary as a validated hierarchical JSON structure. ERNIE downloads the vocabulary from the official CGI vocabulary SPARQL API, preserves all paths of polyhierarchical concepts, and serves only the last successfully validated local copy. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "CGI Simple Lithology vocabulary",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CgiSimpleLithologyVocabulary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "Thesaurus is disabled or no validated local vocabulary is installed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Vocabulary file not found. Please run: php artisan get-cgi-simple-lithology"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/vocabularies/pid4inst-instruments": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Get PID4INST instruments vocabulary",
                "description": "Returns the complete PID4INST instruments vocabulary from b2inst (EUDAT instrument registry). Each instrument includes a persistent identifier (Handle PID), name, description, and additional metadata such as owners, manufacturers, instrument types, and measured variables. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PID4INST instruments vocabulary",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Pid4instInstruments"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "PID4INST is disabled or vocabulary file not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "PID4INST is disabled"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/vocabularies/raid-projects": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Get RAiD projects for ELMO",
                "description": "Returns public RAiD (Research Activity Identifier) project records discovered through DataCite with a metadata wrapper including total count and last update timestamp. Each entry includes the RAiD identifier, title, description, dates, contributors, organisations, related identifiers, and search terms. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "RAiD projects with metadata wrapper",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RaidProjects"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "RAiD is disabled or data file not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "RAiD is disabled"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/vocabularies/thesauri-availability": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Check thesauri availability",
                "description": "Returns the availability status of all configured thesauri (e.g., GCMD Science Keywords, GCMD Platforms, GCMD Instruments, ICS Chronostratigraphic Chart). This endpoint does not require authentication and is intended for frontend configuration checks.",
                "responses": {
                    "200": {
                        "description": "Thesauri availability status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ThesauriAvailability"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/vocabularies/pid-availability": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Check PID registry availability",
                "description": "Returns the availability status of all configured PID registries (e.g., PID4INST, ROR, RAiD). This endpoint does not require authentication and is intended for frontend configuration checks.",
                "responses": {
                    "200": {
                        "description": "PID registry availability status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PidAvailability"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/ror-affiliations/elmo": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Get ROR affiliations for ELMO",
                "description": "Returns the complete ROR (Research Organization Registry) data with metadata wrapper including total count and last update timestamp. Each entry includes the preferred label, ROR ID, and alternative labels/search terms. Provide the API key via the `X-API-Key` header.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ROR affiliations with metadata wrapper",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RorAffiliations"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "404": {
                        "description": "ROR is disabled or data file not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "ROR is disabled"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/elmo/vocabularies/thesauri-availability": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Check thesauri availability for ELMO",
                "description": "Returns the availability status of all configured thesauri from the ELMO perspective (uses `is_elmo_active` flag). Requires API key authentication. For unauthenticated frontend checks, use `/api/v1/vocabularies/thesauri-availability` instead.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Thesauri availability status for ELMO",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ThesauriAvailability"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                }
            }
        },
        "/api/v1/elmo/vocabularies/pid-availability": {
            "get": {
                "tags": ["Vocabularies"],
                "summary": "Check PID registry availability for ELMO",
                "description": "Returns the availability status of all configured PID registries from the ELMO perspective (uses `is_elmo_active` flag). Requires API key authentication. For unauthenticated frontend checks, use `/api/v1/vocabularies/pid-availability` instead.",
                "security": [
                    {
                        "ElmoApiKey": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PID registry availability status for ELMO",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PidAvailability"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    }
                }
            }
        },
        "/api/v1/citation-lookup": {
            "get": {
                "tags": ["DataCite"],
                "summary": "Look up bibliographic metadata by DOI (Related Item Manager)",
                "description": "Returns structured bibliographic metadata (title, authors, publication year, volume, issue, pages, publisher, identifier) for a given DOI. Used by the Related Item Manager curation form to auto-fill related item fields. Primary source is the Crossref REST API (polite pool); DataCite is used as a fallback. Responses are cached for 24h. Requires authentication and is rate-limited to 30 requests per minute per user.",
                "parameters": [
                    {
                        "name": "doi",
                        "in": "query",
                        "required": true,
                        "description": "The DOI to look up (bare DOI or resolver URL).",
                        "schema": {
                            "type": "string",
                            "example": "10.1029/2018JB016456"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lookup completed. The response payload always contains the `source` discriminator. On a hit, `source` is `crossref` or `datacite` and the bibliographic fields are populated. On a miss, `source` is `not_found` and only `identifier` and `identifier_type` are returned.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["source", "identifier", "identifier_type"],
                                    "properties": {
                                        "source": {
                                            "type": "string",
                                            "enum": ["crossref", "datacite", "not_found"],
                                            "description": "Origin of the bibliographic data, or `not_found` if neither Crossref nor DataCite returned a record."
                                        },
                                        "identifier": { "type": "string", "example": "10.1029/2018JB016456" },
                                        "identifier_type": { "type": "string", "example": "DOI" },
                                        "related_item_type": { "type": ["string", "null"], "example": "JournalArticle" },
                                        "title": { "type": ["string", "null"] },
                                        "subtitle": { "type": ["string", "null"] },
                                        "publication_year": { "type": ["integer", "null"], "example": 2019 },
                                        "publisher": { "type": ["string", "null"] },
                                        "volume": { "type": ["string", "null"] },
                                        "issue": { "type": ["string", "null"] },
                                        "first_page": { "type": ["string", "null"] },
                                        "last_page": { "type": ["string", "null"] },
                                        "creators": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "name_type": { "type": "string", "enum": ["Personal", "Organizational"] },
                                                    "name": { "type": "string" },
                                                    "given_name": { "type": ["string", "null"] },
                                                    "family_name": { "type": ["string", "null"] },
                                                    "name_identifier": { "type": ["string", "null"] },
                                                    "name_identifier_scheme": { "type": ["string", "null"] }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Missing or invalid DOI query parameter"
                    },
                    "429": {
                        "description": "Rate limit exceeded (30 requests/minute)"
                    },
                    "401": {
                        "$ref": "#/components/responses/UnauthorizedError"
                    },
                    "502": {
                        "description": "Transient upstream failure. Returned when the primary metadata provider (Crossref) errored and the DataCite fallback did not produce a confirming hit. Clients should retry after a short delay rather than treat this as `not_found`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["source", "identifier", "identifier_type", "message", "error"],
                                    "properties": {
                                        "source": { "type": "string", "example": "crossref" },
                                        "identifier": { "type": "string" },
                                        "identifier_type": { "type": "string", "example": "DOI" },
                                        "message": {
                                            "type": "string",
                                            "example": "Upstream metadata provider is temporarily unavailable. Please try again."
                                        },
                                        "error": { "type": "string", "example": "HTTP 503" }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/datacite/citation": {
            "get": {
                "tags": ["DataCite"],
                "summary": "Get formatted citation for a DOI",
                "description": "Returns a formatted citation string for the given DOI. Uses doi.org Content Negotiation API to retrieve CSL JSON metadata and builds a human-readable citation. The DOI can be provided as a bare DOI (10.5880/...) or as a resolver URL (https://doi.org/10.5880/...); resolver prefixes are stripped automatically.",
                "parameters": [
                    {
                        "name": "doi",
                        "in": "query",
                        "required": true,
                        "description": "The DOI to look up. Accepts bare DOIs (10.5880/GFZ.TEST.2024) or resolver URLs (https://doi.org/10.5880/GFZ.TEST.2024).",
                        "schema": {
                            "type": "string",
                            "example": "10.5880/GFZ.TEST.2024"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Citation retrieved successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "citation": {
                                            "type": "string",
                                            "example": "Smith, John (2024): Test Dataset. GFZ Data Services. https://doi.org/10.5880/GFZ.TEST.2024"
                                        },
                                        "doi": {
                                            "type": "string",
                                            "description": "The normalized DOI in lowercase canonical form",
                                            "example": "10.5880/gfz.test.2024"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Metadata not found for the given DOI",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Metadata not found for DOI"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Missing or invalid DOI query parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Missing or invalid doi query parameter"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/datacite/authors": {
            "get": {
                "tags": ["DataCite"],
                "summary": "Get structured author data for a DOI",
                "description": "Returns structured author information for the given DOI, including affiliations, ORCID identifiers, and author type (Person/Institution). First tries the DataCite REST API (which includes affiliations and nameType), then falls back to CSL JSON via doi.org Content Negotiation for non-DataCite DOIs. The DOI can be provided as a bare DOI or resolver URL.",
                "parameters": [
                    {
                        "name": "doi",
                        "in": "query",
                        "required": true,
                        "description": "The DOI to look up. Accepts bare DOIs (10.5880/GFZ.TEST.2024) or resolver URLs (https://doi.org/10.5880/GFZ.TEST.2024).",
                        "schema": {
                            "type": "string",
                            "example": "10.5880/GFZ.TEST.2024"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Author data retrieved successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "doi": {
                                            "type": "string",
                                            "description": "The normalized DOI in lowercase canonical form",
                                            "example": "10.5880/gfz.test.2024"
                                        },
                                        "authors": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "given_name": {
                                                        "type": ["string", "null"],
                                                        "example": "John"
                                                    },
                                                    "family_name": {
                                                        "type": ["string", "null"],
                                                        "example": "Smith"
                                                    },
                                                    "name": {
                                                        "type": ["string", "null"],
                                                        "description": "Full name for organizational authors"
                                                    },
                                                    "orcid": {
                                                        "type": ["string", "null"],
                                                        "example": "0000-0002-1234-5678"
                                                    },
                                                    "type": {
                                                        "type": "string",
                                                        "enum": ["Person", "Institution"],
                                                        "example": "Person"
                                                    },
                                                    "ror_id": {
                                                        "type": ["string", "null"],
                                                        "example": "https://ror.org/04z8jg394"
                                                    },
                                                    "affiliations": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "object",
                                                            "properties": {
                                                                "name": {
                                                                    "type": "string",
                                                                    "example": "GFZ Helmholtz Centre"
                                                                },
                                                                "identifier": {
                                                                    "type": ["string", "null"],
                                                                    "example": "https://ror.org/04z8jg394"
                                                                },
                                                                "identifier_scheme": {
                                                                    "type": ["string", "null"],
                                                                    "example": "ROR"
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Metadata not found for the given DOI",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Metadata not found for DOI"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Missing or invalid DOI query parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Missing or invalid doi query parameter"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/igsns/import/datacenters": {
            "get": {
                "tags": ["IGSN Imports"],
                "summary": "List legacy IGSN datacenters",
                "description": "Returns the currently available, known datacenters from the legacy GFZ IGSN portal with live resource counts. Legacy names are normalized to their canonical ERNIE datacenter names; in particular, GFZ Potsdam is returned as GFZ German Research Centre for Geosciences.",
                "security": [
                    {
                        "LaravelSession": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Legacy IGSN datacenters available for grouped imports.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/LegacyIgsnDatacenterListResponse"
                                },
                                "example": {
                                    "datacenters": [
                                        {
                                            "id": "IGSNDB.ICDP",
                                            "name": "ICDP",
                                            "legacy_name": "ICDP",
                                            "resource_count": 15813
                                        },
                                        {
                                            "id": "IGSNDB.GFZ",
                                            "name": "GFZ German Research Centre for Geosciences",
                                            "legacy_name": "GFZ Potsdam",
                                            "resource_count": 357
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Authentication required. The request must include a valid ERNIE session."
                    },
                    "403": {
                        "$ref": "#/components/responses/ForbiddenError"
                    },
                    "503": {
                        "description": "The legacy IGSN portal is temporarily unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MessageResponse"
                                },
                                "example": {
                                    "message": "The legacy IGSN portal is currently unavailable. Please try again later."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/igsns/import/start-datacenter": {
            "post": {
                "tags": ["IGSN Imports"],
                "summary": "Start an IGSN import for one legacy datacenter",
                "description": "Starts an authenticated background import for all IGSNs assigned to one currently available legacy IGSN datacenter. The server verifies the submitted legacy identifier against the live portal facet before queueing the job. Only newly created IGSNs receive the datacenter assignment; existing ERNIE resources are not changed.",
                "security": [
                    {
                        "LaravelSession": [],
                        "CsrfToken": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/DatacenterIgsnImportRequest"
                            },
                            "example": {
                                "datacenter_id": "IGSNDB.ICDP"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Datacenter IGSN import job was queued successfully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/IgsnImportStartResponse"
                                },
                                "example": {
                                    "import_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5e",
                                    "message": "Datacenter IGSN import started successfully"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Authentication required. The request must include a valid ERNIE session."
                    },
                    "403": {
                        "$ref": "#/components/responses/ForbiddenError"
                    },
                    "422": {
                        "description": "The legacy datacenter identifier is missing, malformed, unknown, or no longer available from the portal.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ValidationErrorResponse"
                                },
                                "example": {
                                    "message": "The selected legacy IGSN datacenter is no longer available.",
                                    "errors": {
                                        "datacenter_id": ["The selected legacy IGSN datacenter is no longer available."]
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "The legacy IGSN portal is temporarily unavailable, so ERNIE could not verify the datacenter before queueing the import.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MessageResponse"
                                },
                                "example": {
                                    "message": "The legacy IGSN portal is currently unavailable. Please try again later."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/igsns/import/start-single": {
            "post": {
                "tags": ["IGSN Imports"],
                "summary": "Start a single IGSN import from DataCite",
                "description": "Starts an authenticated background import for one IGSN. The value can be a bare IGSN handle, a configured-prefix DOI, or a doi.org URL. ERNIE verifies the record at DataCite before queueing the job. If the requested IGSN is a parent, direct children discovered through DataCite relationships and legacy sources are included. If the requested IGSN is a child, DataCite parent-chain and sibling groups are included as import targets.",
                "security": [
                    {
                        "LaravelSession": [],
                        "CsrfToken": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SingleIgsnImportRequest"
                            },
                            "examples": {
                                "handle": {
                                    "summary": "Bare IGSN handle",
                                    "value": {
                                        "igsn": "ICDP5052EUYY001"
                                    }
                                },
                                "doi": {
                                    "summary": "Configured-prefix DOI",
                                    "value": {
                                        "igsn": "10.60510/GFBNO7002EHG0001"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Single IGSN import job was queued successfully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/IgsnImportStartResponse"
                                },
                                "example": {
                                    "import_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5e",
                                    "message": "Single IGSN import started successfully"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Authentication required. The request must include a valid ERNIE session."
                    },
                    "403": {
                        "$ref": "#/components/responses/ForbiddenError"
                    },
                    "422": {
                        "description": "The IGSN input is missing, malformed, uses a foreign prefix, or could not be found at DataCite.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ValidationErrorResponse"
                                },
                                "examples": {
                                    "invalid": {
                                        "summary": "Invalid IGSN format",
                                        "value": {
                                            "message": "The IGSN must be a valid configured-prefix DOI or IGSN handle.",
                                            "errors": {
                                                "igsn": ["The IGSN must be a valid configured-prefix DOI or IGSN handle."]
                                            }
                                        }
                                    },
                                    "notFound": {
                                        "summary": "IGSN not found at DataCite",
                                        "value": {
                                            "message": "This IGSN could not be found at DataCite.",
                                            "errors": {
                                                "igsn": ["This IGSN could not be found at DataCite."]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "DataCite is temporarily unavailable, so ERNIE could not verify the requested IGSN before queueing the import.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MessageResponse"
                                },
                                "example": {
                                    "message": "DataCite is currently unavailable. Please try again later."
                                }
                            }
                        }
                    }
                }
            }
        },
        "/{portal}-search/free-keyword-suggestions": {
            "get": {
                "tags": ["Portal"],
                "summary": "Suggest free keywords for the public portal search",
                "description": "Returns up to 20 free keywords used by published records. Prefix matches are ranked before substring matches, then by usage count and label.",
                "operationId": "getPortalFreeKeywordSuggestions",
                "security": [],
                "parameters": [
                    {
                        "name": "portal",
                        "in": "path",
                        "required": true,
                        "description": "Fixed discovery portal scope.",
                        "schema": { "type": "string", "enum": ["doi", "igsn"] }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Case-insensitive free-keyword search term.",
                        "schema": { "type": "string", "minLength": 2, "maxLength": 100 },
                        "example": "seis"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Ranked free-keyword suggestions used by published records.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/PortalKeywordSuggestionResponse" },
                                "example": {
                                    "data": [
                                        { "value": "Seismology", "scheme": null, "count": 12 },
                                        { "value": "Paleoseismology", "scheme": null, "count": 3 }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "The query is missing or is outside the allowed length of 2 to 100 characters.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" },
                                "example": {
                                    "message": "The q field is required.",
                                    "errors": { "q": ["The q field is required."] }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Public portal suggestion rate limit exceeded (60 requests per minute by default).",
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds until the client may retry.",
                                "schema": { "type": "integer", "minimum": 0 }
                            },
                            "X-RateLimit-Limit": {
                                "description": "Configured request limit for the current window.",
                                "schema": { "type": "integer", "minimum": 1 }
                            },
                            "X-RateLimit-Remaining": {
                                "description": "Requests remaining in the current window.",
                                "schema": { "type": "integer", "minimum": 0 }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/MessageResponse" }
                            }
                        }
                    }
                }
            }
        },
        "/{portal}-search/count": {
            "get": {
                "tags": ["Portal"],
                "summary": "Count records matching the public portal filters",
                "description": "Returns the cached exact result total, final page, and semantic filter fingerprint for the public portal. Pagination is intentionally excluded from the fingerprint so the same count can be reused across result pages.",
                "operationId": "getPortalCount",
                "security": [],
                "parameters": [
                    {
                        "name": "portal",
                        "in": "path",
                        "required": true,
                        "description": "Fixed discovery portal scope. `doi` excludes physical samples; `igsn` returns only physical samples.",
                        "schema": { "type": "string", "enum": ["doi", "igsn"] }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Portal full-text search term.",
                        "schema": { "type": "string", "maxLength": 500 }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "description": "Legacy resource-type shortcut. The fixed portal scope remains authoritative, and the IGSN portal ignores resource-type filters.",
                        "schema": { "type": "string", "enum": ["doi", "igsn"] }
                    },
                    {
                        "name": "type[]",
                        "in": "query",
                        "required": false,
                        "description": "Selected resource-type slugs for the DOI portal. The IGSN portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "datacenter[]",
                        "in": "query",
                        "required": false,
                        "description": "Selected datacenter names.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "keywords[]",
                        "in": "query",
                        "required": false,
                        "description": "Legacy combined keyword filters.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "free_keywords[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact free-keyword filters.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "thesaurus_keywords[]",
                        "in": "query",
                        "required": false,
                        "description": "Selected controlled-vocabulary term identifiers for the DOI portal. The IGSN portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 2048 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "sample_types[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact sample types for the IGSN portal, combined with OR. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "materials[]",
                        "in": "query",
                        "required": false,
                        "description": "Controlled material nodes for the IGSN portal, combined with OR. Selecting a parent includes its descendants. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "classifications[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact classification values for the IGSN portal. Every selected value must be present. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "geological_ages[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact geological ages for the IGSN portal. Every selected value must be present. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "geological_units[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact geological units for the IGSN portal. Every selected value must be present. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "north",
                        "in": "query",
                        "required": false,
                        "description": "Northern latitude of the optional semantic spatial filter. Supply all four spatial filter bounds together.",
                        "schema": { "type": "number", "minimum": -90, "maximum": 90 }
                    },
                    {
                        "name": "south",
                        "in": "query",
                        "required": false,
                        "description": "Southern latitude of the optional semantic spatial filter.",
                        "schema": { "type": "number", "minimum": -90, "maximum": 90 }
                    },
                    {
                        "name": "east",
                        "in": "query",
                        "required": false,
                        "description": "Eastern longitude of the optional semantic spatial filter.",
                        "schema": { "type": "number", "minimum": -180, "maximum": 180 }
                    },
                    {
                        "name": "west",
                        "in": "query",
                        "required": false,
                        "description": "Western longitude of the optional semantic spatial filter.",
                        "schema": { "type": "number", "minimum": -180, "maximum": 180 }
                    },
                    {
                        "name": "date_type",
                        "in": "query",
                        "required": false,
                        "description": "Date field used by the optional temporal filter.",
                        "schema": { "type": "string", "enum": ["Created", "Collected", "Coverage"] }
                    },
                    {
                        "name": "year_from",
                        "in": "query",
                        "required": false,
                        "description": "Inclusive first year of the optional temporal filter.",
                        "schema": { "type": "integer", "minimum": 1900, "example": 2000 }
                    },
                    {
                        "name": "year_to",
                        "in": "query",
                        "required": false,
                        "description": "Inclusive last year of the optional temporal filter.",
                        "schema": { "type": "integer", "minimum": 1900, "example": 2026 }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Exact count and pagination metadata for the normalized portal filters.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/PortalCountResponse" }
                            }
                        }
                    },
                    "422": {
                        "description": "One or more IGSN metadata filter parameters are invalid.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }
                            }
                        }
                    },
                    "429": {
                        "description": "Public portal rate limit exceeded.",
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds until the client may retry.",
                                "schema": { "type": "integer", "minimum": 0 }
                            },
                            "X-RateLimit-Limit": {
                                "description": "Configured request limit for the current window.",
                                "schema": { "type": "integer", "minimum": 1 }
                            },
                            "X-RateLimit-Remaining": {
                                "description": "Requests remaining in the current window.",
                                "schema": { "type": "integer", "minimum": 0 }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/MessageResponse" }
                            }
                        }
                    },
                    "500": {
                        "description": "The exact count could not be completed, for example because another count still holds the cache lock.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/MessageResponse" }
                            }
                        }
                    }
                }
            }
        },
        "/{portal}-search/resources/{resourceId}/preview": {
            "get": {
                "tags": ["Portal"],
                "summary": "Load a citation and abstract for one portal result",
                "description": "Returns an on-demand APA 7 citation and the preferred non-empty abstract for a published result in the selected portal scope. DOI resources are available only through the DOI portal, while physical samples are available only through the IGSN portal.",
                "operationId": "getPortalResourcePreview",
                "security": [],
                "parameters": [
                    {
                        "name": "portal",
                        "in": "path",
                        "required": true,
                        "description": "Fixed discovery portal scope.",
                        "schema": { "type": "string", "enum": ["doi", "igsn"] }
                    },
                    {
                        "name": "resourceId",
                        "in": "path",
                        "required": true,
                        "description": "Internal identifier of the published portal resource.",
                        "schema": { "type": "integer", "minimum": 1 },
                        "example": 42
                    }
                ],
                "responses": {
                    "200": {
                        "description": "APA 7 citation and preferred abstract for the scoped published resource.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/PortalResourcePreviewResponse" },
                                "example": {
                                    "resourceId": 42,
                                    "citation": {
                                        "styleId": "apa-7",
                                        "label": "APA 7",
                                        "text": "Smith, J. (2026). A portal preview resource. https://doi.org/10.5880/example.2026.001"
                                    },
                                    "abstract": "A concise description of the published resource."
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The resource does not exist, is unpublished, or does not belong to the selected portal scope.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/MessageResponse" },
                                "example": { "message": "Resource not found." }
                            }
                        }
                    },
                    "429": {
                        "description": "Public portal rate limit exceeded.",
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds until the client may retry.",
                                "schema": { "type": "integer", "minimum": 0 }
                            },
                            "X-RateLimit-Limit": {
                                "description": "Configured request limit for the current window.",
                                "schema": { "type": "integer", "minimum": 1 }
                            },
                            "X-RateLimit-Remaining": {
                                "description": "Requests remaining in the current window.",
                                "schema": { "type": "integer", "minimum": 0 }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/MessageResponse" }
                            }
                        }
                    },
                    "503": {
                        "description": "The citation preview could not be rendered temporarily.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/MessageResponse" },
                                "example": { "message": "The citation preview is temporarily unavailable." }
                            }
                        }
                    }
                }
            }
        },
        "/{portal}-search/map": {
            "get": {
                "tags": ["Portal"],
                "summary": "Load clustered records for the public portal map",
                "description": "Returns a bounded set of server-side clusters and individual published records for the visible map viewport. DOI map categories represent Resource Types, while IGSN map categories represent top-level Materials. The optional total count and extent are cached by semantic portal filters, independently of viewport coordinates and dimensions.",
                "operationId": "getPortalMap",
                "security": [],
                "parameters": [
                    {
                        "name": "portal",
                        "in": "path",
                        "required": true,
                        "description": "Fixed discovery portal scope. `doi` excludes physical samples; `igsn` returns only physical samples.",
                        "schema": { "type": "string", "enum": ["doi", "igsn"] }
                    },
                    {
                        "name": "viewport[north]",
                        "in": "query",
                        "required": true,
                        "description": "Northern latitude of the visible technical map viewport.",
                        "schema": { "type": "number", "minimum": -90, "maximum": 90, "example": 54 }
                    },
                    {
                        "name": "viewport[south]",
                        "in": "query",
                        "required": true,
                        "description": "Southern latitude of the visible technical map viewport.",
                        "schema": { "type": "number", "minimum": -90, "maximum": 90, "example": 50 }
                    },
                    {
                        "name": "viewport[east]",
                        "in": "query",
                        "required": true,
                        "description": "Eastern longitude of the visible viewport. A value below west represents an antimeridian-crossing viewport.",
                        "schema": { "type": "number", "minimum": -180, "maximum": 180, "example": 16 }
                    },
                    {
                        "name": "viewport[west]",
                        "in": "query",
                        "required": true,
                        "description": "Western longitude of the visible viewport.",
                        "schema": { "type": "number", "minimum": -180, "maximum": 180, "example": 10 }
                    },
                    {
                        "name": "viewport[width]",
                        "in": "query",
                        "required": true,
                        "description": "Rendered map width in CSS pixels.",
                        "schema": { "type": "integer", "minimum": 1, "maximum": 4096, "example": 1000 }
                    },
                    {
                        "name": "viewport[height]",
                        "in": "query",
                        "required": true,
                        "description": "Rendered map height in CSS pixels.",
                        "schema": { "type": "integer", "minimum": 1, "maximum": 4096, "example": 700 }
                    },
                    {
                        "name": "zoom",
                        "in": "query",
                        "required": true,
                        "description": "Leaflet zoom level requested by the client, up to the deployment's configured portal-map maximum.",
                        "schema": { "type": "integer", "minimum": 0, "example": 8 }
                    },
                    {
                        "name": "include_extent",
                        "in": "query",
                        "required": false,
                        "description": "Include the total number and overall extent of locations matching the semantic filters. Intended for initial and filtered map loads.",
                        "schema": { "type": "boolean", "default": false }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Portal full-text search term.",
                        "schema": { "type": "string", "maxLength": 500 }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "description": "Legacy resource-type shortcut. The fixed portal scope remains authoritative, and the IGSN portal ignores resource-type filters.",
                        "schema": { "type": "string", "enum": ["doi", "igsn"] }
                    },
                    {
                        "name": "type[]",
                        "in": "query",
                        "required": false,
                        "description": "Selected resource-type slugs for the DOI portal. The IGSN portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "datacenter[]",
                        "in": "query",
                        "required": false,
                        "description": "Selected datacenter names.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "keywords[]",
                        "in": "query",
                        "required": false,
                        "description": "Legacy combined keyword filters.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "free_keywords[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact free-keyword filters.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "thesaurus_keywords[]",
                        "in": "query",
                        "required": false,
                        "description": "Selected controlled-vocabulary term identifiers for the DOI portal. The IGSN portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 2048 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "sample_types[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact sample types for the IGSN portal, combined with OR. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "materials[]",
                        "in": "query",
                        "required": false,
                        "description": "Controlled material nodes for the IGSN portal, combined with OR. Selecting a parent includes its descendants. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "classifications[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact classification values for the IGSN portal. Every selected value must be present. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "geological_ages[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact geological ages for the IGSN portal. Every selected value must be present. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "geological_units[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact geological units for the IGSN portal. Every selected value must be present. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "north",
                        "in": "query",
                        "required": false,
                        "description": "Northern latitude of the optional semantic spatial filter. Supply all four spatial filter bounds together.",
                        "schema": { "type": "number", "minimum": -90, "maximum": 90 }
                    },
                    {
                        "name": "south",
                        "in": "query",
                        "required": false,
                        "description": "Southern latitude of the optional semantic spatial filter.",
                        "schema": { "type": "number", "minimum": -90, "maximum": 90 }
                    },
                    {
                        "name": "east",
                        "in": "query",
                        "required": false,
                        "description": "Eastern longitude of the optional semantic spatial filter.",
                        "schema": { "type": "number", "minimum": -180, "maximum": 180 }
                    },
                    {
                        "name": "west",
                        "in": "query",
                        "required": false,
                        "description": "Western longitude of the optional semantic spatial filter.",
                        "schema": { "type": "number", "minimum": -180, "maximum": 180 }
                    },
                    {
                        "name": "date_type",
                        "in": "query",
                        "required": false,
                        "description": "Date field used by the optional temporal filter.",
                        "schema": { "type": "string", "enum": ["Created", "Collected", "Coverage"] }
                    },
                    {
                        "name": "year_from",
                        "in": "query",
                        "required": false,
                        "description": "Inclusive first year of the optional temporal filter.",
                        "schema": { "type": "integer", "minimum": 1900, "example": 2000 }
                    },
                    {
                        "name": "year_to",
                        "in": "query",
                        "required": false,
                        "description": "Inclusive last year of the optional temporal filter.",
                        "schema": { "type": "integer", "minimum": 1900, "example": 2026 }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Bounded map features for the requested viewport.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/PortalMapResponse" }
                            }
                        }
                    },
                    "422": {
                        "description": "One or more viewport or filter parameters are invalid.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }
                            }
                        }
                    },
                    "429": {
                        "description": "Public portal map rate limit exceeded (120 requests per minute by default).",
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds until the client may retry.",
                                "schema": { "type": "integer", "minimum": 0 }
                            },
                            "X-RateLimit-Limit": {
                                "description": "Configured request limit for the current window.",
                                "schema": { "type": "integer", "minimum": 1 }
                            },
                            "X-RateLimit-Remaining": {
                                "description": "Requests remaining in the current window.",
                                "schema": { "type": "integer", "minimum": 0 }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/MessageResponse" }
                            }
                        }
                    },
                    "500": {
                        "description": "An unexpected server error prevented map data from being generated.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/MessageResponse" }
                            }
                        }
                    },
                    "503": {
                        "description": "The portal map feature is temporarily disabled.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/MessageResponse" },
                                "example": { "message": "The portal map is temporarily unavailable." }
                            }
                        }
                    }
                }
            }
        },
        "/{portal}-search/map/clusters/{clusterId}": {
            "get": {
                "tags": ["Portal"],
                "summary": "Load the individual members of a portal map cluster",
                "description": "Resolves a server-issued cluster ID for the same technical viewport and semantic filters. Results are bounded and paginated for terminal cluster inspection.",
                "operationId": "getPortalMapClusterMembers",
                "security": [],
                "parameters": [
                    {
                        "name": "portal",
                        "in": "path",
                        "required": true,
                        "schema": { "type": "string", "enum": ["doi", "igsn"] }
                    },
                    {
                        "name": "clusterId",
                        "in": "path",
                        "required": true,
                        "schema": { "type": "string", "pattern": "^z\\d+(?:-t\\d+)?:-?\\d+:-?\\d+$", "example": "z18:140812:37114" }
                    },
                    {
                        "name": "viewport[north]",
                        "in": "query",
                        "required": true,
                        "schema": { "type": "number", "minimum": -90, "maximum": 90 }
                    },
                    {
                        "name": "viewport[south]",
                        "in": "query",
                        "required": true,
                        "schema": { "type": "number", "minimum": -90, "maximum": 90 }
                    },
                    {
                        "name": "viewport[east]",
                        "in": "query",
                        "required": true,
                        "schema": { "type": "number", "minimum": -180, "maximum": 180 }
                    },
                    {
                        "name": "viewport[west]",
                        "in": "query",
                        "required": true,
                        "schema": { "type": "number", "minimum": -180, "maximum": 180 }
                    },
                    {
                        "name": "viewport[width]",
                        "in": "query",
                        "required": true,
                        "schema": { "type": "integer", "minimum": 1, "maximum": 4096 }
                    },
                    {
                        "name": "viewport[height]",
                        "in": "query",
                        "required": true,
                        "schema": { "type": "integer", "minimum": 1, "maximum": 4096 }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": { "type": "integer", "minimum": 1, "default": 1 }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Portal full-text search term.",
                        "schema": { "type": "string", "maxLength": 500 }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "description": "Legacy resource-type shortcut. The fixed portal scope remains authoritative, and the IGSN portal ignores resource-type filters.",
                        "schema": { "type": "string", "enum": ["doi", "igsn"] }
                    },
                    {
                        "name": "type[]",
                        "in": "query",
                        "required": false,
                        "description": "Selected resource-type slugs for the DOI portal. The IGSN portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "datacenter[]",
                        "in": "query",
                        "required": false,
                        "description": "Selected datacenter names.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "keywords[]",
                        "in": "query",
                        "required": false,
                        "description": "Legacy combined keyword filters.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "free_keywords[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact free-keyword filters.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "thesaurus_keywords[]",
                        "in": "query",
                        "required": false,
                        "description": "Selected controlled-vocabulary term identifiers for the DOI portal. The IGSN portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 2048 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "sample_types[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact sample types for the IGSN portal, combined with OR. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "materials[]",
                        "in": "query",
                        "required": false,
                        "description": "Controlled material nodes for the IGSN portal, combined with OR. Selecting a parent includes its descendants. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "classifications[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact classification values for the IGSN portal. Every selected value must be present. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "geological_ages[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact geological ages for the IGSN portal. Every selected value must be present. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "geological_units[]",
                        "in": "query",
                        "required": false,
                        "description": "Exact geological units for the IGSN portal. Every selected value must be present. The DOI portal ignores this parameter.",
                        "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 } },
                        "style": "form",
                        "explode": true
                    },
                    {
                        "name": "north",
                        "in": "query",
                        "required": false,
                        "description": "Northern latitude of the optional semantic spatial filter. Supply all four spatial filter bounds together.",
                        "schema": { "type": "number", "minimum": -90, "maximum": 90 }
                    },
                    {
                        "name": "south",
                        "in": "query",
                        "required": false,
                        "description": "Southern latitude of the optional semantic spatial filter.",
                        "schema": { "type": "number", "minimum": -90, "maximum": 90 }
                    },
                    {
                        "name": "east",
                        "in": "query",
                        "required": false,
                        "description": "Eastern longitude of the optional semantic spatial filter.",
                        "schema": { "type": "number", "minimum": -180, "maximum": 180 }
                    },
                    {
                        "name": "west",
                        "in": "query",
                        "required": false,
                        "description": "Western longitude of the optional semantic spatial filter.",
                        "schema": { "type": "number", "minimum": -180, "maximum": 180 }
                    },
                    {
                        "name": "date_type",
                        "in": "query",
                        "required": false,
                        "description": "Date field used by the optional temporal filter.",
                        "schema": { "type": "string", "enum": ["Created", "Collected", "Coverage"] }
                    },
                    {
                        "name": "year_from",
                        "in": "query",
                        "required": false,
                        "description": "Inclusive first year of the optional temporal filter.",
                        "schema": { "type": "integer", "minimum": 1900, "example": 2000 }
                    },
                    {
                        "name": "year_to",
                        "in": "query",
                        "required": false,
                        "description": "Inclusive last year of the optional temporal filter.",
                        "schema": { "type": "integer", "minimum": 1900, "example": 2026 }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "A bounded page of individually hydrated cluster members.",
                        "content": {
                            "application/json": {
                                "schema": { "$ref": "#/components/schemas/PortalMapClusterMembersResponse" }
                            }
                        }
                    },
                    "404": {
                        "description": "The cluster no longer exists for the supplied viewport and filters.",
                        "content": {
                            "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } }
                        }
                    },
                    "422": {
                        "description": "The cluster ID, viewport, pagination, or filter parameters are invalid.",
                        "content": {
                            "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } }
                        }
                    },
                    "429": {
                        "description": "Public portal map rate limit exceeded.",
                        "content": {
                            "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } }
                        }
                    },
                    "503": {
                        "description": "The portal map feature is temporarily disabled.",
                        "content": {
                            "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "ElmoApiKey": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-Key",
                "description": "API key required to access ELMO-specific endpoints. Must be provided in the `X-API-Key` header. Query parameter authentication is not supported for security reasons. Contact the ERNIE team to obtain an API key."
            },
            "LaravelSession": {
                "type": "apiKey",
                "in": "cookie",
                "name": "ernie_session",
                "description": "Authenticated ERNIE browser session cookie used by web routes."
            },
            "CsrfToken": {
                "type": "apiKey",
                "in": "header",
                "name": "X-CSRF-TOKEN",
                "description": "Laravel CSRF token required for authenticated mutating web requests."
            }
        },
        "responses": {
            "UnauthorizedError": {
                "description": "Authentication failed. Either the API key is invalid/missing, or the server has no API key configured.",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "message": {
                                    "type": "string",
                                    "description": "Error message describing the authentication failure",
                                    "enum": ["Invalid API key.", "API key not configured."]
                                }
                            },
                            "required": ["message"]
                        },
                        "examples": {
                            "invalidKey": {
                                "summary": "Invalid or missing API key",
                                "value": {
                                    "message": "Invalid API key."
                                }
                            },
                            "notConfigured": {
                                "summary": "API key not configured on server",
                                "value": {
                                    "message": "API key not configured."
                                }
                            }
                        }
                    }
                }
            },
            "ForbiddenError": {
                "description": "The authenticated user is not allowed to start IGSN imports.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/MessageResponse"
                        },
                        "example": {
                            "message": "This action is unauthorized."
                        }
                    }
                }
            }
        },
        "schemas": {
            "PortalKeywordSuggestion": {
                "type": "object",
                "description": "An uncontrolled keyword used by one or more published records.",
                "properties": {
                    "value": { "type": "string", "minLength": 1, "description": "Exact keyword label." },
                    "scheme": { "type": "null", "description": "Always null because controlled-vocabulary terms are excluded." },
                    "count": { "type": "integer", "minimum": 1, "description": "Number of published records using the keyword." }
                },
                "required": ["value", "scheme", "count"],
                "additionalProperties": false
            },
            "PortalKeywordSuggestionResponse": {
                "type": "object",
                "description": "Ranked free-keyword suggestions for the public portal search.",
                "properties": {
                    "data": {
                        "type": "array",
                        "maxItems": 20,
                        "items": { "$ref": "#/components/schemas/PortalKeywordSuggestion" }
                    }
                },
                "required": ["data"],
                "additionalProperties": false
            },
            "PortalCountResponse": {
                "type": "object",
                "description": "Exact public portal result count for one normalized semantic filter combination.",
                "properties": {
                    "filter_fingerprint": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{64}$",
                        "description": "SHA-256 fingerprint of the count-relevant normalized filters."
                    },
                    "total": { "type": "integer", "minimum": 0 },
                    "last_page": { "type": "integer", "minimum": 1 },
                    "count_status": { "type": "string", "enum": ["ready"] }
                },
                "required": ["filter_fingerprint", "total", "last_page", "count_status"],
                "additionalProperties": false
            },
            "PortalResourcePreviewCitation": {
                "type": "object",
                "description": "Plain-text citation rendered in the single style supported by portal previews.",
                "properties": {
                    "styleId": { "type": "string", "enum": ["apa-7"] },
                    "label": { "type": "string", "enum": ["APA 7"] },
                    "text": { "type": "string", "minLength": 1 }
                },
                "required": ["styleId", "label", "text"],
                "additionalProperties": false
            },
            "PortalResourcePreviewResponse": {
                "type": "object",
                "description": "On-demand citation and abstract details for one scoped public portal result.",
                "properties": {
                    "resourceId": { "type": "integer", "minimum": 1 },
                    "citation": { "$ref": "#/components/schemas/PortalResourcePreviewCitation" },
                    "abstract": {
                        "type": ["string", "null"],
                        "description": "Preferred non-empty abstract, or null when none is available."
                    }
                },
                "required": ["resourceId", "citation", "abstract"],
                "additionalProperties": false
            },
            "PortalMapBounds": {
                "type": "object",
                "description": "Geographic bounds. A west value greater than east denotes an antimeridian-crossing interval.",
                "properties": {
                    "north": { "type": "number", "minimum": -90, "maximum": 90 },
                    "south": { "type": "number", "minimum": -90, "maximum": 90 },
                    "east": { "type": "number", "minimum": -180, "maximum": 180 },
                    "west": { "type": "number", "minimum": -180, "maximum": 180 }
                },
                "required": ["north", "south", "east", "west"],
                "additionalProperties": false
            },
            "PortalMapPosition": {
                "type": "object",
                "properties": {
                    "lat": { "type": "number", "minimum": -90, "maximum": 90 },
                    "lng": { "type": "number", "minimum": -180, "maximum": 180 }
                },
                "required": ["lat", "lng"],
                "additionalProperties": false
            },
            "PortalMapPoint": {
                "type": "object",
                "properties": {
                    "latitude": { "type": "number", "minimum": -90, "maximum": 90 },
                    "longitude": { "type": "number", "minimum": -180, "maximum": 180 }
                },
                "required": ["latitude", "longitude"],
                "additionalProperties": false
            },
            "PortalMapPointGeometry": {
                "type": "object",
                "properties": {
                    "type": { "type": "string", "enum": ["point"] },
                    "latitude": { "type": "number", "minimum": -90, "maximum": 90 },
                    "longitude": { "type": "number", "minimum": -180, "maximum": 180 }
                },
                "required": ["type", "latitude", "longitude"],
                "additionalProperties": false
            },
            "PortalMapBoxGeometry": {
                "type": "object",
                "properties": {
                    "type": { "type": "string", "enum": ["box"] },
                    "north": { "type": "number", "minimum": -90, "maximum": 90 },
                    "south": { "type": "number", "minimum": -90, "maximum": 90 },
                    "east": { "type": "number", "minimum": -180, "maximum": 180 },
                    "west": { "type": "number", "minimum": -180, "maximum": 180 }
                },
                "required": ["type", "north", "south", "east", "west"],
                "additionalProperties": false
            },
            "PortalMapPathGeometry": {
                "type": "object",
                "properties": {
                    "type": { "type": "string", "enum": ["polygon", "line"] },
                    "points": {
                        "type": "array",
                        "minItems": 2,
                        "items": { "$ref": "#/components/schemas/PortalMapPoint" }
                    }
                },
                "required": ["type", "points"],
                "additionalProperties": false
            },
            "PortalMapGeometry": {
                "oneOf": [
                    { "$ref": "#/components/schemas/PortalMapPointGeometry" },
                    { "$ref": "#/components/schemas/PortalMapBoxGeometry" },
                    { "$ref": "#/components/schemas/PortalMapPathGeometry" }
                ]
            },
            "PortalMapCreator": {
                "type": "object",
                "properties": {
                    "name": { "type": "string" }
                },
                "required": ["name"],
                "additionalProperties": false
            },
            "PortalMapResourceType": {
                "type": "object",
                "properties": {
                    "slug": { "type": "string" },
                    "name": { "type": "string" }
                },
                "required": ["slug", "name"],
                "additionalProperties": false
            },
            "PortalMapVisualizationDimension": {
                "type": "string",
                "enum": ["resource-type", "material"]
            },
            "PortalMapCategoryStatus": {
                "type": "string",
                "enum": ["value", "not-applicable", "missing", "unrecognized"]
            },
            "PortalMapPresentation": {
                "type": "object",
                "properties": {
                    "dimension": { "$ref": "#/components/schemas/PortalMapVisualizationDimension" },
                    "key": { "type": "string", "minLength": 1 },
                    "label": { "type": "string", "minLength": 1 },
                    "status": { "$ref": "#/components/schemas/PortalMapCategoryStatus" }
                },
                "required": ["dimension", "key", "label", "status"],
                "additionalProperties": false
            },
            "PortalMapIgsnSummary": {
                "type": "object",
                "properties": {
                    "sampleType": { "type": ["string", "null"] },
                    "material": { "type": ["string", "null"] },
                    "materialLabel": { "type": ["string", "null"] }
                },
                "required": ["sampleType", "material", "materialLabel"],
                "additionalProperties": false
            },
            "PortalMapComposition": {
                "type": "object",
                "properties": {
                    "dimension": { "$ref": "#/components/schemas/PortalMapVisualizationDimension" },
                    "counts": {
                        "type": "object",
                        "additionalProperties": { "type": "integer", "minimum": 1 }
                    }
                },
                "required": ["dimension", "counts"],
                "additionalProperties": false
            },
            "PortalMapResourceSummary": {
                "type": "object",
                "properties": {
                    "id": { "type": "integer", "minimum": 1 },
                    "identifier": { "type": ["string", "null"] },
                    "title": { "type": "string" },
                    "resourceType": {
                        "oneOf": [{ "$ref": "#/components/schemas/PortalMapResourceType" }, { "type": "null" }]
                    },
                    "presentation": { "$ref": "#/components/schemas/PortalMapPresentation" },
                    "igsn": {
                        "oneOf": [{ "$ref": "#/components/schemas/PortalMapIgsnSummary" }, { "type": "null" }]
                    },
                    "creators": {
                        "type": "array",
                        "maxItems": 3,
                        "items": { "$ref": "#/components/schemas/PortalMapCreator" }
                    },
                    "landingPageUrl": { "type": ["string", "null"] }
                },
                "required": ["id", "identifier", "title", "resourceType", "presentation", "igsn", "creators", "landingPageUrl"],
                "additionalProperties": false
            },
            "PortalMapClusterFeature": {
                "type": "object",
                "properties": {
                    "kind": { "type": "string", "enum": ["cluster"] },
                    "id": { "type": "string" },
                    "position": { "$ref": "#/components/schemas/PortalMapPosition" },
                    "bounds": { "$ref": "#/components/schemas/PortalMapBounds" },
                    "navigationBounds": { "$ref": "#/components/schemas/PortalMapBounds" },
                    "count": { "type": "integer", "minimum": 1 },
                    "resourceTypeCounts": {
                        "type": "object",
                        "additionalProperties": { "type": "integer", "minimum": 1 }
                    },
                    "composition": { "$ref": "#/components/schemas/PortalMapComposition" }
                },
                "required": ["kind", "id", "position", "bounds", "navigationBounds", "count", "resourceTypeCounts", "composition"],
                "additionalProperties": false
            },
            "PortalMapResourceFeature": {
                "type": "object",
                "properties": {
                    "kind": { "type": "string", "enum": ["resource"] },
                    "id": { "type": "string" },
                    "position": { "$ref": "#/components/schemas/PortalMapPosition" },
                    "bounds": { "$ref": "#/components/schemas/PortalMapBounds" },
                    "geometry": { "$ref": "#/components/schemas/PortalMapGeometry" },
                    "resource": { "$ref": "#/components/schemas/PortalMapResourceSummary" }
                },
                "required": ["kind", "id", "position", "bounds", "geometry", "resource"],
                "additionalProperties": false
            },
            "PortalMapFeature": {
                "oneOf": [{ "$ref": "#/components/schemas/PortalMapClusterFeature" }, { "$ref": "#/components/schemas/PortalMapResourceFeature" }]
            },
            "PortalMapMeta": {
                "type": "object",
                "properties": {
                    "requestedZoom": { "type": "integer", "minimum": 0 },
                    "effectiveZoom": { "type": "integer", "minimum": 0 },
                    "visibleLocations": { "type": "integer", "minimum": 0 },
                    "returnedFeatures": { "type": "integer", "minimum": 0 },
                    "totalLocations": { "type": ["integer", "null"], "minimum": 0 },
                    "extent": {
                        "oneOf": [{ "$ref": "#/components/schemas/PortalMapBounds" }, { "type": "null" }]
                    },
                    "coarsened": { "type": "boolean" },
                    "visualizationDimension": { "$ref": "#/components/schemas/PortalMapVisualizationDimension" }
                },
                "required": [
                    "requestedZoom",
                    "effectiveZoom",
                    "visibleLocations",
                    "returnedFeatures",
                    "totalLocations",
                    "extent",
                    "coarsened",
                    "visualizationDimension"
                ],
                "additionalProperties": false
            },
            "PortalMapResponse": {
                "type": "object",
                "properties": {
                    "schemaVersion": { "type": "integer", "enum": [3] },
                    "features": {
                        "type": "array",
                        "description": "Bounded by the deployment's PORTAL_MAP_MAX_FEATURES setting.",
                        "items": { "$ref": "#/components/schemas/PortalMapFeature" }
                    },
                    "meta": { "$ref": "#/components/schemas/PortalMapMeta" }
                },
                "required": ["schemaVersion", "features", "meta"],
                "additionalProperties": false
            },
            "PortalMapClusterMembersPagination": {
                "type": "object",
                "properties": {
                    "currentPage": { "type": "integer", "minimum": 1 },
                    "lastPage": { "type": "integer", "minimum": 1 },
                    "perPage": { "type": "integer", "minimum": 1, "maximum": 100 }
                },
                "required": ["currentPage", "lastPage", "perPage"],
                "additionalProperties": false
            },
            "PortalMapClusterMembersResponse": {
                "type": "object",
                "properties": {
                    "schemaVersion": { "type": "integer", "enum": [1] },
                    "clusterId": { "type": "string" },
                    "total": { "type": "integer", "minimum": 1 },
                    "members": {
                        "type": "array",
                        "maxItems": 100,
                        "items": { "$ref": "#/components/schemas/PortalMapResourceFeature" }
                    },
                    "pagination": { "$ref": "#/components/schemas/PortalMapClusterMembersPagination" }
                },
                "required": ["schemaVersion", "clusterId", "total", "members", "pagination"],
                "additionalProperties": false
            },
            "DatacenterIgsnImportRequest": {
                "type": "object",
                "description": "Payload for starting an IGSN import limited to one legacy datacenter.",
                "properties": {
                    "datacenter_id": {
                        "type": "string",
                        "description": "Legacy IGSN portal datacenter identifier selected from the datacenter list endpoint.",
                        "pattern": "^IGSNDB\\.[A-Z0-9_-]+$",
                        "maxLength": 100,
                        "example": "IGSNDB.ICDP"
                    }
                },
                "required": ["datacenter_id"],
                "additionalProperties": false
            },
            "LegacyIgsnDatacenter": {
                "type": "object",
                "description": "Known legacy IGSN datacenter normalized to its canonical ERNIE name.",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Stable legacy portal facet identifier.",
                        "pattern": "^IGSNDB\\.[A-Z0-9_-]+$",
                        "example": "IGSNDB.GFZ"
                    },
                    "name": {
                        "type": "string",
                        "description": "Canonical ERNIE datacenter name.",
                        "example": "GFZ German Research Centre for Geosciences"
                    },
                    "legacy_name": {
                        "type": "string",
                        "description": "Display name used by the legacy IGSN portal.",
                        "example": "GFZ Potsdam"
                    },
                    "resource_count": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Current number of IGSNs in the legacy portal facet.",
                        "example": 357
                    }
                },
                "required": ["id", "name", "legacy_name", "resource_count"],
                "additionalProperties": false
            },
            "LegacyIgsnDatacenterListResponse": {
                "type": "object",
                "description": "Legacy datacenters currently available for grouped IGSN imports.",
                "properties": {
                    "datacenters": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/LegacyIgsnDatacenter"
                        }
                    }
                },
                "required": ["datacenters"],
                "additionalProperties": false
            },
            "SingleIgsnImportRequest": {
                "type": "object",
                "description": "Payload for starting a single IGSN import from DataCite.",
                "properties": {
                    "igsn": {
                        "type": "string",
                        "description": "IGSN handle, configured-prefix DOI, or doi.org URL.",
                        "examples": ["ICDP5052EUYY001", "10.60510/GFBNO7002EHG0001", "https://doi.org/10.60510/SSDPRR02ES84601"]
                    }
                },
                "required": ["igsn"]
            },
            "IgsnImportStartResponse": {
                "type": "object",
                "description": "Response returned after an IGSN import job has been queued.",
                "properties": {
                    "import_id": {
                        "type": "string",
                        "format": "uuid",
                        "description": "Cache key suffix used to poll the import status endpoint.",
                        "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5e"
                    },
                    "message": {
                        "type": "string",
                        "example": "Single IGSN import started successfully"
                    }
                },
                "required": ["import_id", "message"]
            },
            "ValidationErrorResponse": {
                "type": "object",
                "description": "Laravel validation error response.",
                "properties": {
                    "message": {
                        "type": "string",
                        "example": "The IGSN must be a valid configured-prefix DOI or IGSN handle."
                    },
                    "errors": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        },
                        "example": {
                            "igsn": ["This IGSN could not be found at DataCite."]
                        }
                    }
                },
                "required": ["message", "errors"]
            },
            "MessageResponse": {
                "type": "object",
                "description": "Generic JSON response containing a user-facing message.",
                "properties": {
                    "message": {
                        "type": "string",
                        "example": "DataCite is currently unavailable. Please try again later."
                    }
                },
                "required": ["message"]
            },
            "ElmoResourceType": {
                "type": "object",
                "description": "A resource type configuration for ELMO editor",
                "properties": {
                    "id": {
                        "type": "integer",
                        "readOnly": true,
                        "example": 1
                    },
                    "name": {
                        "type": "string",
                        "example": "Dataset"
                    },
                    "description": {
                        "type": ["string", "null"],
                        "description": "Official DataCite description for this resource type",
                        "example": "Data encoded in a defined structure."
                    }
                },
                "required": ["id", "name"]
            },
            "Role": {
                "type": "object",
                "description": "A role that can be assigned to authors or contributors",
                "properties": {
                    "id": {
                        "type": "integer",
                        "readOnly": true,
                        "example": 1
                    },
                    "name": {
                        "type": "string",
                        "example": "Project Leader"
                    },
                    "slug": {
                        "type": "string",
                        "example": "project-leader"
                    }
                },
                "required": ["id", "name", "slug"]
            },
            "TitleType": {
                "type": "object",
                "description": "A title type for categorizing resource titles",
                "properties": {
                    "id": {
                        "type": "integer",
                        "readOnly": true,
                        "example": 1
                    },
                    "name": {
                        "type": "string",
                        "example": "Main Title"
                    },
                    "slug": {
                        "type": "string",
                        "example": "main-title"
                    }
                },
                "required": ["id", "name", "slug"]
            },
            "DateType": {
                "type": "object",
                "description": "A date type for categorizing resource dates according to DataCite schema",
                "properties": {
                    "id": {
                        "type": "integer",
                        "readOnly": true,
                        "example": 1
                    },
                    "name": {
                        "type": "string",
                        "example": "Accepted"
                    },
                    "slug": {
                        "type": "string",
                        "example": "accepted"
                    },
                    "description": {
                        "type": ["string", "null"],
                        "example": "The date that the publisher accepted the resource into their system."
                    }
                },
                "required": ["id", "name", "slug", "description"]
            },
            "DescriptionType": {
                "type": "object",
                "description": "A description type for categorizing resource descriptions according to DataCite schema 4.7",
                "properties": {
                    "id": {
                        "type": "integer",
                        "readOnly": true,
                        "example": 1
                    },
                    "name": {
                        "type": "string",
                        "example": "Abstract"
                    },
                    "slug": {
                        "type": "string",
                        "example": "Abstract"
                    }
                },
                "required": ["id", "name", "slug"]
            },
            "License": {
                "type": "object",
                "description": "A license or reusable rights statement that can be applied to research data",
                "properties": {
                    "id": {
                        "type": "integer",
                        "readOnly": true,
                        "example": 1
                    },
                    "identifier": {
                        "type": "string",
                        "description": "License/right identifier. Catalog licenses usually use SPDX identifiers; reusable custom rights use generated identifiers.",
                        "example": "CC-BY-4.0"
                    },
                    "name": {
                        "type": "string",
                        "example": "Creative Commons Attribution 4.0 International"
                    },
                    "uri": {
                        "type": ["string", "null"],
                        "format": "uri",
                        "description": "URL of the license or rights text, when known.",
                        "example": "https://creativecommons.org/licenses/by/4.0/"
                    },
                    "scheme_uri": {
                        "type": ["string", "null"],
                        "format": "uri",
                        "description": "URI of the identifier scheme, such as SPDX. Null when no scheme is available.",
                        "example": "https://spdx.org/licenses/"
                    }
                },
                "required": ["id", "identifier", "name", "uri", "scheme_uri"]
            },
            "Language": {
                "type": "object",
                "description": "A language supported for dataset metadata",
                "properties": {
                    "id": {
                        "type": "integer",
                        "readOnly": true,
                        "example": 1
                    },
                    "code": {
                        "type": "string",
                        "description": "ISO 639-1 language code",
                        "example": "en"
                    },
                    "name": {
                        "type": "string",
                        "example": "English"
                    }
                },
                "required": ["id", "code", "name"]
            },
            "GcmdScienceKeywords": {
                "type": "object",
                "description": "GCMD Science Keywords from NASA Knowledge Management System",
                "properties": {
                    "lastUpdated": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Timestamp when the vocabulary was last updated",
                        "example": "2025-10-08T11:54:31Z"
                    },
                    "data": {
                        "type": "array",
                        "description": "Hierarchical array of GCMD Science Keywords",
                        "items": {
                            "$ref": "#/components/schemas/GcmdKeywordConcept"
                        }
                    }
                }
            },
            "GcmdPlatforms": {
                "type": "object",
                "description": "GCMD Platforms from NASA Knowledge Management System",
                "properties": {
                    "lastUpdated": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Timestamp when the vocabulary was last updated",
                        "example": "2025-10-08T12:13:45Z"
                    },
                    "data": {
                        "type": "array",
                        "description": "Hierarchical array of GCMD Platforms",
                        "items": {
                            "$ref": "#/components/schemas/GcmdKeywordConcept"
                        }
                    }
                }
            },
            "GcmdInstruments": {
                "type": "object",
                "description": "GCMD Instruments from NASA Knowledge Management System",
                "properties": {
                    "lastUpdated": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Timestamp when the vocabulary was last updated",
                        "example": "2025-10-08T12:22:38Z"
                    },
                    "data": {
                        "type": "array",
                        "description": "Hierarchical array of GCMD Instruments",
                        "items": {
                            "$ref": "#/components/schemas/GcmdKeywordConcept"
                        }
                    }
                }
            },
            "MslLaboratoriesResponse": {
                "type": "object",
                "description": "Public MSL laboratories vocabulary wrapper. Internal source and Git SHA metadata are excluded.",
                "additionalProperties": false,
                "properties": {
                    "version": {
                        "type": "string",
                        "pattern": "^\\d+(?:\\.\\d+)+$",
                        "description": "Resolved stable vocabulary version",
                        "example": "1.2"
                    },
                    "lastUpdated": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Timestamp when the local vocabulary was last updated",
                        "example": "2026-07-21T12:00:00+00:00"
                    },
                    "total": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Total number of laboratories",
                        "example": 119
                    },
                    "data": {
                        "type": "array",
                        "minItems": 0,
                        "description": "Validated MSL laboratory records",
                        "items": {
                            "$ref": "#/components/schemas/MslLaboratory"
                        }
                    }
                },
                "required": ["version", "lastUpdated", "total", "data"]
            },
            "MslLaboratory": {
                "type": "object",
                "description": "A laboratory from the canonical Originating Multi-Scale Laboratories vocabulary",
                "additionalProperties": false,
                "properties": {
                    "identifier": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Stable laboratory identifier",
                        "example": "9ba34c109b827b177aab36e0266b1643"
                    },
                    "name": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Canonical laboratory name",
                        "example": "HelTec - Helmholtz Laboratory"
                    },
                    "display_name": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Unique user-facing label for search and selection",
                        "example": "HelTec - Helmholtz Laboratory — GFZ German Research Centre"
                    },
                    "affiliation_name": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Name of the affiliated institution",
                        "example": "GFZ German Research Centre"
                    },
                    "affiliation_ror": {
                        "type": ["string", "null"],
                        "format": "uri",
                        "pattern": "^https://ror\\.org/[0-9A-Za-z]{9}$",
                        "description": "ROR URL of the affiliated institution, or null when none is available",
                        "example": "https://ror.org/04z8jg394"
                    },
                    "scientific_domain": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Scientific domain of the laboratory",
                        "example": "Geosciences"
                    },
                    "country": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Country of the laboratory",
                        "example": "Germany"
                    }
                },
                "required": ["identifier", "name", "display_name", "affiliation_name", "affiliation_ror", "scientific_domain", "country"]
            },
            "ChronostratTimescale": {
                "type": "object",
                "description": "ICS Chronostratigraphic Timescale from ARDC Linked Data API (International Chronostratigraphic Chart / Geologic Time Scale 2020)",
                "properties": {
                    "lastUpdated": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Timestamp when the vocabulary was last updated",
                        "example": "2025-12-15T09:30:00Z"
                    },
                    "data": {
                        "type": "array",
                        "description": "Hierarchical array of chronostratigraphic intervals (Eons → Eras → Periods → Epochs → Ages)",
                        "items": {
                            "$ref": "#/components/schemas/GcmdKeywordConcept"
                        }
                    }
                }
            },
            "GemetThesaurus": {
                "type": "object",
                "description": "GEMET (GEneral Multilingual Environmental Thesaurus) from the EIONET REST API",
                "properties": {
                    "lastUpdated": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Timestamp when the vocabulary was last updated",
                        "example": "2026-03-12T10:00:00Z"
                    },
                    "data": {
                        "type": "array",
                        "description": "Hierarchical array of GEMET concepts (SuperGroups → Groups → Concepts)",
                        "items": {
                            "$ref": "#/components/schemas/GcmdKeywordConcept"
                        }
                    }
                }
            },
            "AnalyticalMethodsVocabulary": {
                "type": "object",
                "description": "Analytical Methods for Geochemistry and Cosmochemistry vocabulary from the ARDC Linked Data API (EarthChem/GEOROC)",
                "properties": {
                    "lastUpdated": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Timestamp when the vocabulary was last updated",
                        "example": "2026-04-15T12:00:00Z"
                    },
                    "data": {
                        "type": "array",
                        "description": "Hierarchical array of analytical method concepts with notation codes",
                        "items": {
                            "$ref": "#/components/schemas/AnalyticalMethodsConcept"
                        }
                    }
                }
            },
            "AnalyticalMethodsConcept": {
                "type": "object",
                "description": "A concept from the Analytical Methods for Geochemistry and Cosmochemistry vocabulary, extending the base keyword concept with a notation code",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uri",
                        "description": "Unique identifier (URI) for the concept",
                        "example": "https://w3id.org/geochem/1.0/analyticalmethod/massspectrometry"
                    },
                    "text": {
                        "type": "string",
                        "description": "Preferred label for the concept",
                        "example": "Atomic Absorption Spectroscopy"
                    },
                    "language": {
                        "type": "string",
                        "description": "Language code of the concept label",
                        "example": "en"
                    },
                    "scheme": {
                        "type": "string",
                        "description": "Name of the vocabulary scheme",
                        "example": "Analytical Methods for Geochemistry and Cosmochemistry"
                    },
                    "schemeURI": {
                        "type": "string",
                        "format": "uri",
                        "description": "URI of the vocabulary scheme",
                        "example": "https://w3id.org/geochem/1.0/analyticalmethod/method"
                    },
                    "notation": {
                        "type": "string",
                        "description": "Notation code for the concept (e.g. a short identifier). Always present; empty string when no notation is defined in the vocabulary.",
                        "example": "AAS"
                    },
                    "description": {
                        "type": "string",
                        "description": "Definition or description of the concept",
                        "example": "A technique used to determine the concentration of a specific metal element in a sample."
                    },
                    "children": {
                        "type": "array",
                        "description": "Child concepts in the hierarchy",
                        "items": {
                            "$ref": "#/components/schemas/AnalyticalMethodsConcept"
                        }
                    }
                },
                "required": ["id", "text", "notation", "language", "scheme", "schemeURI", "description", "children"]
            },
            "EuroSciVocVocabulary": {
                "type": "object",
                "description": "European Science Vocabulary (EuroSciVoc) from the Publications Office of the European Union",
                "required": ["lastUpdated", "data"],
                "properties": {
                    "lastUpdated": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Timestamp when the vocabulary was last updated",
                        "example": "2026-04-16T12:00:00Z"
                    },
                    "data": {
                        "type": "array",
                        "description": "Hierarchical array of EuroSciVoc concepts organized by fields of science",
                        "items": {
                            "$ref": "#/components/schemas/EuroSciVocConcept"
                        }
                    }
                }
            },
            "EuroSciVocConcept": {
                "type": "object",
                "description": "A concept from the European Science Vocabulary (EuroSciVoc), representing a field of science or research topic",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uri",
                        "description": "Unique identifier (URI) for the concept",
                        "example": "http://data.europa.eu/8mn/euroscivoc/3d76a7f4-5a16-411e-ae44-7b712d5222ee"
                    },
                    "text": {
                        "type": "string",
                        "description": "Preferred label for the concept in English",
                        "example": "natural sciences"
                    },
                    "language": {
                        "type": "string",
                        "description": "Language code of the concept label",
                        "example": "en"
                    },
                    "scheme": {
                        "type": "string",
                        "description": "Name of the vocabulary scheme",
                        "example": "European Science Vocabulary (EuroSciVoc)"
                    },
                    "schemeURI": {
                        "type": "string",
                        "format": "uri",
                        "description": "URI of the EuroSciVoc concept scheme",
                        "example": "http://data.europa.eu/8mn/euroscivoc/40c0f173-baa3-48a3-9fe6-d6e8fb366a00"
                    },
                    "description": {
                        "type": "string",
                        "description": "Description of the concept (empty string if not available)",
                        "example": ""
                    },
                    "children": {
                        "type": "array",
                        "description": "Child concepts in the hierarchy",
                        "items": {
                            "$ref": "#/components/schemas/EuroSciVocConcept"
                        }
                    }
                },
                "required": ["id", "text", "language", "scheme", "schemeURI", "description", "children"]
            },
            "CgiSimpleLithologyVocabulary": {
                "type": "object",
                "description": "Validated local representation of the official CGI Simple Lithology vocabulary",
                "required": ["schemaVersion", "lastUpdated", "total", "pathCount", "source", "data"],
                "properties": {
                    "schemaVersion": {
                        "type": "integer",
                        "example": 1
                    },
                    "lastUpdated": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Timestamp when ERNIE last downloaded and validated the vocabulary"
                    },
                    "total": {
                        "type": "integer",
                        "description": "Number of unique concepts",
                        "example": 265
                    },
                    "pathCount": {
                        "type": "integer",
                        "description": "Number of nodes after expanding every valid polyhierarchical path",
                        "example": 760
                    },
                    "source": {
                        "type": "object",
                        "required": ["provider", "endpoint", "schemeURI", "collectionURI", "sha256"],
                        "properties": {
                            "provider": { "type": "string" },
                            "endpoint": { "type": "string", "format": "uri" },
                            "schemeURI": { "type": "string", "format": "uri" },
                            "collectionURI": { "type": "string", "format": "uri" },
                            "dateModified": { "type": ["string", "null"] },
                            "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/CgiSimpleLithologyConcept"
                        }
                    }
                }
            },
            "CgiSimpleLithologyConcept": {
                "type": "object",
                "required": ["id", "text", "language", "scheme", "schemeURI", "description", "children"],
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uri",
                        "example": "http://resource.geosciml.org/classifier/cgi/lithology/basalt"
                    },
                    "text": { "type": "string", "example": "Basalt" },
                    "language": { "type": "string", "example": "en" },
                    "scheme": { "type": "string", "example": "CGI Simple Lithology" },
                    "schemeURI": {
                        "type": "string",
                        "format": "uri",
                        "example": "http://resource.geosciml.org/classifierscheme/cgi/2016.01/simplelithology"
                    },
                    "description": { "type": "string" },
                    "children": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/CgiSimpleLithologyConcept" }
                    }
                }
            },
            "GcmdKeywordConcept": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uri",
                        "description": "Unique identifier (URI) for the concept",
                        "example": "https://gcmd.earthdata.nasa.gov/kms/concept/1eb0ea0a-312c-4d74-8d42-6f1ad758f999"
                    },
                    "text": {
                        "type": "string",
                        "description": "Preferred label for the concept",
                        "example": "EARTH SCIENCE"
                    },
                    "language": {
                        "type": "string",
                        "description": "Language code of the concept label",
                        "example": "en"
                    },
                    "scheme": {
                        "type": "string",
                        "description": "Name of the vocabulary scheme",
                        "example": "NASA/GCMD Earth Science Keywords"
                    },
                    "schemeURI": {
                        "type": "string",
                        "format": "uri",
                        "description": "URI of the vocabulary scheme",
                        "example": "https://gcmd.earthdata.nasa.gov/kms/concepts/concept_scheme/sciencekeywords"
                    },
                    "description": {
                        "type": "string",
                        "description": "Definition or description of the concept",
                        "example": "any of various sciences, as geography, geology, or meteorology, that deal with the earth, its composition, or any of its changing aspects."
                    },
                    "children": {
                        "type": "array",
                        "description": "Child concepts in the hierarchy",
                        "items": {
                            "$ref": "#/components/schemas/GcmdKeywordConcept"
                        }
                    }
                },
                "required": ["id", "text", "language", "scheme", "schemeURI", "description", "children"]
            },
            "Pid4instInstruments": {
                "type": "object",
                "description": "PID4INST instruments vocabulary from b2inst (EUDAT instrument registry)",
                "properties": {
                    "lastUpdated": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Timestamp when the vocabulary was last updated",
                        "example": "2025-10-15T14:30:00Z"
                    },
                    "total": {
                        "type": "integer",
                        "description": "Total number of instruments in the vocabulary",
                        "example": 1250
                    },
                    "data": {
                        "type": "array",
                        "description": "Array of instrument records from b2inst",
                        "items": {
                            "$ref": "#/components/schemas/Pid4instInstrument"
                        }
                    }
                },
                "required": ["lastUpdated", "total", "data"]
            },
            "Pid4instInstrument": {
                "type": "object",
                "description": "A single instrument record from the b2inst PID registry. Fields are flattened from the original b2inst API response — nested objects are reduced to their name strings for simpler consumption.",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Internal b2inst record ID (string-cast)",
                        "example": "123"
                    },
                    "pid": {
                        "type": "string",
                        "description": "Persistent Identifier (Handle PID) of the instrument",
                        "example": "21.T11998/0000-001A-3905-F"
                    },
                    "pidType": {
                        "type": "string",
                        "description": "Type of the persistent identifier",
                        "example": "Handle"
                    },
                    "name": {
                        "type": "string",
                        "description": "Name or title of the instrument",
                        "example": "CTD Profiler"
                    },
                    "description": {
                        "type": "string",
                        "description": "Description of the instrument (empty string if not available)",
                        "example": "Conductivity-Temperature-Depth profiler for oceanographic measurements"
                    },
                    "landingPage": {
                        "type": "string",
                        "description": "URL to the landing page of the instrument in b2inst (empty string if not available)",
                        "example": "https://b2inst.gwdg.de/records/123"
                    },
                    "owners": {
                        "type": "array",
                        "description": "Names of organizations or persons owning the instrument",
                        "items": {
                            "type": "string",
                            "example": "GFZ Helmholtz Centre Potsdam"
                        }
                    },
                    "manufacturers": {
                        "type": "array",
                        "description": "Names of manufacturers of the instrument",
                        "items": {
                            "type": "string",
                            "example": "Sea-Bird Electronics"
                        }
                    },
                    "model": {
                        "type": ["string", "null"],
                        "description": "Model name of the instrument, or null if not available",
                        "example": "SBE 911plus"
                    },
                    "instrumentTypes": {
                        "type": "array",
                        "description": "Classification type names of the instrument",
                        "items": {
                            "type": "string",
                            "example": "CTD"
                        }
                    },
                    "measuredVariables": {
                        "type": "array",
                        "description": "Variables measured by the instrument",
                        "items": {
                            "type": "string",
                            "example": "Conductivity"
                        }
                    }
                },
                "required": ["id", "pid", "pidType", "name"]
            },
            "ThesauriAvailability": {
                "type": "object",
                "description": "Availability status of thesauri vocabularies, keyed by thesaurus type",
                "additionalProperties": {
                    "type": "object",
                    "properties": {
                        "available": {
                            "type": "boolean",
                            "description": "Whether this thesaurus is enabled",
                            "example": true
                        },
                        "displayName": {
                            "type": "string",
                            "description": "Human-readable name of the thesaurus",
                            "example": "GCMD Science Keywords"
                        }
                    },
                    "required": ["available", "displayName"]
                },
                "example": {
                    "science_keywords": {
                        "available": true,
                        "displayName": "GCMD Science Keywords"
                    },
                    "platforms": {
                        "available": true,
                        "displayName": "GCMD Platforms"
                    },
                    "instruments": {
                        "available": true,
                        "displayName": "GCMD Instruments"
                    },
                    "chronostratigraphy": {
                        "available": true,
                        "displayName": "ICS Chronostratigraphy"
                    },
                    "gemet": {
                        "available": true,
                        "displayName": "GEMET Thesaurus"
                    }
                }
            },
            "PidAvailability": {
                "type": "object",
                "description": "Availability status of PID registries, keyed by registry type",
                "additionalProperties": {
                    "type": "object",
                    "properties": {
                        "available": {
                            "type": "boolean",
                            "description": "Whether this PID registry is enabled",
                            "example": true
                        },
                        "displayName": {
                            "type": "string",
                            "description": "Human-readable name of the PID registry",
                            "example": "PID4INST (b2inst)"
                        }
                    },
                    "required": ["available", "displayName"]
                },
                "example": {
                    "pid4inst": {
                        "available": true,
                        "displayName": "PID4INST (b2inst)"
                    },
                    "ror": {
                        "available": true,
                        "displayName": "ROR (Research Organization Registry)"
                    },
                    "raid": {
                        "available": true,
                        "displayName": "RAiD (Research Activity Identifier)"
                    }
                }
            },
            "RaidProjects": {
                "type": "object",
                "description": "Public RAiD project records with metadata wrapper",
                "properties": {
                    "lastUpdated": {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp of when the data was last fetched",
                        "example": "2026-06-26T12:00:00+00:00"
                    },
                    "total": {
                        "type": "integer",
                        "description": "Total number of RAiD projects in the local dataset",
                        "example": 570
                    },
                    "data": {
                        "type": "array",
                        "description": "Array of normalized RAiD project entries",
                        "items": {
                            "$ref": "#/components/schemas/RaidProject"
                        }
                    }
                },
                "required": ["lastUpdated", "total", "data"]
            },
            "RaidProject": {
                "type": "object",
                "description": "Normalized public RAiD project record",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "10.71613/65b180be"
                    },
                    "doi": {
                        "type": "string",
                        "example": "10.71613/65b180be"
                    },
                    "raidId": {
                        "type": ["string", "null"],
                        "format": "uri",
                        "example": "https://raid.org/10.71613/65b180be"
                    },
                    "title": {
                        "type": "string",
                        "example": "Example RAiD project"
                    },
                    "description": {
                        "type": "string",
                        "example": "A public research activity."
                    },
                    "url": {
                        "type": ["string", "null"],
                        "format": "uri",
                        "example": "https://static.prod.raid.org.au/raids/10.71613/65b180be"
                    },
                    "downloadUrl": {
                        "type": ["string", "null"],
                        "format": "uri",
                        "example": "https://static.prod.raid.org.au/raids/10.71613/65b180be.download/"
                    },
                    "publicationYear": {
                        "type": ["integer", "null"],
                        "example": 2026
                    },
                    "publisher": {
                        "type": ["string", "null"],
                        "example": "Australian Research Data Commons"
                    },
                    "dates": {
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    },
                    "contributors": {
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    },
                    "organisations": {
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    },
                    "relatedIdentifiers": {
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    },
                    "subjects": {
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    },
                    "registered": {
                        "type": ["string", "null"],
                        "format": "date-time"
                    },
                    "updated": {
                        "type": ["string", "null"],
                        "format": "date-time"
                    },
                    "searchTerms": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "required": [
                    "id",
                    "doi",
                    "raidId",
                    "title",
                    "description",
                    "url",
                    "dates",
                    "contributors",
                    "organisations",
                    "relatedIdentifiers",
                    "subjects",
                    "searchTerms"
                ]
            },
            "RorAffiliations": {
                "type": "object",
                "description": "ROR affiliations data with metadata wrapper",
                "properties": {
                    "lastUpdated": {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp of when the data was last fetched",
                        "example": "2026-03-05T12:00:00+00:00"
                    },
                    "total": {
                        "type": "integer",
                        "description": "Total number of organizations in the dataset",
                        "example": 109876
                    },
                    "data": {
                        "type": "array",
                        "description": "Array of ROR organization entries",
                        "items": {
                            "type": "object",
                            "properties": {
                                "prefLabel": {
                                    "type": "string",
                                    "description": "Preferred display name of the organization",
                                    "example": "Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences"
                                },
                                "rorId": {
                                    "type": "string",
                                    "description": "ROR identifier URL",
                                    "example": "https://ror.org/04z8jg394"
                                },
                                "otherLabel": {
                                    "type": "array",
                                    "description": "Alternative names, acronyms, and search terms",
                                    "items": {
                                        "type": "string"
                                    },
                                    "example": ["GFZ", "Deutsches GeoForschungsZentrum"]
                                }
                            },
                            "required": ["prefLabel", "rorId", "otherLabel"]
                        }
                    }
                },
                "required": ["lastUpdated", "total", "data"]
            },
            "RelationType": {
                "type": "object",
                "description": "A DataCite relationType value used for Related Identifiers (e.g. Cites, IsSupplementTo)",
                "properties": {
                    "id": {
                        "type": "integer",
                        "readOnly": true,
                        "example": 1
                    },
                    "name": {
                        "type": "string",
                        "description": "Human-readable name of the relation type",
                        "example": "Cites"
                    },
                    "slug": {
                        "type": "string",
                        "description": "Machine-readable slug matching the DataCite schema value",
                        "example": "Cites"
                    }
                },
                "required": ["id", "name", "slug"]
            },
            "IdentifierType": {
                "type": "object",
                "description": "A DataCite relatedIdentifierType value (e.g. DOI, URL, Handle) with optional validation and detection regex patterns",
                "properties": {
                    "id": {
                        "type": "integer",
                        "readOnly": true,
                        "example": 1
                    },
                    "name": {
                        "type": "string",
                        "description": "Human-readable name of the identifier type",
                        "example": "DOI"
                    },
                    "slug": {
                        "type": "string",
                        "description": "Machine-readable slug matching the DataCite schema value",
                        "example": "DOI"
                    },
                    "patterns": {
                        "type": "object",
                        "description": "Grouped regex patterns for this identifier type",
                        "properties": {
                            "validation": {
                                "type": "array",
                                "description": "Regex patterns to validate whether a given string is a valid identifier of this type",
                                "items": {
                                    "$ref": "#/components/schemas/IdentifierTypePattern"
                                }
                            },
                            "detection": {
                                "type": "array",
                                "description": "Regex patterns to auto-detect this identifier type from a raw input string",
                                "items": {
                                    "$ref": "#/components/schemas/IdentifierTypePattern"
                                }
                            }
                        },
                        "required": ["validation", "detection"]
                    }
                },
                "required": ["id", "name", "slug", "patterns"]
            },
            "IdentifierTypePattern": {
                "type": "object",
                "description": "A single regex pattern for validating or detecting an identifier type",
                "properties": {
                    "pattern": {
                        "type": "string",
                        "description": "JavaScript-compatible regex pattern (without delimiters)",
                        "example": "^10\\.\\d{4,}\\/\\S+$"
                    },
                    "priority": {
                        "type": "integer",
                        "description": "Priority for ordering patterns (higher = checked first)",
                        "minimum": 0,
                        "maximum": 100,
                        "example": 10
                    }
                },
                "required": ["pattern", "priority"]
            }
        }
    }
}