# plugins_api.metadata_plugins

*module*

Metadata-related plugin classes.

This module contains classes for metadata field definition and mapping.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L1-1)

## plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin

*class*

```python
class MetadataFieldDefinitionPlugin(MadbotPlugin)
```

Bases: `plugins_api.base.MadbotPlugin`

Abstract class defining the minimum API for a MetadataFieldDefinition plugin.

Metadata field definition plugins are interfaces used to import metadata fields from
external sources. They provide a consistent way to fetch, parse and integrate metadata
specifications from various standards bodies, repositories, or other external systems
into the madbot metadata fields referential. For this purpose, they define the metadata
fields, mappings between these fields and the metadata fields of the madbot referential.
Finally, they provide methods to convert values from the plugin referential to the madbot
referential and vice versa.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L22-296)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.convert_madbot_to_plugin

*method* · *abstract* · *classmethod*

```python
def convert_madbot_to_plugin(values: dict[str, Any], mapping_filter: dict[str, Any] | None = None) -> dict[str, Any]
```

Transform the values from the madbot referential to the plugin referential.

**Parameters**

- `values` (`Dict[str, Any]`) — Values keyed by madbot field slug.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`Dict[str, Any]`) — The transformed values from the madbot referential to the plugin referential.

**Examples**

Convert a full name from madbot to plugin format

```pycon
>>> print(self.convert_madbot_to_plugin({"full_name": "John Doe"}))
{"first_name": "John", "last_name": "Doe"}
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L238-266)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.convert_plugin_to_madbot

*method* · *abstract* · *classmethod*

```python
def convert_plugin_to_madbot(values: dict[str, Any], mapping_filter: dict[str, Any] | None = None) -> dict[str, Any]
```

Transform the values from the plugin referential to the madbot referential.

**Parameters**

- `values` (`Dict[str, Any]`) — Values keyed by plugin field slug.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`Dict[str, Any]`) — The transformed values from the plugin referential to the madbot referential.

**Examples**

Convert a full name from plugin to madbot format

```pycon
>>> print(self.convert_plugin_to_madbot({"first_name": "John", "last_name": "Doe"}))
{"full_name": "John Doe"}
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L268-296)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_all_mappings

*method* · *abstract* · *classmethod*

```python
def get_all_mappings(mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]
```

Get all mappings for the plugin, optionally filtered.

**Returns**

- (`List[MetadataFieldMapping]`) — List of all field mappings between both referential, optionally filtered.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L149-163)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_all_metadata_object_types

*method* · *abstract* · *classmethod*

```python
def get_all_metadata_object_types() -> dict[str, MetadataObjectType]
```

Return a dictionary of metadata object types supported by the plugin.

**Returns**

- (`Dict[str, MetadataObjectType]`) — Dictionary of metadata object types supported by the plugin, keyed by type slug.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L118-130)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_contextual_metadata_object_types

*method* · *abstract*

```python
def get_contextual_metadata_object_types() -> dict[str, MetadataObjectType]
```

Return a filtered dictionary of metadata object types supported by the plugin.

The filter is applied based on the context of the plugin. For example, for the ENA plugin,
the values returned for the contextual metadata object types include the sample metadata
object type of the selected checklist.

**Returns**

- (`dict[str, MetadataObjectType]`) — Dictionary of metadata object types supported by the plugin, filtered by the context of the plugin (e.g. the selected checklist).

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L132-147)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_madbot_field_mapping

*method* · *abstract* · *classmethod*

```python
def get_madbot_field_mapping(madbot_field: str, mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]
```

Get the mapping information for a specific field in the madbot referential.

**Parameters**

- `madbot_field` (`str`) — Madbot field slug to get the mapping for.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`List[MetadataFieldMapping]`) — List of mapping information for the specified field.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L192-213)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_metadata_fields_groups

*method* · *abstract* · *classmethod*

```python
def get_metadata_fields_groups(parent: str | None = None) -> list[MetadataGroupNodeDTO]
```

Return metadata groups for UI navigation.

Complementary to ``get_all_metadata_object_types()``: MOT methods define
what each object type contains; this method only organizes those fields
for browsing. See ``MetadataGroupNodeDTO`` for the full contract.

> **Required shape**
>
> - Recreate each MOT as a ``type="mot"`` node whose ``slug`` matches
>   ``get_all_metadata_object_types()`` (e.g. Zenodo ``"general"``).
> - Put UI folders under those MOTs as ``type="subgroup"`` children.
> - Do not mix fields from different MOTs in the same subgroup.
> - Use ``children`` (not a ``groups`` key).

> **Parent semantics**
>
> - ``parent=None``: full tree from root nodes.
> - ``parent=<slug>``: direct children of that node.
> - Unknown parent: raise ``ValueError``.

**Parameters**

- `parent` (`str`) (default: `None`) — Parent slug to expand.

**Returns**

- (`list[MetadataGroupNodeDTO]`) — Metadata group nodes.

**Examples**

One MOT with subgroups (``parent=None``):

```pycon
>>> cls.get_metadata_fields_groups(parent=None)
[
    MetadataGroupNodeDTO(
        slug="general",
        name="General",
        description="General metadata object",
        type="mot",
        has_groups=True,
        fields=[],
        children=[
            MetadataGroupNodeDTO(
                slug="core_identification",
                name="Core identification",
                description="Essential identifying information",
                type="subgroup",
                has_groups=False,
                fields=["plugin__identifier", "plugin__type"],
                children=[],
            )
        ],
    ),
]
```

Expanding that MOT:

```pycon
>>> cls.get_metadata_fields_groups(parent="general")
[
    MetadataGroupNodeDTO(
        slug="core_identification",
        name="Core identification",
        description="Essential identifying information",
        type="subgroup",
        has_groups=False,
        fields=["plugin__identifier", "plugin__type"],
        children=[],
    )
]
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L37-116)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_plugin_field_mapping

*method* · *abstract* · *classmethod*

```python
def get_plugin_field_mapping(plugin_field: str, mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]
```

Get the mapping information for a specific field in the plugin referential.

**Parameters**

- `plugin_field` (`str`) — Plugin field slug to get the mapping for.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`List[MetadataFieldMapping]`) — List of mapping information for the specified field.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L215-236)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_author

*method* · *abstract* · *classmethod*

```python
def get_author() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return plugin author.

**Returns**

- (`str`) — Plugin author.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L82-94)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_color

*method* · *abstract* · *classmethod*

```python
def get_color() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the color of the plugin.

Typically a hex value such as ``"#3B82F6"``.

**Returns**

- (`str`) — Plugin color.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L113-127)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_description

*method* · *abstract* · *classmethod*

```python
def get_description() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return plugin description.

**Returns**

- (`str`) — Plugin description.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L68-80)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_id

*method* · *classmethod*

```python
def get_id() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the unique identifier of the plugin.

**Returns**

- (`str`) — Unique identifier in the format 'module.class'.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L24-35)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_logo

*method* · *abstract* · *classmethod*

```python
def get_logo() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the static path of the plugin logo.

Path is relative to the plugin package static files.
Example: ``"images/ena.png"``.

**Returns**

- (`str`) — Plugin logo static path.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L96-111)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_name

*method* · *abstract* · *classmethod*

```python
def get_name() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the plugin name.

**Returns**

- (`str`) — Plugin name.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L37-49)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_slug

*method* · *abstract* · *classmethod*

```python
def get_slug() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the plugin slug.

Lowercase, no spaces (e.g. ``"ena"``, ``"omero"``).
Used as ``MetadataFieldID.source`` and as the schema source at reload.

**Returns**

- (`str`) — Plugin slug.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L51-66)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_status

*method* · *abstract* · *classmethod*

```python
def get_status() -> dict[str, PluginStatus]
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the maturity status of the plugin, keyed by capability type.

A plugin implementing several capability types at once (e.g. a class
inheriting from both `SubmissionPlugin` and
`MetadataFieldDefinitionPlugin`) must return one entry per type it
implements, using the same type strings as `get_types()`.

**Returns**

- (`dict[str, PluginStatus]`) — Mapping of plugin type (as returned by `get_types()`) to its maturity status.

**Examples**

A plugin implementing a single type:

```pycon
>>> print(self.get_status())
{"data_plugin": PluginStatus.PREVIEW}
```

A plugin implementing several types at once:

```pycon
>>> print(self.get_status())
{
    "submission_plugin": PluginStatus.STABLE,
    "metadata_field_definition_plugin": PluginStatus.STABLE,
}
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L129-162)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin.get_types

*method* · *classmethod*

```python
def get_types() -> list[str]
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the list of the plugin types in snake_case.

**Returns**

- (`list`) — List of plugin types.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L164-181)

## plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping

*class*

```python
class MetadataFieldDefinitionPluginWithStandardMapping(MetadataFieldDefinitionPlugin)
```

Bases: `plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin`

Abstract class defining the minimum API for a MetadataFieldDefinition plugin, while implementing a standard mapping system.

Metadata field definition plugins are interfaces used to import metadata fields from
external sources. They provide a consistent way to fetch, parse and integrate metadata
specifications from various standards bodies, repositories, or other external systems
into the Madbot metadata fields referential.

This class implements a standard mapping system, which allows to define a mapping between
the metadata fields of the plugin and the metadata fields of the Madbot referential.

The mapping is defined by the user, by calling the `set_mapper` method or setting the
`mapper` attribute.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L774-1025)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.mapper

*attribute* · *class attribute* · *instance attribute*

```python
mapper: StandardMetadataMapper | None = None
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L792-792)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.convert_madbot_to_plugin

*method* · *classmethod*

```python
def convert_madbot_to_plugin(values: dict[str, Any], mapping_filter: dict[str, Any] | None = None) -> dict[str, Any]
```

Transform the values from the madbot referential to the plugin referential.

This method delegates to the mapper if one is set, otherwise raises NotImplementedError.

**Parameters**

- `values` (`Dict[str, Any]`) — Values keyed by madbot field slug.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`Dict[str, Any]`) — The transformed values from the madbot referential to the plugin referential.

**Raises**

- `NotImplementedError` — If no mapper is set.

**Examples**

Convert a full name from madbot to plugin format

```pycon
>>> print(self.convert_madbot_to_plugin({"full_name": "John Doe"}))
{"first_name": "John", "last_name": "Doe"}
```

Convert multiple fields

```pycon
>>> print(self.convert_madbot_to_plugin({"title": "Hello World", "description": "A test"}))
{"name": "HELLO WORLD", "desc": "A test"}
```

Convert with specific checklist filter

```pycon
>>> print(self.convert_madbot_to_plugin({"name": "Sample123"}, mapping_filter={"mapping_id": "erc000010"}))
{"sample_name": "Sample123"}
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L931-977)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.convert_plugin_to_madbot

*method* · *classmethod*

```python
def convert_plugin_to_madbot(values: dict[str, Any], mapping_filter: dict[str, Any] | None = None) -> dict[str, Any]
```

Transform the values from the plugin referential to the madbot referential.

This method delegates to the mapper if one is set, otherwise raises NotImplementedError.

**Parameters**

- `values` (`Dict[str, Any]`) — Values keyed by plugin field slug.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`Dict[str, Any]`) — The transformed values from the plugin referential to the madbot referential.

**Raises**

- `NotImplementedError` — If no mapper is set.

**Examples**

Convert a full name from plugin to madbot format

```pycon
>>> print(self.convert_plugin_to_madbot({"first_name": "John", "last_name": "Doe"}))
{"full_name": "John Doe"}
```

Convert multiple fields

```pycon
>>> print(self.convert_plugin_to_madbot({"name": "Hello World", "desc": "A test"}))
{"title": "HELLO WORLD", "description": "A test"}
```

Convert with specific checklist filter

```pycon
>>> print(self.convert_plugin_to_madbot({"sample_name": "Sample123"}, mapping_filter={"mapping_id": "erc000010"}))
{"name": "Sample123"}
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L979-1025)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_all_mappings

*method* · *classmethod*

```python
def get_all_mappings(mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]
```

Get all mappings for the plugin, optionally filtered.

This method delegates to the mapper if one is set, otherwise raises NotImplementedError.

**Parameters**

- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`List[MetadataFieldMapping]`) — List of all field mappings between both referential, optionally filtered.

**Raises**

- `NotImplementedError` — If no mapper is set.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L809-836)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_madbot_field_mapping

*method* · *classmethod*

```python
def get_madbot_field_mapping(madbot_field: str, mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]
```

Get the mapping information for a specific field in the madbot referential.

**Parameters**

- `madbot_field` (`str`) — Field slug to get the mapping for.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`List[MetadataFieldMapping]`) — List of mapping information for the specified field.

**Raises**

- `NotImplementedError` — If no mapper is set.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L873-900)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_plugin_field_mapping

*method* · *classmethod*

```python
def get_plugin_field_mapping(plugin_field: str, mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]
```

Get the mapping information for a specific field in the plugin referential.

**Parameters**

- `plugin_field` (`str`) — Field slug to get the mapping for.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`List[MetadataFieldMapping]`) — List of mapping information for the specified field.

**Raises**

- `NotImplementedError` — If no mapper is set.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L902-929)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.set_mapper

*method* · *classmethod*

```python
def set_mapper(mapper: StandardMetadataMapper) -> None
```

Set the mapper for this plugin class.

This method sets the mapper that will be used by all instances of this class.

**Parameters**

- `mapper` (`StandardMetadataMapper`) — The mapper to use for field transformations.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L794-807)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_all_metadata_object_types

*method* · *abstract* · *classmethod*

```python
def get_all_metadata_object_types() -> dict[str, MetadataObjectType]
```

Inherited from: `plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin`

Return a dictionary of metadata object types supported by the plugin.

**Returns**

- (`Dict[str, MetadataObjectType]`) — Dictionary of metadata object types supported by the plugin, keyed by type slug.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L118-130)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_contextual_metadata_object_types

*method* · *abstract*

```python
def get_contextual_metadata_object_types() -> dict[str, MetadataObjectType]
```

Inherited from: `plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin`

Return a filtered dictionary of metadata object types supported by the plugin.

The filter is applied based on the context of the plugin. For example, for the ENA plugin,
the values returned for the contextual metadata object types include the sample metadata
object type of the selected checklist.

**Returns**

- (`dict[str, MetadataObjectType]`) — Dictionary of metadata object types supported by the plugin, filtered by the context of the plugin (e.g. the selected checklist).

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L132-147)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_metadata_fields_groups

*method* · *abstract* · *classmethod*

```python
def get_metadata_fields_groups(parent: str | None = None) -> list[MetadataGroupNodeDTO]
```

Inherited from: `plugins_api.metadata_plugins.MetadataFieldDefinitionPlugin`

Return metadata groups for UI navigation.

Complementary to ``get_all_metadata_object_types()``: MOT methods define
what each object type contains; this method only organizes those fields
for browsing. See ``MetadataGroupNodeDTO`` for the full contract.

> **Required shape**
>
> - Recreate each MOT as a ``type="mot"`` node whose ``slug`` matches
>   ``get_all_metadata_object_types()`` (e.g. Zenodo ``"general"``).
> - Put UI folders under those MOTs as ``type="subgroup"`` children.
> - Do not mix fields from different MOTs in the same subgroup.
> - Use ``children`` (not a ``groups`` key).

> **Parent semantics**
>
> - ``parent=None``: full tree from root nodes.
> - ``parent=<slug>``: direct children of that node.
> - Unknown parent: raise ``ValueError``.

**Parameters**

- `parent` (`str`) (default: `None`) — Parent slug to expand.

**Returns**

- (`list[MetadataGroupNodeDTO]`) — Metadata group nodes.

**Examples**

One MOT with subgroups (``parent=None``):

```pycon
>>> cls.get_metadata_fields_groups(parent=None)
[
    MetadataGroupNodeDTO(
        slug="general",
        name="General",
        description="General metadata object",
        type="mot",
        has_groups=True,
        fields=[],
        children=[
            MetadataGroupNodeDTO(
                slug="core_identification",
                name="Core identification",
                description="Essential identifying information",
                type="subgroup",
                has_groups=False,
                fields=["plugin__identifier", "plugin__type"],
                children=[],
            )
        ],
    ),
]
```

Expanding that MOT:

```pycon
>>> cls.get_metadata_fields_groups(parent="general")
[
    MetadataGroupNodeDTO(
        slug="core_identification",
        name="Core identification",
        description="Essential identifying information",
        type="subgroup",
        has_groups=False,
        fields=["plugin__identifier", "plugin__type"],
        children=[],
    )
]
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L37-116)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_author

*method* · *abstract* · *classmethod*

```python
def get_author() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return plugin author.

**Returns**

- (`str`) — Plugin author.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L82-94)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_color

*method* · *abstract* · *classmethod*

```python
def get_color() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the color of the plugin.

Typically a hex value such as ``"#3B82F6"``.

**Returns**

- (`str`) — Plugin color.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L113-127)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_description

*method* · *abstract* · *classmethod*

```python
def get_description() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return plugin description.

**Returns**

- (`str`) — Plugin description.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L68-80)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_id

*method* · *classmethod*

```python
def get_id() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the unique identifier of the plugin.

**Returns**

- (`str`) — Unique identifier in the format 'module.class'.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L24-35)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_logo

*method* · *abstract* · *classmethod*

```python
def get_logo() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the static path of the plugin logo.

Path is relative to the plugin package static files.
Example: ``"images/ena.png"``.

**Returns**

- (`str`) — Plugin logo static path.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L96-111)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_name

*method* · *abstract* · *classmethod*

```python
def get_name() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the plugin name.

**Returns**

- (`str`) — Plugin name.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L37-49)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_slug

*method* · *abstract* · *classmethod*

```python
def get_slug() -> str
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the plugin slug.

Lowercase, no spaces (e.g. ``"ena"``, ``"omero"``).
Used as ``MetadataFieldID.source`` and as the schema source at reload.

**Returns**

- (`str`) — Plugin slug.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L51-66)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_status

*method* · *abstract* · *classmethod*

```python
def get_status() -> dict[str, PluginStatus]
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the maturity status of the plugin, keyed by capability type.

A plugin implementing several capability types at once (e.g. a class
inheriting from both `SubmissionPlugin` and
`MetadataFieldDefinitionPlugin`) must return one entry per type it
implements, using the same type strings as `get_types()`.

**Returns**

- (`dict[str, PluginStatus]`) — Mapping of plugin type (as returned by `get_types()`) to its maturity status.

**Examples**

A plugin implementing a single type:

```pycon
>>> print(self.get_status())
{"data_plugin": PluginStatus.PREVIEW}
```

A plugin implementing several types at once:

```pycon
>>> print(self.get_status())
{
    "submission_plugin": PluginStatus.STABLE,
    "metadata_field_definition_plugin": PluginStatus.STABLE,
}
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L129-162)

### plugins_api.metadata_plugins.MetadataFieldDefinitionPluginWithStandardMapping.get_types

*method* · *classmethod*

```python
def get_types() -> list[str]
```

Inherited from: `plugins_api.base.MadbotPlugin`

Return the list of the plugin types in snake_case.

**Returns**

- (`list`) — List of plugin types.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/base.py#L164-181)

## plugins_api.metadata_plugins.StandardMetadataMapper

*class*

```python
class StandardMetadataMapper
```

Class representing bidirectional mapping between plugin fields and madbot fields.

This class manages the mapping and transformation of fields between a plugin's referential
and the madbot referential. It follows RDF-like concepts where:
- Plugin fields are considered "subjects" in plugin->madbot direction
- Madbot fields are considered "objects" in plugin->madbot direction
- The transformation functions act as "predicates" defining the relationship

This class definition can be enhanced to support the specification of SSSOM mappings.
For more information on SSSOM, see https://mapping-commons.github.io/sssom/

**Attributes**

- `_plugin_to_madbot` (`Dict[str, List[MetadataFieldMapping]]`) — Internal dictionary mapping plugin fields to lists of MetadataFieldMapping instances
- `_madbot_to_plugin` (`Dict[str, List[MetadataFieldMapping]]`) — Internal dictionary mapping madbot fields to lists of MetadataFieldMapping instances

**Examples**

Create a new StandardMetadataMapper instance

```pycon
>>> mapper = StandardMetadataMapper()
```

Simple one-to-one mapping

```pycon
>>> mapper.add_mapping(
...     plugin_fields="title",
...     madbot_fields="name",
...     transform_plugin_to_madbot=lambda x: {"name": x["title"].upper()},
...     transform_madbot_to_plugin=lambda x: {"title": x["name"].lower()}
... )
```

Many-to-one mapping

```pycon
>>> mapper.add_mapping(
...     plugin_fields=["first_name", "last_name"],
...     madbot_fields="full_name",
...     transform_plugin_to_madbot=lambda x: {
...         "full_name": f"{x['first_name']} {x['last_name']}"
...     },
...     transform_madbot_to_plugin=lambda x: {
...         "first_name": x["full_name"].split()[0],
...         "last_name": x["full_name"].split()[1]
...     }
... )
```

Multiple mapping rules for the same field (e.g., different ENA checklists)

```pycon
>>> mapper.add_mapping(
...     plugin_fields="sample_name",
...     madbot_fields="name",
...     transform_plugin_to_madbot=lambda x: {"name": x["sample_name"]},
...     transform_madbot_to_plugin=lambda x: {"sample_name": x["name"]},
...     mapping_id="erc000010"  # Specific checklist
... )
```

```pycon
>>> mapper.add_mapping(
...     plugin_fields="sample_name",
...     madbot_fields="name",
...     transform_plugin_to_madbot=lambda x: {"name": f"ENA_{x['sample_name']}"},
...     transform_madbot_to_plugin=lambda x: {"sample_name": x["name"].replace("ENA_", "")},
...     mapping_id="erc000028"  # Different checklist
... )
```

Convert plugin to madbot with filtering

```pycon
>>> print(mapper.convert_plugin_to_madbot({"title": "Hello World"}, mapping_filter={"mapping_id": "erc000010"}))
{"name": "HELLO WORLD"}
```

Convert madbot to plugin with filtering

```pycon
>>> print(mapper.convert_madbot_to_plugin({"name": "HELLO WORLD"}, mapping_filter={"mapping_id": "erc000010"}))
{"title": "hello world"}
```

```pycon
>>> print(mapper.get_plugin_field_mapping(plugin_field="first_name", mapping_filter={"mapping_id": "erc000010"}))
MetadataFieldMapping(
    plugin_fields=["first_name", "last_name"],
    madbot_fields=["full_name"],
    transform_madbot_to_plugin=<function>,
    transform_plugin_to_madbot=<function>,
)
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L299-771)

### plugins_api.metadata_plugins.StandardMetadataMapper.add_mapping

*method*

```python
def add_mapping(plugin_fields: str | list[str], madbot_fields: str | list[str], transform_plugin_to_madbot: Callable[[dict[str, Any]], dict[str, Any]] = lambda x: x, transform_madbot_to_plugin: Callable[[dict[str, Any]], dict[str, Any]] = lambda x: x, mapping_id: str | None = None, **kwargs) -> None
```

Add a bidirectional mapping between plugin and madbot fields.

This method creates a new MetadataFieldMapping instance and stores it in both the plugin->madbot
and madbot->plugin mapping dictionaries. Multiple mappings can be added for the same field,
distinguished by the mapping_id and additional kwargs.

**Parameters**

- `plugin_fields` (`Union[str, List[str]]`) — Plugin field slug, or list of slugs.
- `madbot_fields` (`Union[str, List[str]]`) — Madbot field slug, or list of slugs.
- `transform_plugin_to_madbot` (`Callable`) (default: `lambda x: x`) — Function to transform values from plugin to madbot format. Should accept a dict of plugin field values and return a dict of madbot field values. By default, returns the input unchanged.
- `transform_madbot_to_plugin` (`Callable`) (default: `lambda x: x`) — Function to transform values from madbot to plugin format. Should accept a dict of madbot field values and return a dict of plugin field values. By default, returns the input unchanged.
- `mapping_id` (`Optional[str]`) (default: `None`) — Unique identifier for this mapping rule. Useful for distinguishing between multiple mappings for the same field (e.g., different checklists).
- `**kwargs` (`Any`) (default: `{}`) — Additional metadata for the mapping (e.g., checklist, version, etc.)

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L393-462)

### plugins_api.metadata_plugins.StandardMetadataMapper.convert_madbot_to_plugin

*method*

```python
def convert_madbot_to_plugin(values: dict[str, Any], mapping_filter: dict[str, Any] | None = None) -> dict[str, Any]
```

Convert values from madbot referential to plugin referential.

This method handles the conversion of one or more fields from the madbot referential
to the plugin referential. The input values should be a dictionary where keys are
madbot field slugs and values are the corresponding values to convert.

**Parameters**

- `values` (`Dict[str, Any]`) — Dictionary of madbot field slugs to their values. All fields must belong to the same mapping group (e.g., if converting a full name, both first_name and last_name must be provided).
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`Dict[str, Any]`) — Dictionary of plugin field slugs to their converted values.

**Raises**

- `ValueError` — If the fields don't belong to the same mapping group or if any field is not found.

**Examples**

Convert a full name from madbot to plugin format

```pycon
>>> print(mapper.convert_madbot_to_plugin({"full_name": "John Doe"}))
{"first_name": "John", "last_name": "Doe"}
```

Convert multiple fields

```pycon
>>> print(mapper.convert_madbot_to_plugin({"title": "Hello World", "description": "A test"}))
{"name": "HELLO WORLD", "desc": "A test"}
```

Convert with specific checklist filter

```pycon
>>> print(mapper.convert_madbot_to_plugin({"name": "Sample123"}, mapping_filter={"mapping_id": "erc000010"}))
{"sample_name": "Sample123"}
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L617-693)

### plugins_api.metadata_plugins.StandardMetadataMapper.convert_plugin_to_madbot

*method*

```python
def convert_plugin_to_madbot(values: dict[str, Any], mapping_filter: dict[str, Any] | None = None) -> dict[str, Any]
```

Convert values from plugin referential to madbot referential.

This method handles the conversion of one or more fields from the plugin referential
to the madbot referential. The input values should be a dictionary where keys are
plugin field slugs and values are the corresponding values to convert.

**Parameters**

- `values` (`Dict[str, Any]`) — Dictionary of plugin field slugs to their values. All fields must belong to the same mapping group (e.g., if converting a full name, both first_name and last_name must be provided).
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`Dict[str, Any]`) — Dictionary of madbot field slugs to their converted values.

**Raises**

- `ValueError` — If the fields don't belong to the same mapping group or if any field is not found.

**Examples**

Convert a full name from plugin to madbot format

```pycon
>>> print(mapper.convert_plugin_to_madbot({"first_name": "John", "last_name": "Doe"}))
{"full_name": "John Doe"}
```

Convert multiple fields

```pycon
>>> print(mapper.convert_plugin_to_madbot({"name": "Hello World", "desc": "A test"}))
{"title": "HELLO WORLD", "description": "A test"}
```

Convert with specific checklist filter

```pycon
>>> print(mapper.convert_plugin_to_madbot({"sample_name": "Sample123"}, mapping_filter={"mapping_id": "erc000010"}))
{"name": "Sample123"}
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L695-771)

### plugins_api.metadata_plugins.StandardMetadataMapper.get_all_mappings

*method*

```python
def get_all_mappings(mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]
```

Get all mappings for the plugin, optionally filtered.

**Parameters**

- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`List[MetadataFieldMapping]`) — List of all field mappings between both referential, optionally filtered.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L506-527)

### plugins_api.metadata_plugins.StandardMetadataMapper.get_madbot_field_mapping

*method*

```python
def get_madbot_field_mapping(madbot_field: str, mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]
```

Get the mapping information for a specific field in the madbot referential.

**Parameters**

- `madbot_field` (`str`) — Madbot field slug to get the mapping for.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`List[MetadataFieldMapping]`) — List of mapping information for the specified field.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L572-593)

### plugins_api.metadata_plugins.StandardMetadataMapper.get_plugin_field_mapping

*method*

```python
def get_plugin_field_mapping(plugin_field: str, mapping_filter: dict[str, Any] | None = None) -> list[MetadataFieldMapping]
```

Get the mapping information for a specific field in the plugin referential.

**Parameters**

- `plugin_field` (`str`) — Plugin field slug to get the mapping for.
- `mapping_filter` (`Optional[Dict[str, Any]]`) (default: `None`) — Dictionary of filter criteria. Keys should match attributes of MetadataFieldMapping.

**Returns**

- (`    List[MetadataFieldMapping]: List of mapping information for the specified field.`)

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/3aa4c278bf4620ccd23a16eb233b035646016bd2/plugin_api/plugins_api/metadata_plugins.py#L595-615)
