MIME Type Resolution Service

Info: Available in brXM 16.9.0 and later.

Overview

The MIME Type Resolution Service centralizes the configuration of acceptable MIME types for each file extension used when uploading images and assets. Both the browser upload widget and the server-side validation reference this configuration to ensure consistent file acceptance.

Purpose

Define which MIME types are valid for each file extension in a single location.
Ensure both client-side (browser) and server-side (repository) checks use the same MIME type rules during file uploads.

Background

File uploads are validated at two points:

Client-side (CMS upload widget):
The FilePond widget allows users to select files only if the browser-reported MIME type matches an entry in the acceptedFileTypes list.
- If the list is empty, all files are accepted.
- If the file's MIME type is not listed, the upload is blocked before reaching the server.
Server-side (DefaultUploadValidationService / ImageUploadValidationService):
The server inspects the uploaded file using Apache Tika. The detected MIME type must match, or be a sub-/super-type of, an allowed MIME type for the file extension.

Browser and operating system differences can cause the same file extension to be reported with different MIME types. For example, .csv files may appear as text/csv, application/csv, or text/x-csv. The MimeTypeResolutionService allows you to register all valid MIME type variants for each extension, ensuring both client and server validation are aligned.

Note: Registering an extension only in the legacy extension.mimetype.allowed.mappings property does not affect the client-side filter. If the extension is not configured in the MIME Type Resolution Service, the client will block the file before it reaches the server. Always register extensions here for consistent validation.

Configuration

The MIME Type Resolution Service is configured in the repository at:

/hippo:configuration/hippo:modules/mimetype-resolution

Mappings are defined under the module's hippo:moduleconfig node. Each direct child node represents a file extension (lowercase, without the leading dot). The mimeTypes property (multi-valued string) lists all MIME type variants accepted for that extension.

Example configuration:

/hippo:moduleconfig
  /jpg
    mimeTypes: [image/jpeg, image/pjpeg]
  /png
    mimeTypes: [image/png]
  /csv
    mimeTypes: [text/csv, application/csv, text/x-csv]

Property	Type	Description
`mimeTypes`	String multiple	Lists all accepted MIME type variants for the extension. At least one value is required. If missing or empty, the extension is unknown.

The module provides default mappings for common image and asset extensions (such as jpg, jpeg, png, gif, webp, svg, bmp, ico, pdf, csv, xml, doc/docx, psd, ps, and others). To support additional extensions (for example, .kml or .log), add them explicitly in your project's HCM configuration. This ensures that only trusted extensions are allowed.

Determining the Correct MIME Type

Browser-reported MIME types can vary by browser and operating system. To determine the correct value:

Attempt to upload the file in the CMS.
Review the error message, which displays the MIME type detected by Tika.
Add all MIME type variants needed for your use case to the mimeTypes property.

If editors use different browsers or operating systems that report different MIME types for the same extension, include every required variant in the configuration.

Usage

Client-side filtering:
FileUploadWidgetSettings calls MimeTypeResolutionService.getMimeTypes(extension) for each extension listed in extensions.allowed on the validation service. The combined result is used to set FilePond's acceptedFileTypes property.
Server-side validation:
Starting with version 17.2, DefaultUploadValidationService.getAllowedMimeTypesForExtension(extension) merges the MIME types from this service with those from the deprecated extension.mimetype.allowed.mappings property (for backward compatibility). The combined set is passed to the Tika-based MimeTypeValidator.
A file is accepted if its detected content type matches, or is a registered sub-/super-type of, any allowed MIME type. Allowing an extension does not bypass content validation.

Registering an extension in the MIME Type Resolution Service is sufficient for both client and server validation. The legacy property is maintained only for backward compatibility and should not be used for new mappings.

Java API

The service is available through the Hippo Service Registry:

import com.bloomreach.cms.services.mimetyperesolution.MimeTypeResolutionService;
import org.onehippo.cms7.services.HippoServiceRegistry;

MimeTypeResolutionService service = HippoServiceRegistry.getService(MimeTypeResolutionService.class);
Set<String> mimeTypes = service.getMimeTypes("kml");
// -> [application/vnd.google-earth.kml+xml], or empty if unconfigured

Method	Description
`Set<String> getMimeTypes(String extension)`	Returns all known MIME types for the specified extension (with or without leading dot, case-insensitive). Returns an empty set if the extension is unknown.
`Set<String> getMimeTypes(Collection<String> extensions)`	Returns the union of known MIME types for the provided extensions.

Migrating from extension.mimetype.allowed.mappings

To migrate custom entries from the legacy extension.mimetype.allowed.mappings property (on assetValidationService or imageValidationService), move each <extension>,<mimeType> pair to a node in the MimeTypeResolutionService configuration.

For example:

Legacy property:

extension.mimetype.allowed.mappings: ['.aac,audio/x-aac']

Becomes:

/hippo:configuration/hippo:modules/mimetype-resolution/hippo:moduleconfig:
  /aac:
    jcr:primaryType: hipposys:moduleconfig
    mimeTypes:
      - audio/x-aac

The legacy property remains for backward compatibility, but new mappings must be added to the MIME Type Resolution Service. This is the only configuration used by the client-side filter.