MIME Type Resolution Service
Introduction
Goal
Register which MIME types are acceptable for a given file extension when uploading images and assets, in one place that both the browser's upload widget and the server-side content check use.
Background
Uploading an image or asset is checked at two independent points:
- The client, in the CMS upload widget: FilePond only lets a user pick a file whose browser-reported MIME type is in its configured acceptedFileTypes list. An empty list means "accept anything"; a non-empty list that doesn't contain the file's MIME type blocks it before any request is sent to the server.
- The server, in DefaultUploadValidationService / ImageUploadValidationService: the uploaded stream's content is inspected with Apache Tika, and the detected content type must match (or be a sub-/super-type of) an allowed MIME type for that extension.
Different browsers, and different operating systems, can report different MIME types for the same extension. For example a .csv file may come in as text/csv, application/csv, or text/x-csv depending on the browser. MimeTypeResolutionService centralizes, per extension, every MIME type variant that should be treated as valid, so both gates agree on the same answer.
Registering an extension only in the legacy, deprecated extension.mimetype.allowed.mappings property (see the legacy "Allow Extra MIME Types" section of Upload Validation) does not help if the extension has no entry here — the client-side filter blocks the file first, and the server is never reached. Register the extension here instead.
Configuration
The service is backed by a Hippo repository module at:
/hippo:configuration/hippo:modules/mimetype-resolution
with its mappings under the module's hippo:moduleconfig node. Each direct child node name is a lowercase file extension without the leading dot, and its mimeTypes property (String, multi-valued) lists every MIME type variant that should be accepted for that extension:
/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 | The MIME type variants accepted for this extension's parent node name. At least one value is required for the extension to be considered configured; an extension with no matching node (or an empty mimeTypes) is treated as unknown. |
The module ships default mappings for the common image and asset extensions (jpg, jpeg, png, gif, webp, svg, bmp, ico, pdf, csv, xml, doc/docx, psd, ps, and others). Extensions outside that default set — like .kml or .log — must be added explicitly by a project's own HCM configuration; this is intentional, since the whole point of the service is that a project controls which extensions it trusts.
Finding the right MIME type
Because the value must match what the browser reports, and that can vary by browser and OS, the most reliable way to get it is to attempt the upload first and read the CMS error message, which includes the content-detected MIME type Tika found; the same technique described in the legacy "Allow Extra MIME Types" section of Upload Validation.
If different browsers used by your editors report different values for the same extension (for example Windows can report application/vnd.google-earth.kml+xml for .kml where another OS reports an empty type), list every variant you need to support in mimeTypes.
How It's Used
- Client-side accept filter — FileUploadWidgetSettings calls MimeTypeResolutionService.getMimeTypes(extension) for every extension configured as extensions.allowed on the validation service, and uses the combined result to build FilePond's acceptedFileTypes.
- Server-side content check — as of version 17.2, DefaultUploadValidationService.getAllowedMimeTypesForExtension(extension)unions this service's result with the deprecated, legacy per-validator extension.mimetype.allowed.mappings (still read for backwards compatibility), and passes the combined set 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 — the extension being "allowed" never bypasses the content check itself.
Registering an extension once, here, is sufficient for both — the legacy property only exists so old configuration keeps working; it should not be used for new mappings.
Java API
The service is registered in 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) | All known MIME types for one extension (with or without leading dot, case-insensitive). Empty set if the extension is unknown. |
| Set<String> getMimeTypes(Collection<String> extensions) | Union of known MIME types across several extensions. |
Migrating from extension.mimetype.allowed.mappings
If a project has custom entries in the legacy extension.mimetype.allowed.mappings property (on assetValidationService and/or imageValidationService), move each <extension>,<mimeType> pair into a MimeTypeResolutionService node instead:
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 is still read for backwards compatibility, but new mappings should be added here since it's the only mechanism the client-side filter reads.