/api/v1/xmlmapping

Manage XML import/export mappings — transformations between fylr objects and external XML formats (METS/MODS, LIDO, custom profiles, ...). A mapping pairs an XML profile with field-level bindings; profiles describe the structure of the external XML.

GET /xmlmapping/list — List all profiles with the mappings built from each.

List all profiles with the mappings built from each.

get

Returns every registered profile together with the concrete mappings derived from it (the mappings sub-array). Profiles with no mappings are still included.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Responses

200

Array of profile-with-mappings descriptors.

application/json

A profile for XML / Exiftool / Dublin Core import or export — the template from which concrete XmlMappingApi mappings are derived. Profiles are loaded from xmlmapping/<profile>.yml files in the base config (and from plugins that contribute their own).

Returned by GET /api/v1/xmlmapping/profile/{profile} and embedded in each entry of GET /api/v1/xmlmapping/list (with its concrete mappings appended under mappings).

profilestringRequired

Stable profile name as stored — this is the file's profile: value and includes the source file extension, e.g. dc.yml. This exact string is the {profile} path parameter of GET /xmlmapping/profile/{profile} and the XmlMappingApi.profile value of mappings built from it.

xml_basestringOptional

Base XML namespace URL that the resulting XML documents anchor themselves to. Mostly relevant for XML export.

401

No authenticated user. The request must carry a valid access token.

application/json

[
  {
    "profile": "text",
    "displayname": {
      "de-DE": "Deutscher text",
      "en-US": "English text"
    },
    "profile_type": {
      "xml_export": true,
      "exiftool_export": true,
      "exiftool_export_omit_empty": true,
      "exiftool_import": true,
      "dc_export": true,
      "plugins_import": true
    },
    "xml_base": "text",
    "tabs": [
      {
        "tab": "text",
        "text": {
          "de-DE": "Deutscher text",
          "en-US": "English text"
        },
        "custom": true,
        "fields": [
          {
            "_id": "text",
            "name": "text",
            "strategy_import": "text",
            "type": "Output",
            "text": "text",
            "xml": "text",
            "xml_export": [
              {
                "path": "XMP-dc:Subject",
                "list": true
              }
            ],
            "xml_import": [
              {
                "search": "text",
                "l10n_prefix": "text"
              }
            ],
            "json_import": "text",
            "json_import_type": "text",
            "easydb": [
              {
                "text": "text",
                "type": "text",
                "field": "text"
              }
            ],
            "custom": true,
            "x": 1,
            "y": 1,
            "recipe_name": "text"
          }
        ]
      }
    ],
    "_compiled_recipes": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "mappings": [
      {
        "id": 1,
        "displayname": {
          "de-DE": "Deutscher text",
          "en-US": "English text"
        },
        "_recipes_required": [
          "text"
        ]
      }
    ]
  }
]

GET /xmlmapping/tags — List the metadata tags the exif-list recipe knows about.

List the metadata tags the exif-list recipe knows about.

get

Runs the recipe named by produceConfig.metadata.exif_list (default _metadata:_exif_list) and copies its output straight to the response body. The default recipe invokes fylr metadata list -, which runs exiftool -listx and converts the XML tag list to JSON — a structured list of every metadata tag exiftool understands, used by the mapping editor to autocomplete tag names.

The response is the recipe's output streamed through unmodified, so a custom recipe determines its own shape. With the default recipe the response follows the XmlMappingTagCatalog schema: each entry in tags carries path, group, writable, type and two capability flags the mapping editor uses to offer only the value-shapes the tag actually supports — l10n (the tag is a localized lang-alt) and list (the tag is a repeatable list, with list_type Bag or Seq). The two combine into four container kinds: scalar (neither), list (list), lang-alt (l10n), and list-of-lang-alt (both — e.g. XMP-plus:Custom1). Requires system.profile.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Responses

200

The recipe's JSON output, streamed through unmodified (Content-Type: application/json; charset=utf-8). With the default exif_list recipe this is the exiftool tag catalog.

application/json

The metadata tag catalog returned by GET /xmlmapping/tags with the default exif_list recipe — the JSON conversion of exiftool -f -listx, produced by fylr metadata list.

exiftool_versionstringOptional

The version of the exiftool binary that produced the catalog.

Example: 13.50

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user has neither the system.profile nor the system.root right. One of them is required for GET /tags, GET /mapping/{mapping}, PUT /mapping, POST /mapping/{mapping} and DELETE /mapping/{mapping}. (GET /list and GET /profile/{profile} require only an authenticated user — no right.) Response code is SystemRightRequired.

application/json

{
  "tags": [
    {
      "writable": true,
      "path": "XMP-plus:Custom1",
      "group": "XMP-plus",
      "description": {
        "de-DE": "Benutzerdefiniert 1",
        "en-US": "Custom 1"
      },
      "type": "lang-alt",
      "l10n": true,
      "list": true,
      "list_type": "Bag"
    }
  ],
  "xmlns": {
    "AAC": "http://ns.exiftool.ca/AAC/AAC/1.0/"
  },
  "exiftool_version": "13.50"
}

GET /xmlmapping/profile/{profile} — Retrieve a single XML profile.

Retrieve a single XML profile.

get

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Path parameters

profilestringRequired

Stable profile name exactly as returned by GET /xmlmapping/list — it includes the source file extension, e.g. dc.yml. The full list is reachable via GET /xmlmapping/list.

Responses

200

The profile descriptor.

application/json

A profile for XML / Exiftool / Dublin Core import or export — the template from which concrete XmlMappingApi mappings are derived. Profiles are loaded from xmlmapping/<profile>.yml files in the base config (and from plugins that contribute their own).

Returned by GET /api/v1/xmlmapping/profile/{profile} and embedded in each entry of GET /api/v1/xmlmapping/list (with its concrete mappings appended under mappings).

profilestringRequired

Stable profile name as stored — this is the file's profile: value and includes the source file extension, e.g. dc.yml. This exact string is the {profile} path parameter of GET /xmlmapping/profile/{profile} and the XmlMappingApi.profile value of mappings built from it.

xml_basestringOptional

Base XML namespace URL that the resulting XML documents anchor themselves to. Mostly relevant for XML export.

400

The {mapping} id (or {profile} name) in the URL does not match any stored entry. The handler returns a plain error, so the response code is ServerGeneric with status 400 — there is no 404/NotFoundError for this endpoint.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

{
  "profile": "text",
  "displayname": {
    "de-DE": "Deutscher text",
    "en-US": "English text"
  },
  "profile_type": {
    "xml_export": true,
    "exiftool_export": true,
    "exiftool_export_omit_empty": true,
    "exiftool_import": true,
    "dc_export": true,
    "plugins_import": true
  },
  "xml_base": "text",
  "tabs": [
    {
      "tab": "text",
      "text": {
        "de-DE": "Deutscher text",
        "en-US": "English text"
      },
      "custom": true,
      "fields": [
        {
          "_id": "text",
          "name": "text",
          "strategy_import": "text",
          "type": "Output",
          "text": "text",
          "xml": "text",
          "xml_export": [
            {
              "path": "XMP-dc:Subject",
              "list": true
            }
          ],
          "xml_import": [
            {
              "search": "text",
              "l10n_prefix": "text"
            }
          ],
          "json_import": "text",
          "json_import_type": "text",
          "easydb": [
            {
              "text": "text",
              "type": "text",
              "field": "text"
            }
          ],
          "custom": true,
          "x": 1,
          "y": 1,
          "recipe_name": "text"
        }
      ]
    }
  ],
  "_compiled_recipes": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "mappings": [
    {
      "id": 1,
      "displayname": {
        "de-DE": "Deutscher text",
        "en-US": "English text"
      },
      "_recipes_required": [
        "text"
      ]
    }
  ]
}

PUT /xmlmapping/mapping — Create a new mapping.

Create a new mapping.

put

The body's id is ignored on create — a fresh id is drawn from the mapping.id sequence and the row is inserted into the mapping table (plus mapping_field / mapping_field_easydb). The same handler serves POST /xmlmapping/mapping/{mapping} for updates.

Differs from easydb 5: easydb 5 stores each mapping as a JSON file in the schema folder (schema/<db>/<current>/xmlmapping-mappings/<mapping_id>.json). fylr stores mappings directly in the mapping / mapping_field / mapping_field_easydb database tables — there is no per-mapping file and no schema-folder path.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Body

application/json

A concrete XML mapping — pairs a profile with a target objecttype, the field bindings and any recipe configuration the mapping needs at runtime.

Used as the request body of PUT /api/v1/xmlmapping/mapping and POST /api/v1/xmlmapping/mapping/{mapping}, and as the response body of GET /api/v1/xmlmapping/mapping/{mapping}.

idinteger · int64Optional

Server-issued numeric id. Empty / 0 on create; required on update.

idTableinteger · int64Optional

Objecttype id this mapping targets. Required for every mapping except global / cross-objecttype ones.

profilestringRequired

Profile name (xmlmapping.Profile.profile) the mapping is built from. Must match an existing profile registered with the instance.

xml_basestringOptional

Override of the profile's xml_base namespace anchor for this mapping. Optional.

limited_extensionsstring[]Optional

Optional whitelist of file extensions (e.g. tif, jpg) this mapping should be offered for. Empty means no restriction.

custombooleanOptional

Read-only marker set when the mapping was created by a user (vs. loaded from a config file). Custom mappings are editable and deletable through the API; config-loaded ones aren't.

Responses

200

The created mapping.

application/json

A concrete XML mapping — pairs a profile with a target objecttype, the field bindings and any recipe configuration the mapping needs at runtime.

Used as the request body of PUT /api/v1/xmlmapping/mapping and POST /api/v1/xmlmapping/mapping/{mapping}, and as the response body of GET /api/v1/xmlmapping/mapping/{mapping}.

idinteger · int64Optional

Server-issued numeric id. Empty / 0 on create; required on update.

idTableinteger · int64Optional

Objecttype id this mapping targets. Required for every mapping except global / cross-objecttype ones.

profilestringRequired

Profile name (xmlmapping.Profile.profile) the mapping is built from. Must match an existing profile registered with the instance.

xml_basestringOptional

Override of the profile's xml_base namespace anchor for this mapping. Optional.

limited_extensionsstring[]Optional

Optional whitelist of file extensions (e.g. tif, jpg) this mapping should be offered for. Empty means no restriction.

custombooleanOptional

Read-only marker set when the mapping was created by a user (vs. loaded from a config file). Custom mappings are editable and deletable through the API; config-loaded ones aren't.

400

The body failed validation — for example an unknown easydb field type, a text_fixed/deep_link_url source placed among the text/custom sources, a field name that is not a valid target column, an idTable (objecttype id) that does not exist, or a recipe config that names a recipe the mapping does not use. A duplicate field name within the mapping hits the mapping_field unique index and surfaces as DatabaseUniqueKeyViolation. (An unknown profile name is accepted silently — it is not validated on save.) Returned with code ReadOnlyMode when the instance is in read-only mode — this read-only check runs first, before the right check and before the body is decoded.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user has neither the system.profile nor the system.root right. One of them is required for GET /tags, GET /mapping/{mapping}, PUT /mapping, POST /mapping/{mapping} and DELETE /mapping/{mapping}. (GET /list and GET /profile/{profile} require only an authenticated user — no right.) Response code is SystemRightRequired.

application/json

{
  "id": 1,
  "idTable": 1,
  "displayname": {
    "de-DE": "Deutscher text",
    "en-US": "English text"
  },
  "profile": "text",
  "profile_type": {
    "xml_export": true,
    "exiftool_export": true,
    "exiftool_export_omit_empty": true,
    "exiftool_import": true,
    "dc_export": true,
    "plugins_import": true
  },
  "xml_base": "text",
  "fields": [
    {
      "_id": "text",
      "name": "text",
      "strategy_import": "text",
      "type": "Output",
      "text": "text",
      "xml": "text",
      "xml_export": [
        {
          "path": "XMP-dc:Subject",
          "list": true
        }
      ],
      "xml_import": [
        {
          "search": "text",
          "l10n_prefix": "text"
        }
      ],
      "json_import": "text",
      "json_import_type": "text",
      "easydb": [
        {
          "text": "text",
          "type": "text",
          "field": "text"
        }
      ],
      "custom": true,
      "x": 1,
      "y": 1,
      "recipe_name": "text"
    }
  ],
  "limited_extensions": [
    "text"
  ],
  "recipe_configs": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "custom": true
}

GET /xmlmapping/mapping/{mapping} — Retrieve an XML mapping.

Retrieve an XML mapping.

get

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Path parameters

mappingstringRequired

The mapping's numeric id (parsed with pflib.GetInt); a non-numeric or 0 value resolves to id 0, which matches no mapping.

Responses

200

The mapping descriptor.

application/json

A concrete XML mapping — pairs a profile with a target objecttype, the field bindings and any recipe configuration the mapping needs at runtime.

Used as the request body of PUT /api/v1/xmlmapping/mapping and POST /api/v1/xmlmapping/mapping/{mapping}, and as the response body of GET /api/v1/xmlmapping/mapping/{mapping}.

idinteger · int64Optional

Server-issued numeric id. Empty / 0 on create; required on update.

idTableinteger · int64Optional

Objecttype id this mapping targets. Required for every mapping except global / cross-objecttype ones.

profilestringRequired

Profile name (xmlmapping.Profile.profile) the mapping is built from. Must match an existing profile registered with the instance.

xml_basestringOptional

Override of the profile's xml_base namespace anchor for this mapping. Optional.

limited_extensionsstring[]Optional

Optional whitelist of file extensions (e.g. tif, jpg) this mapping should be offered for. Empty means no restriction.

custombooleanOptional

Read-only marker set when the mapping was created by a user (vs. loaded from a config file). Custom mappings are editable and deletable through the API; config-loaded ones aren't.

400

The {mapping} id (or {profile} name) in the URL does not match any stored entry. The handler returns a plain error, so the response code is ServerGeneric with status 400 — there is no 404/NotFoundError for this endpoint.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user has neither the system.profile nor the system.root right. One of them is required for GET /tags, GET /mapping/{mapping}, PUT /mapping, POST /mapping/{mapping} and DELETE /mapping/{mapping}. (GET /list and GET /profile/{profile} require only an authenticated user — no right.) Response code is SystemRightRequired.

application/json

{
  "id": 1,
  "idTable": 1,
  "displayname": {
    "de-DE": "Deutscher text",
    "en-US": "English text"
  },
  "profile": "text",
  "profile_type": {
    "xml_export": true,
    "exiftool_export": true,
    "exiftool_export_omit_empty": true,
    "exiftool_import": true,
    "dc_export": true,
    "plugins_import": true
  },
  "xml_base": "text",
  "fields": [
    {
      "_id": "text",
      "name": "text",
      "strategy_import": "text",
      "type": "Output",
      "text": "text",
      "xml": "text",
      "xml_export": [
        {
          "path": "XMP-dc:Subject",
          "list": true
        }
      ],
      "xml_import": [
        {
          "search": "text",
          "l10n_prefix": "text"
        }
      ],
      "json_import": "text",
      "json_import_type": "text",
      "easydb": [
        {
          "text": "text",
          "type": "text",
          "field": "text"
        }
      ],
      "custom": true,
      "x": 1,
      "y": 1,
      "recipe_name": "text"
    }
  ],
  "limited_extensions": [
    "text"
  ],
  "recipe_configs": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "custom": true
}

POST /xmlmapping/mapping/{mapping} — Update an existing XML mapping.

Update an existing XML mapping.

post

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Path parameters

mappingstringRequired

The mapping's numeric id, written into the body's id before saving. Must be > 0, otherwise the request fails with ServerGeneric 400. An id that matches no row makes the UPDATE a no-op (no 404).

Body

application/json

A concrete XML mapping — pairs a profile with a target objecttype, the field bindings and any recipe configuration the mapping needs at runtime.

Used as the request body of PUT /api/v1/xmlmapping/mapping and POST /api/v1/xmlmapping/mapping/{mapping}, and as the response body of GET /api/v1/xmlmapping/mapping/{mapping}.

idinteger · int64Optional

Server-issued numeric id. Empty / 0 on create; required on update.

idTableinteger · int64Optional

Objecttype id this mapping targets. Required for every mapping except global / cross-objecttype ones.

profilestringRequired

Profile name (xmlmapping.Profile.profile) the mapping is built from. Must match an existing profile registered with the instance.

xml_basestringOptional

Override of the profile's xml_base namespace anchor for this mapping. Optional.

limited_extensionsstring[]Optional

Optional whitelist of file extensions (e.g. tif, jpg) this mapping should be offered for. Empty means no restriction.

custombooleanOptional

Read-only marker set when the mapping was created by a user (vs. loaded from a config file). Custom mappings are editable and deletable through the API; config-loaded ones aren't.

Responses

200

The updated mapping.

application/json

A concrete XML mapping — pairs a profile with a target objecttype, the field bindings and any recipe configuration the mapping needs at runtime.

Used as the request body of PUT /api/v1/xmlmapping/mapping and POST /api/v1/xmlmapping/mapping/{mapping}, and as the response body of GET /api/v1/xmlmapping/mapping/{mapping}.

idinteger · int64Optional

Server-issued numeric id. Empty / 0 on create; required on update.

idTableinteger · int64Optional

Objecttype id this mapping targets. Required for every mapping except global / cross-objecttype ones.

profilestringRequired

Profile name (xmlmapping.Profile.profile) the mapping is built from. Must match an existing profile registered with the instance.

xml_basestringOptional

Override of the profile's xml_base namespace anchor for this mapping. Optional.

limited_extensionsstring[]Optional

Optional whitelist of file extensions (e.g. tif, jpg) this mapping should be offered for. Empty means no restriction.

custombooleanOptional

Read-only marker set when the mapping was created by a user (vs. loaded from a config file). Custom mappings are editable and deletable through the API; config-loaded ones aren't.

400

The body failed validation — for example an unknown easydb field type, a text_fixed/deep_link_url source placed among the text/custom sources, a field name that is not a valid target column, or a recipe config that names a recipe the mapping does not use. A duplicate field name within the mapping hits the mapping_field unique index and surfaces as DatabaseUniqueKeyViolation. Returned with code ReadOnlyMode when the instance is in read-only mode — this read-only check runs first, before the right check and before the body is decoded.

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user has neither the system.profile nor the system.root right. One of them is required for GET /tags, GET /mapping/{mapping}, PUT /mapping, POST /mapping/{mapping} and DELETE /mapping/{mapping}. (GET /list and GET /profile/{profile} require only an authenticated user — no right.) Response code is SystemRightRequired.

application/json

{
  "id": 1,
  "idTable": 1,
  "displayname": {
    "de-DE": "Deutscher text",
    "en-US": "English text"
  },
  "profile": "text",
  "profile_type": {
    "xml_export": true,
    "exiftool_export": true,
    "exiftool_export_omit_empty": true,
    "exiftool_import": true,
    "dc_export": true,
    "plugins_import": true
  },
  "xml_base": "text",
  "fields": [
    {
      "_id": "text",
      "name": "text",
      "strategy_import": "text",
      "type": "Output",
      "text": "text",
      "xml": "text",
      "xml_export": [
        {
          "path": "XMP-dc:Subject",
          "list": true
        }
      ],
      "xml_import": [
        {
          "search": "text",
          "l10n_prefix": "text"
        }
      ],
      "json_import": "text",
      "json_import_type": "text",
      "easydb": [
        {
          "text": "text",
          "type": "text",
          "field": "text"
        }
      ],
      "custom": true,
      "x": 1,
      "y": 1,
      "recipe_name": "text"
    }
  ],
  "limited_extensions": [
    "text"
  ],
  "recipe_configs": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "custom": true
}

DELETE /xmlmapping/mapping/{mapping} — Delete an XML mapping.

Delete an XML mapping.

delete

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Path parameters

mappingstringRequired

The mapping's numeric id.

Query parameters

delete_policystring · enumOptional

Resolves the 202 confirmation that is returned when the mapping is still linked from one or more collections' upload settings. The only accepted value is delete, which unlinks the mapping from every affected collection (sets collection_create_object.mapping_id to NULL) and then deletes the mapping — it is a save-side-effect switch, not a no-op confirmation. Omit it on the first call to receive the 202 listing the affected collections.

Possible values:

Responses

200

The mapping was deleted (no collections linked it, or the unlink was confirmed with delete_policy=delete).

application/json

acknowledgedbooleanRequired

Always true when the mapping was deleted.

202

The mapping is still linked from one or more collections' upload settings. Re-send the same request with ?delete_policy=delete to unlink it from those collections and delete it.

application/json

400

Returned with code ReadOnlyMode when the instance is in read-only mode — this is checked before the right check and before the mapping is loaded. With code UnknownDeletePolicy when delete_policy is present but not delete. With code ServerGeneric when the {mapping} id matches no stored mapping (the loader returns a plain error — there is no 404).

application/json

401

No authenticated user. The request must carry a valid access token.

application/json

403

The authenticated user has neither the system.profile nor the system.root right. One of them is required for GET /tags, GET /mapping/{mapping}, PUT /mapping, POST /mapping/{mapping} and DELETE /mapping/{mapping}. (GET /list and GET /profile/{profile} require only an authenticated user — no right.) Response code is SystemRightRequired.

application/json

{
  "acknowledged": true
}