Skip to main content
Version: 13.x (Current)

Custom Service

A Custom Microservice is a service that receives HTTP requests, whose cycle of use and deploy is managed by the platform. A Custom Microservice encapsulates ad-hoc business logics that can be developed by any user of the platform. To know how manage your services in the DevOps Console see the documentation

The library exports a function which creates the infrastructure ready to accept the definition of routes and decorators.
The function optionally can take a schema of the required environment variables (you can find the reference fastify-env.


const customService = require('@mia-platform/custom-plugin-lib')({
type: 'object',
required: ['ENV_VAR'],
properties: {
ENV_VAR: { type: 'string' },

More examples? Go here to see another use cases.

You can configure the environment variables from DevOps console, in your service configuration. For further detail see Mia-Platform documentation.

The customService function expects two arguments:

  • an async function to initialize and configure the service, a Fastify instance;
  • an optional serviceOptions object useful for configuring the plugins used by the library.

You can access the environment variables values from service.config:

module.exports = customService(async function handler(service) {
const { ENV_VAR } = service.config
}, serviceOptions)

Upon service, you can you can add routes and decorators.

The serviceOptions argument supports the following properties:

  • ajv: an object useful to customize certain configurations of the ajv instance used by the service:
    • vocabulary: a list of strings used to setup a custom keyword vocabulary,
      keep in mind that if you whish to extend the OAS specification generated by your services and create a valid API specification, each vocabulary entry must start with the x- prefix, check out the OAS specification for further details;
    • plugins: allows setting up the different plugins used by the service:
      • ajv-formats (^2.1.1): with this option you can configure certain ajv-formats configurations
        • formats: a list of strings used to setup the formats that should be allowed when validating schemas

An example of service options is the following:

const serviceOptions = {
ajv: {
plugins: {
'ajv-formats': { formats: ['date-time'] },
vocabulary: ['x-name'],
module.exports = customService(async function myService(service) {
}, serviceOptions)