Module description source (MDS) is a unified component model definition source file that models component management data, IPMI, as well as component extension and customization capabilities. Its design goal is to ensure that the entire system and development tools share a consistent model foundation. As the definition of system resources, MDS specifies the functional scope and data model of components, ensuring the stability of service code architecture. It serves as the core of the microcomponent framework. The engineering framework automatically generates relevant configuration files and code based on the model source file, simplifying component development. Component developers mainly focus on writing business logic for in-memory objects.

BMCStudio provides a visual interface for configuring MDS and includes a consistency validation feature. It is advised to use BMCStudio for MDS configuration. For usage instructions, refer to the BMC Studio User Guide.

Composition ​

All MDS-related files are located in the /mds directory of the component repository. To maintain consistency across the system and avoid multiple configuration description languages, MDS uses the json format.

• service.json

Describes the component's service model, including its name, version, dependencies, and subscriptions or access to other components' app resource collaboration interface properties.

• model.json

Defines the component's data model, including class definitions, properties, object paths, and interfaces.

• ipmi.json

Describes the component's IPMI command model, including command configurations and the data formats for requests and responses.

• types.json

Used when the model involves complex data structures. It describes the data types used by the component's data model and IPMI command model—such as class properties, interface properties, interface methods, structures, and enumeration types.

• schema.json

Used for field format validation. This file is automatically generated based on model.json and does not require manual configuration.

Directory Structure ​

The directory structure is divided into development mode and deployment mode.

Directory Structure of the Development Mode: ​

└── mds
    └── service.json
    └── model.json
    └── ipmi.json
    └── types.json
    └── debug
        └── model.json
        └── ipmi.json

Directory Structure of the Deployment Mode: ​

/opt/bmc/
└── apps/xxx/mds
    └── service.json
    └── schema.json

service.json ​

The service.json file is mainly used to define the component's name and description, the components it depends on during independent build and DT testing, and the collaboration interfaces required by the component.

Configuration Example: ​

{
    "name": "app_name",
    "type":  "application",
    "deployConfig":  "app.service",
    "version" :  "1.0.1",
    "author" :   "",
    "license" :  "Mulan PSL v2",
    "language": "lua",
    "description" : "micro-component app",
    "codeGenPolicy": {
        "version": 3
    },
    "dependencies": {
        "build": [
            {
                "conan": "liba2/[>1.0.0]"
            },
            {
                "conan": "liba3/[>=1.1.0]"
            },
        ],
        "test": [
            {
                "conan": "lib/1.2.3"
            }
        ]
    },
    "required": [
        {
            "path": "*",
            "interface": "bmc.kepler.XXXXX"
        },
        {
            "path": "/bmc/kepler/XXXXX",
            "interface": "bmc.kepler.XXXXX",
            "properties": {}
        },
        {
            "path": "/bmc/kepler/XXXXXX/${Id}",
            "interface": "bmc.kepler.XXXX",
            "properties": {}
        }
    ]
    ...
}

Field Description: ​

name ​

The component name. It uses lowercase letters and underscores, and must be consistent with both the deployment-mode MDS path /opt/bmc/apps/xxx/mds (the xxx part) and the repository name.

type ​

The component type. Supported types include application, library, tool, command, and configuration.

deployConfig ​

Deployment configuration for the component. Applicable when the component type is application (currently referring to a systemd configuration file).

version ​

The component version, following a three-segment dotted format.

author ​

The author of the component—either an individual or an organization/company.

license ​

The license governing the component. The default license is Mulan PSL v2.

language ​

The programming language used (e.g., Lua, C, C++), which helps the code generation tool select the appropriate template.

description ​

A brief summary of the component—a short sentence describing what it is.

codeGenPolicy ​

The code generation policy for the component. The code generation tool will generate corresponding code based on the version and other information specified in this policy.

dependencies ​

The component's dependencies during building or testing, primarily including library files and foundational framework or platform components. Versions can be defined precisely or with flexible ranges, following Conan's versioning policy (refer to BMC Studio CLI (bingo) for details).

1. 1.2.3: precisely specifies that the component or library must be at the stable version 1.2.3.
2. [>=1.0.0]: specifies that the component or library must be the latest stable version later than 1.0.0.
3. [>1.0.0 <1.10.0]: specifies a version range for the component or library; the latest released version within the range will be selected.

required ​

Defines the component's dependencies on other resource collaboration interfaces.

Note: If the dependency is not configured here, the corresponding resource cannot be invoked in the code.

It indicates the resource collaboration interface required for component running and is mainly used to generate the client code for interface access in the component.

1. interface: The name of the interface required at runtime.
2. path: The object path of the interface, with three ways to define it:
   • No specific object path (ObjectPath)
   • Object path without dynamic parameters—dependency check performed at runtime.
   • Object path with dynamic parameters—dependency check also performed at runtime.
3. properties: specify runtime property dependencies and currently support precise signal subscription to property changes.
4. optional: defines the dependency strength. True indicates weak dependency. The absence of the interface does not affect component execution. The default value is false.
5. stage: defines the lifecycle stage at which the interface must be available. Stages include starting and running and the default value is running.

model.json ​

The file is primarily used to define the component's internal and external resources, corresponding data models, data model persistence mode, and access permission.

Configuration Example of MDS Classes and Properties: ​

{
    "ClassA": {
        "tableName":"t_classa",
        "tableLocation":"Local",
        "path": "/bmc/kepler/xxx/${Id}",
        "privilege": ["UserMgmt", "BasicSetting"],
        "interfaces":{
            "bmc.kepler.IClassA":{
                "privilege": ["SecurityMgmt"],
                "properties":{
                    "PropA1": {
                        "privilege": {
                            "read": ["ReadOnly"],
                            "write": ["ConfigureSelf"],
                        },
                        "usage": ["CSR",  "PermanentPer"]
                    },
                    "PropA2": {
                        "usage": ["ResetPer"],
                        "alias": "IClassAPropA1"
                    }
                }
            },
            "bmc.kepler.IClassAExtend":{
                "properties":{
                    "PropA2": {
                        "usage": ["PoweroffPer"],
                        "alias": "IClassAExtendPropA2",
                        "sensitive": true,
                        "critical": true
                    }
                },
                "methods": {
                    "Method1" : {
                        "privilege": ["DiagnoseMgmt"],
                    }
                }
            },
            "description": "this is a demo"
        },
       "properties" : {
        …
        }
    },
    …
}

Field Description: ​

Persistence Configuration Fields ​

MDS classes support database-based persistence. In the class definition, setting tableLocation to Local indicates local persistence. If this field is not configured or set to another value, remote persistence is used instead. For more details on persistence, refer to the Persistence section in the Lua Programming Framework.

tableName ​

Specifies the name of the database table used for object persistence.

tableLocation ​

Specifies whether persistence is remote or local. The value can only be "Local", indicating local persistence; if not configured, remote persistence is applied.

tableType ​

Defines the persistence type for all class properties. property persistence must be configured in the usage field of each property (see below).

ClassA ​

The MDS class name for the service model, written in PascalCase. If the instantiated object needs to be mounted to D-Bus (i.e., a path field exists), the class name must match the file name corresponding to that path (see MDB Syntax). If not mounted to D-Bus, the class name is not restricted and only needs to be unique.

path ​

Specifies the object path on D-Bus where the class's interfaces (the contents under interfaces) are mounted.

interfaces ​

Defines the set of resource collaboration interfaces supported by the class. These interfaces are detailed in the MDB.

bmc.kepler.IClassA ​

The name of the interface implemented by the object, which must match the interface name in mdb_interface.

properties ​

Define the collection of properties under the resource collaboration interface. Only the property names (e.g., PropA1, PropA2) and their usage need to be specified in PascalCase. Property types and validation constraints are already defined in the MDB.

usage ​

Indicates the purpose of the property. It can be a combination of multiple purposes or left empty. Supported purpose types include CSR, PermanentPer, PoweroffPer, ResetPer, TemporaryPer, PoweroffPerRetain, ResetPerRetain, and TemporaryPerRetain.

• Configuring CSR means the value can come from the CSR configuration.

All other options define the field's persistence type, and only one can be selected:

description ​

A comment field for the Class; it is not involved in code generation.

alias ​

An alias for the property. The alias resolves naming conflicts between resource collaboration interface properties or between such properties and private properties, ensuring unique access to the property (including persistent access and D-Bus object access). The alias follows these constraints:

• Only resource collaboration interface properties can have aliases; private properties cannot. An alias must not duplicate any existing interface property name or private property name.
• If N interface properties share the same name, aliases must be assigned to at least N-1 of them (or to all of them).
• For properties that have both a usage type including "CSR" and an alias, the CSR configuration must use the alias instead of the original name.
• Aliases must not be changed arbitrarily to avoid compatibility issues.

privilege ​

As shown in the example, the privilege field can be configured on objects, interfaces, properties, and methods.

Supported privilege types include: UserMgmt, BasicSetting, KVMMgmt, VMMMgmt, SecurityMgmt, PowerMgmt, DiagnoseMgmt, ReadOnly, and ConfigureSelf.

If a user only has ConfigureSelf privilege, but the D-Bus path, the resource collaboration interface, or its properties/methods have no privilege configured, or have privilege configured but do not include ConfigureSelf, the framework will return an error requiring a password change.

When privileges are configured at multiple levels, the system applies local-inherits-from-global principle, meaning the required privileges are:

• For accessing a resource collaboration interface property/method: resource collaboration interface access privilege and D-Bus path access privilege (all must be satisfied)
• For accessing a resource collaboration interface: D-Bus path access privilege (all must be satisfied)

Further details of privilege configuration are described below.

sensitive ​

Indicates whether the property is sensitive data. When the value is true, the framework automatically anonymizes the data in debug terminals during viewing and one-click export. Default is false.

critical ​

Indicates whether the property is critical. When set to true and the property uses power-off persistence, the system writes it to disk and backs it up in real time during persistence; otherwise, periodic backup is used. Default is false.

Configuration Example of the Private Class Properties of MDS: ​

In component business code, some data models do not need to be exposed through resource collaboration interfaces but still need to be managed by the micro-component framework to enable features such as descriptions, persistence, and CSR-based configuration. In this case, an MDS private class can be used.

{
    "ClassA": {
        "tableName":"t_classa",
        "tableLocation":"Local",
        "path":"bmc/kepler/xxx/${Id}",
        "interfaces":{
         …
        },
        "properties": {
            "PropA4": {
                "usage": ["PoweroffPer"],
                "baseType":  "U32",
                "default": 1,
                "minimum": 0,
                "maximum": 100
            },
            "PropA5": {
                "usage": ["CSR"],
                "baseType": "U8[]",
                "refInterface":"bmc.kepler.IBlockIO"
            },
            "PropA6": {
                "usage": ["CSR"],
                "baseType": "String",
                "minLength": 1,
                "maxLength": 64,
                "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
            }
        }
    },
    …
}

Field Description: ​

properties ​

Defines private properties of the class (not mounted to resource collaboration interfaces). These properties must not share names with interface properties or aliases. Each private property (PropA4, PropA5, and more) must be fully defined. properties are at the same level as interfaces.

usage ​

Same meaning as the usage field for interface properties.

baseType ​

Specifies the property type. Unlike interface properties, whose types are defined by the interface itself, private properties must declare their own types.

Supported types include U8, U16, U32, U64, S16, S32, S64, Double, String,and their array forms. When custom types are defined in types.json, Array, Struct, and Enum are also allowed. The standard schema type field is not used. See the types.json section for more information.

default ​

Specifies the property's default value according to its type. "" represents an empty string. This field is optional; if omitted, the generated code uses type-appropriate defaults such as 0, an empty string, an empty array, or an empty dictionary.

Type verification field ​

minimum/maximum: range limits for numeric types; minLength/maxLength: length limits for string types; pattern: format requirements for string types, validated using a regular expression. Additional validation fields may follow the json-schema specification.

refInterface ​

Indicates that the property references another object (using the # syntax in CSR) and retrieves the set of methods and properties defined under that object's interface.

It indicates that the property retrieves or sets data through the interface's Read/Write methods (typical for device objects that require block-based read/write operations, such as EEPROM), or directly reads properties from that interface (typical for software configuration objects like Component). The referenced interface (e.g., bmc.kepler.IBlockIO) must comply with the unified resource collaboration interface definition and be explicitly declared under require in service.json.

types.json ​

types.json defines complex types in the model, including structures and enums.

Configuration Example: ​

{
    "defs": {
        "AaaBbb": {
            "MemVar1": {
                "baseType": "Boolean"
            },
            "b2": {
                "baseType": "Struct",
                "$ref": "#/defs/XxxYyy"
            }
        },
        "XxxYyy": {
            "MemVar3": {
                "baseType": "S64[]"
            },
            "MemVar4": {
                "baseType": "String"
            }
        },
        "EAbcXyz": {
            "EnumVal1" : 1,
            "EnumVal2" : 2
        }
    }
}

Field Description: ​

1. defs is a fixed field and serves as the entry point for complex type definitions.
2. AaaBbb, XxxYyy, and EAbcXyz are names of structure or enum types. MemVar1, MemVar2, MemVar3, and MemVar4 are structure member names. EnumVal1 and EnumVal2 are enum variable names. All names follow the PascalCase style.

Configuration Example of Complex Data Types (model.json Used as an Example): ​

{
    "ClassDemo": {
        "path": "/bmc/kepler/Demo/:Id",
        "interfaces" : {},
        "properties": {
            "a1" : {
                "baseType": "Struct",
                "$ref": "types.json#/defs/AaaBbb"
            },
            "a2": {
                "baseType": "Array",
                "items": {
                    "baseType": "Struct",
                    "$ref": "types.json#/defs/AaaBbb"
                }
            },
            "a3" : {
                "baseType": "Enum",
                "default": "EnumVal1",
                "$ref": "types.json#/defs/EAbcXyz"
            },
            "a4" : {
                "baseType": "Struct",
                "$ref": "mdb://bmc/demo/IDemo.json#/defs/Struct1"
            },
            "a5": {
                "baseType": "Enum",
                "$ref": "mdb://bmc/demo/IDemo.json#/defs/Enum1"
            }
        }
    }
}

Field Description: ​

Extended baseType Values ​

Beyond basic types, the complex types defined in types.json can be referenced using extended baseType values:

1. Struct: Indicates that the property is a structure. The $ref field specifies where the structure is defined. For example, types.json#/defs/AaaBbb means that the structure AaaBbb is defined under the "defs" object in types.json.

2. Array: Indicates that the property is an array. Array items may be basic types or structure/enum types. When items are structures or enums, $ref specifies their definition location.

3. Enum: Indicates that the property is an enumeration type. The default field specifies its default value and must match one of the enumeration's defined variable names. The $ref field specifies the enumeration's definition location. For example, types.json#/defs/EAbcXyz means the enum EAbcXyz is defined under the "defs" object in types.json.

Special $ref Values: ​

mdb://bmc/demo/IDemo.json#/defs/Struct1 and mdb://bmc/demo/IDemo.json#/defs/Enum1 reference structure and enum definitions in a resource collaboration interface description file. This syntax also applies to arrays.

Keyword Usage Specifications ​

Component Model Properties, Methods, and Signal Keywords ​

Property Keywords ​

Among property keywords, only the default keyword is allowed to override the definition in the resource tree interface. All other property keywords can only be defined within the component model.

Method Keywords ​

The method keywords below can be defined only in the component model.

Signal Keywords ​

The signal keywords below can be defined only in the component model.

ipmi.json ​

Configuration Example: ​

{
    "package" : "XXIpmiCmds",
    "cmds": {
        "CmdName1" {
            "netfn": "0x0f",
            "cmd": "0x0f",
            "priority":  "Default",
            "role" : "Administrator",
            "req" : [
                {"data": "Iana", "baseType": "U32", "len": "3B", "value": "0xFFFF", "customizedRule": "Manufacturer"},
                {"data": "SubCmd", "baseType": "U8", "len": "1B", "value": "0xFF"},
                {"data": "Reserved", "baseType": "U8", "len": "4b"},
                {"data": "ChannelNum", "baseType": "U8", "len": "4b"},
                {"data": "Length", "baseType": "U16", "len": "2B"},
                {"data": "Data", "baseType": "U8[]", "len": "Length"},
                {"data": "Sign", "baseType": "String", "len": "64B"},
                {"data": "Padding", "baseType": "U8[]", "len": "*"}
            ],
            "rsp": [
                {"data": "Iana", "baseType": "U32", "len": "3B"}
            ],
            "sysLockedPolicy": "Allowed",
        },
        "CmdName2": {
        }
    }
}

Field Description: ​

package ​

The name of the IPMI command package, using PascalCase.

cmds ​

A collection of IPMI command definitions.

CmdName1 ​

The command name, written in PascalCase (e.g., SetEventReceiver, GetDeviceId, WriteSmbios). Command names must be unique within the same component.

netfn ​

The network function code of the command, expressed as a hexadecimal string.

cmd ​

The command code, expressed as a hexadecimal string.

priority ​

Defines the routing priority for IPMI commands, which determines the actual handler. Supported priority levels include Default, OEM, ODM, OBM, and EndUser (customization for end users). Runtime priority order is: Default < OEM < ODM < OBM < EndUser.

privilege ​

The permissions required to execute the command. Supported privilege types include: UserMgmt, BasicSetting, KVMMgmt, VMMMgmt, SecurityMgmt, PowerMgmt, DiagnoseMgmt, ReadOnly, and ConfigureSelf. Multiple permissions may be configured, and all must be satisfied to run the command.

req/rsp ​

Defines the request and response of the command. Each is an array describing fields in a structured format. The fields of req/rsp are:

1. data: field name, written in PascalCase.
2. baseType: field type (same usage as in model.json).
3. len: field length, where: B = bytes; b = bits; and * = variable length.
4. value: field value (used as a filter).
5. Variable-length data rules: If the variable-length data appears in the middle of the data block, a separate field must indicate the actual length (see Length and Data). The len of the data field must reference the name of this length field. If the data appears at the end (see Padding), len may use *, and the type may be U8[] or String.
6. customizedRule: customization rule; currently only Manufacturer is supported, where the corresponding field in the request or response is replaced with the manufacturer identifier.

sysLockedPolicy ​

Indicates whether the IPMI command is allowed when the system is locked. Options: Allowed or Forbidden. Default is Allowed.

sensitive ​

Indicates that the request or response contains sensitive information, which should be anonymized in scenarios such as IPMI tracing.