Skip to content

Community Schema Extension Guide#

This document describes the currently supported features for community schema extensions in Invenio-RDM v13.

The goal is to help partners define new schema extensions for their communities.

Schema structure#

{
  "community_slug": "<community_slug>",
  "section": "Metadata for the communtiy <Community Name>",
  "fields": [
   ...
  ]
}
The slug for the community can be found in https://<fqdn>/api/communities/<community_name or community_id>.

Prefix#

The slug is used as prefix for the field. This is done to avoid duplicates amoung communitites and to implement search and filtering features. The slug is needed only in the first level variables. For the nesting object is only needed for the parent.

1. Supported Field Types#

The following field types are currently supported.

Type Description Supported field_cls Default UI Widget
text Free text value stripped, url, email Input
date Date value date DateInput
integer Whole number - NumberInput
number Decimal number - NumberInput
boolean True/False - Checkbox
vocabulary Vocabulary-backed field or enum-like dropdown enum or vocabulary_id Dropdown
nested Object containing sub-fields - MultiNestedInput

Text Variants#

Plain Text#

{
  "name": "<community_slug>:station_name",
  "type": "text",
  "field_cls": "stripped",
  "ui_widget": "Input",
  "ui_props": {
    "label": "Station Name",
    "description": "The name of the station"
  }
}

URL#

{
  "name": "<community_slug>:station_description",
  "type": "text",
  "field_cls": "url",
  "ui_widget": "Input"
}

Email#

{
  "name": "<community_slug>:contact_email",
  "type": "text",
  "field_cls": "email",
  "ui_widget": "Input"
}

2. Required Fields#

Any field can be marked as required using:

"ui_props": {
  "required": true
}

Example:

{
  "name": "<community_slug>:observed_variable",
  "type": "text",
  "field_cls": "stripped",
  "ui_props": {
    "label": "Observed Variable",
    "required": true
  }
}

3. Arrays / Multiple Values#

Arrays are supported for all primitive field types.

To define an array, use:

"multiple": true
Type Array Supported
text Yes
date Yes
integer Yes
number Yes
boolean Yes
vocabulary Yes

Example: multiple text values

{
  "name": "<community_slug>:PIDs",
  "type": "text",
  "multiple": true,
  "field_cls": "stripped",
  "ui_widget": "MultiLineInput"
}

Example: multiple numeric values

{
  "name": "<community_slug>:bounding_box",
  "type": "number",
  "multiple": true,
  "ui_widget": "NumberInput"
}

4. Nested Objects#

Nested objects are supported.

A nested object is defined using:

{
  "type": "nested",
  "properties": [ ... ]
}

Each nested field contains a list of sub-fields.

Example:

{
  "name": "<community_slug>:single_station_series_meta",
  "type": "nested",
  "multiple": false,
  "ui_widget": "MultiNestedInput",
  "ui_props": {
    "label": "Metadata For Single Station Series",
    "properties": {
      "_object_name": "metadata of resource from type SingleStationSeries"
    }
  },
  "properties": [
    {
      "name": "observed_variable",
      "type": "text",
      "field_cls": "stripped",
      "ui_props": {
        "label": "Observed Variable",
        "required": true
      }
    },
    {
      "name": "observed_variable_unit",
      "type": "text",
      "field_cls": "stripped",
      "ui_props": {
        "label": "Observed Variable Unit",
        "required": true
      }
    }
  ]
}

5. Arrays of Nested Objects#

Arrays of nested objects are partially supported.

To define an array of objects:

{
  "type": "nested",
  "multiple": true
}

Example:

{
  "name": "<community_slug>:authors",
  "type": "nested",
  "multiple": true,
  "ui_widget": "MultiNestedInput",
  "ui_props": {
    "label": "Authors",
    "properties": {
      "_object_name": "Author"
    }
  },
  "properties": [
    {
      "name": "name",
      "type": "text",
      "field_cls": "stripped"
    },
    {
      "name": "affiliation",
      "type": "text",
      "field_cls": "stripped"
    }
  ]
}

Current Status#

Feature Status
UI rendering of multiple nested objects Supported
Backend field definition Supported
Validation of nested object arrays Partially supported
Error reporting for indexed items (field.0.name) Partially supported
Faceting/filtering on nested object arrays Not fully supported

Partners should therefore use arrays of nested objects only for simple cases.

6. Supported Field Types Inside Nested Objects#

The same field types supported at the top level may also be used inside a nested object.

Field Type Inside Nested Object Supported
text Yes
date Yes
integer Yes
number Yes
boolean Yes
vocabulary Yes
multiple: true fields Yes
another nested field Partially supported

Example:

{
  "name": "<community_slug>:station_type",
  "type": "vocabulary",
  "options": [
    "background",
    "industrial",
    "traffic",
    "other"
  ],
  "ui_widget": "Dropdown"
}

7. Nested Objects Inside Nested Objects#

Nested fields inside another nested field are currently only partially supported.

Example structure:

{
  "name": "<community_slug>:outer",
  "type": "nested",
  "properties": [
    {
      "name": "inner",
      "type": "nested",
      "properties": [
        {
          "name": "value",
          "type": "text"
        }
      ]
    }
  ]
}

Current Status#

Capability Status
Schema definition Supported
Recursive backend creation Supported
UI generation Partially supported
Validation Partially supported
Search mapping and facets Not supported

Recommendation: avoid nested objects deeper than one level until full recursive support is implemented.

8. Validation Support#

The following validation features are supported.

Validator Field Types Example
length text min/max string length
regex text pattern matching
range integer, number numeric range

Example:

{
  "name": "<community_slug>:station_id",
  "type": "text",
  "validators": [
    {
      "type": "regex",
      "args": {
        "expression": "^[A-Z0-9_-]+$"
      }
    }
  ]
}

Example numeric range:

{
  "name": "<community_slug>:station_latitude",
  "type": "number",
  "validators": [
    {
      "type": "range",
      "args": {
        "min": -90,
        "max": 90
      }
    }
  ]
}

9. Filtering and Facets#

A field may be used for filtering by setting:

"use_as_filter": true

Optional custom label:

"facet_label": "Station Type"

Current Status#

Field Type Facets Supported
Top-level primitive field Yes
Top-level vocabulary field Yes
Primitive field inside nested object Partially supported
Nested object field itself No
Deeply nested field No

10. Currently Supported Example#

{
  "name": "<community_slug>:single_station_series_meta",
  "type": "nested",
  "ui_widget": "MultiNestedInput",
  "properties": [
    {
      "name": "observed_variable",
      "type": "text",
      "field_cls": "stripped",
      "ui_props": {
        "label": "Observed Variable",
        "required": true
      }
    },
    {
      "name": "type_of_data_creation",
      "type": "vocabulary",
      "options": ["measurements", "model"],
      "ui_widget": "Dropdown"
    }
  ]
}

12. Planned / Future Improvements#

The following features should be added in the future.

  1. Full support for arrays of nested objects.
  2. Recursive nested object validation.
  3. Recursive facet and search mapping generation.
  4. Conditional required fields.
  5. Better UI handling for nested arrays.
  6. Explicit support for date intervals and coordinate pairs.
  7. Better support for deeply nested structures.
  8. External vocabulary support in vocabulary object.

13. Recommended Best Practices#

Until deeper support is implemented, partners are encouraged to:

  • Prefer flat fields when possible.
  • Use at most one level of nested object.
  • Avoid nested objects inside arrays unless strictly required.
  • Avoid nested objects inside nested objects.
  • Use vocabulary with options for controlled values.
  • Use validators for all important required fields.
  • Test schema definitions with a small dataset before publishing.

  Last update : 01.04.2026

Last review : 01.04.2026