Module Definition File

Note

This document has been machine translated.

Module Definition File Overview

A module definition file specifies the scripts (processes) and data structures that a module provides, thereby declaring the module’s interface specification.
It is created in JSON format and stored within the module as definition.json.
xData FL retrieves definition.json to understand the processes offered by a module. When an xData FL-provided module execution Web API is invoked, the system interprets the parameters correctly, prepares the required data for the requested process, and handles interpretation, storage of results, etc.

Module Definition File Structure

Overall Structure

The module definition file is a JSON object with the following structure:

{
  "name": "<module name in FQDN format, uniquely identifying the module>",
  "description": "<module description>",
  "supports": "<list of features supported by the module (TBD)>",
  "definitions": {
    "<parameter type definitions, see Type Definitions below>",
    ...
  },
  "scripts": {
    "<script label>": {
      "description": "<human‑readable description of the script>",
      "path": "<service name to invoke (as defined in docker-compose.yml)>",
      "type": "<script type: training | prediction | aggregation | model_transformation | data_transformation>",
      "input": {
        "<first input definition>": { ... },
        "<second input definition>": { ... },
        ...
      },
      "output": {
        "<first output definition>": { ... },
        "<second output definition>": { ... },
        ...
      }
    },
    "<another script label>": {
      "type": "<script type>",
      ...
    }
  }
}

Type Definitions

Format of a Type Declaration within definitions

Each type declaration must be unique within definitions and follows this format:

"<type name>": {
  "description": "<description of the type>",
  "definition": "<structure definition, see below>"
}

Structure Definition

The structure definition is used as the value of definition in a type declaration and also as the value of paramtype in input/output definitions.

{
  "type": "<kind: model | model_set | data | others>",
  "form": "<file | directory | STDIN/STDOUT, directory only for model_set>",
  "files": [
    "<file definitions if form is directory>"
  ],
  "format": "<format definition for non‑directory forms>",
  "paramtype": "<string name of a model type or nested definition for model_set>"
}

The format varies according to type and form.

1. model, data, or others with directory form

{
  "type": "<model | data | others>",
  "form": "directory",
  "files": [
    { /* file definition */ }
  ]
}

1. model, data, or others with file or STDIN/STDOUT form

{
  "type": "<model | data | others>",
  "form": "<file | STDIN/STDOUT>",
  "format": { /* file format definition */ }
}

1. model_set

{
  "type": "model_set",
  "form": "directory",
  "paramtype": "<name of a model type or nested definition>"
}

File Definition (for directory form)

When the form is directory, each file inside that directory must be listed in the files array:

{
  "name": "<file label>",
  "path": "<relative file name or wildcard within the directory>",
  "form": "<file | directory>",
  "files": [ /* recursive file definitions if form is directory */ ],
  "format": { /* format definition if form is file */ }
}

File Format Definition

Declares the format of a file:

{
  "type": "<CSV | JSON | Movie | ...>",
  "structure": "<format‑specific structure>"
}

For CSV:

{
  "lineseparator": "<row separator, default CRLF>",
  "delimiter": "<column delimiter, default comma>",
  "columns": [
    { "name": "<column label>", "type": "<string | number | date | geometry | ...>" },
    ...
  ]
}

Other file formats are defined as needed.

Model Transfer Method

When type is model, the system handles two files distinguished by their format type:

• Metadata file: JSON (format.type = "json")
• Model body: PyTorch state_dict (format.type = "state_dict")

During input definition, if the form is directory, a file whose format.type is "json" holds metadata, and a file with "state_dict" contains the binary model.
During output definition, the same logic applies.

Input/Output Definition

"<input/output label>": {
  "description": "<human‑readable description>",
  "path": "<relative path within the input/output directory>",
  "paramtype": "<name of a type or nested definition>"
}

The label must be unique for each script’s inputs and outputs.

Example Module Definition

Below is an example definition file for a module that implements the FedAvg aggregation algorithm.

{
  "name": "module.fed-avg-module.aggregate",
  "description": "FedAvg aggregate module",
  "supports": "",
  "definitions": {
    "the_model": {
      "description": "Model before and after aggregation",
      "definition": {
        "type": "model",
        "form": "directory",
        "files": [
          {
            "name": "model_data",
            "path": "model.dat.xdata_meta",
            "form": "file",
            "format": {
              "type": "json",
              "structure": ""
            }
          },
          {
            "name": "model_file",
            "path": "model.dat",
            "form": "file",
            "format": {
              "type": "state_dict",
              "structure": ""
            }
          }
        ]
      }
    }
  },
  "scripts": {
    "fed_avg_aggregate": {
      "description": "FedAvg aggregate",
      "path": "aggregate",
      "type": "aggregation",
      "input": {
        "input_model_set": {
          "description": "input models",
          "path": "models",
          "paramtype": {
            "type": "model_set",
            "form": "directory",
            "paramtype": "the_model"
          }
        }
      },
      "output": {
        "output_model": {
          "description": "output models",
          "path": "aggregated_model",
          "paramtype": "the_model"
        }
      }
    }
  }
}

This module contains a single script that aggregates multiple models into one. The input is a set of models collected under models/, and the output is a single aggregated model stored under aggregated_model/.