About Fusion Metadata Service

Fusion Metadata Service (FMS) provides a secure way to publish SDMX structural metadata.

The main use case is where institutions wish to make SDMX structures publicly available but need a secure, read-only and scalable platform. FMS answers this requirement by providing a light-weight SDMX-compliant structure query REST API server that needs only a single static file containing the structual metadata to operate.

Note

FMS supports only structural metadata

SDMX structural metadata
SDMX reference metadata reports
SDMX data

How FMS, FMR, and Workbench Fit Together

The Fusion Metadata Registry (FMR) is a metadata management platform used to create, manage, validate, and maintain SDMX artefacts and related configuration. It provides APIs for storing and retrieving metadata content, along with administrative and operational capabilities such as user management, security configuration, integration with databases, email servers, Kafka, and other enterprise infrastructure services.

The Fusion Metadata Service (FMS) complements the FMR by providing a lightweight, high-performance dissemination layer. FMS exposes SDMX-compliant web service APIs over published metadata structure files, enabling fast, secure, and scalable public access to statistical metadata and data structures without requiring the full metadata management platform.

While FMS does not include its own user interface, the Fusion Workbench can be used as a read-only user interface layer for browsing and exploring the metadata exposed by FMS.

Deployment

FMS is a Java Spring Boot application that needs only a Java 17 or later runtime to operate. No web application server is required.

Docker

Start by assembling some SDMX structural metadata to publish into a zip file called 'structures.zip', for example

BashWindows PowerShellWindows Cmd

curl 'https://registry.sdmx.io/sdmx/v2/structure/*/*/*/*?format=fusion-json' > structures.json && zip structures.zip structures.json

curl.exe "https://registry.sdmx.io/sdmx/v2/structure/*/*/*/*?format=fusion-json" -o structures.json; if ($?) { Compress-Archive -Path structures.json -DestinationPath structures.zip }

curl "https://registry.sdmx.io/sdmx/v2/structure/*/*/*/*?format=fusion-json" -o structures.json && powershell -Command "Compress-Archive -Path structures.json -DestinationPath structures.zip"

Next, run the Fusion Metadata Service:

1. Get Docker Desktop
2. At the operating system command prompt, run:

   docker run --rm -p8080:8080 --name fms -v ./:/fms/content sdmxio/fms:latest
   

3. Browse http://localhost:8080/sdmx/v2/structure?detail=allstubs - you should an SDMX XML message listing all the structures as stubs

By default, the image uses the /fms directory for the structural metadata content, configuration and cache temporary storage:

/fmr/content/structures.zip
/fmr/config/application.yaml
/fmr/cache

Create an application.yaml as described below and mount the directory at runtime on /fms/config to apply a custom configuration. In the following example, the application.yaml is in the local config directory:

docker run --rm -p8080:8080 --name fms -v ./:/fms/content -v ./config/:/fms/config sdmxio/fms:latest

Configuring FMS

Configuration Properties

Fusion Metadata Service has one configuration file application.yaml with the following contents:

#The port the application will run on
server:
  port: 8080

app:
  #The sender ID used in the Header of SDMX messages
  sender: FMS

  #The folder the application will create temporary files in
  #cache location is from environment variable APP_CACHE_DIR if this is not supplied
  #cache location is the second property (/your/path/to/...)
  #On windows use the syntax c:/your/path/to/the/cache/folder
  cache: ${APP_CACHE_DIR:/your/path/to/the/cache/folder}

  #The public URL the server will be accessed on
  #This is used to generate the structureURL property for stub structures
  url: http://localhost:8080/FMS

  #The location on disk of the structure file to serve from the API
  #For windows machines use the syntax file:///your/path/to/the/structure/file.xml
  #The following SDMX structure files are valid
  #SDMX-ML v2.1, v3.0
  #SDMX-JSON v1.0, v2.0
  #FusionJson
  structures: /your/path/to/the/structure/file.xml

  #Set to true if the structure file does not fully load into memory, due to file size
  #hitting memory limits. When set to true, the structures will be loaded into memory when required
  #and stored in the temporary folder (off heap) on startup
  deferred: false

#Log levels are WARN, INFO, DEBUG
logging:
  level:
     root : INFO
    io.sdmx: ERROR
    io.sdmx.fms: ERROR

#Provides a health check web service
management:
  endpoint:
    health:
      probes:
        enabled: true
  endpoints:
    web:
      exposure:
        include: health

Configuration File Location

The application will look for application.yaml in the following locations:

1. From the classpath

2. The classpath root

3. The classpath /config package

4. From the current directory

5. The current directory

6. The config/ subdirectory in the current directory
7. Immediate child directories of the config/ subdirectory

The list is ordered by precedence (with values from lower items overriding earlier ones).

Features

SDMX API

The principal purpose of the FMS is to serve a fully compliant SDMX Structural Metadata API.

The FMS provides the following web service entry points:

SDMX API version	Entry Point
v1.x	[app url]/sdmx/v1/
v2.x	[app url]/sdmx/v2

Example Queries

  https://[app url]/sdmx/v1/dataflow


  https://[app url]/sdmx/v2/structure/dataflow

Health Check API

Liveness

Indicates whether the application is alive and running. If this check fails, the application should typically be restarted.

  https://[app url]/actuator/health/liveness

Readiness

Indicates whether the application is ready to accept traffic and process requests.

  https://[app url]/actuator/health/readiness

Response Example

{
"status": "UP"
}

Possible Status Values

Status	Description	Default HTTP Status
UP	Service is healthy and operational	200 OK
DOWN	Service is unavailable or unhealthy	503
OUT_OF_SERVICE	Service is running but intentionally unavailable	503
UNKNOWN	Health state could not be determined	200 OK

Launching FMS

FMS is packaged as a standalone Spring Boot application and includes an embedded Apache Tomcat server. No separate application server installation or deployment to an external Tomcat instance is required.

Two startup scripts are provided:

Script	Platform
start.sh	Linux / Unix
start.bat	Windows

Linux / Unix

Ensure the script has execute permissions:

chmod +x start.sh

Launch FMS using:

./start.sh

Windows

Launch FMS using:

start.bat

Application Startup

When the application starts successfully, the embedded Tomcat server will be initialized automatically and the FMS application will begin listening on the configured HTTP port.

Typical startup log entries include messages similar to:

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/

Spring Boot :(v4.0.2)

Tomcat initialized with port 8081 (http)
Starting service [Tomcat]
Starting Servlet engine: [Apache Tomcat/11.0.15]
Root WebApplicationContext: initialization completed in 425 ms
Exposing 1 endpoint beneath base path '/actuator'
Tomcat started on port 8081 (http) with context path '/'
Initializing Spring DispatcherServlet 'dispatcherServlet'
Initializing Servlet 'dispatcherServlet'
Completed initialization in 1 ms

Typical Startup Time

The application startup time depends on the size of the structure file to load and the CPU speed.

Testing on a Mac M3 chip with 16Gb of memory results in the following.

File Size (uncompressed)	Startup Time (s)
2.5Mb	1
180Mb	14
2.5Gb	180

Verifying the Application

Once started, the application health endpoint can be checked.