TmfSpecificationGenerator 1.0.0

TMF Specification Generator

Generates strongly-typed C# wrapper classes from TMF (TM Forum) specification JSON files with built-in validation and type safety.

Installation

As a .NET Global Tool

dotnet tool install --global TmfSpecificationGenerator

From Source

cd src/TmfSpecificationGenerator
dotnet build -c Release
dotnet pack -c Release
dotnet tool install --global --add-source ./bin/Release TmfSpecificationGenerator

Quick Start

# 1. Generate configuration file
tmfgen generate-config --output config.json
# or using short alias: tmfgen gencfg --output config.json

# 2. Place TMF specification JSON files in ./Specs directory

# 3. Generate C# classes
tmfgen generate-from-config --config config.json
# or using short alias: tmfgen genspeccfg --config config.json

Commands

generate-config

Creates a default configuration file.

Aliases: gencfg

tmfgen generate-config [--output <file>]
# or
tmfgen gencfg [--output <file>]

Options:

• --output - Output file path (default: config.json)

generate-from-config

Generates specification classes from a configuration file.

Aliases: genspeccfg

tmfgen generate-from-config [--config <file>]
# or
tmfgen genspeccfg [--config <file>]

Options:

• --config - Configuration file path (default: config.json)

generate

Generates specification classes with inline options.

Aliases: genspec

tmfgen generate [options]
# or
tmfgen genspec [options]

Options:

• --input <directory> or -i <directory> - Input directory with specification JSON files (default: ./Specs)
• --output <directory> or -o <directory> - Output directory for generated classes (default: ./TMF/GeneratedSpecification)
• --namespace <name> or -n <name> - Namespace for generated classes (default: TMF.GeneratedSpecification)
• --use-newtonsoft - Use Newtonsoft.Json instead of System.Text.Json (not currently supported, default: false)
• --tmf-ver <version> - TMF API version (only v4 is supported, default: v4)
• --generate-ss - Generate Service Specifications (default: true)
• --generate-rs - Generate Resource Specifications (default: true)
• --generate-dependencies - Generate dependency classes; otherwise CxOTmfAssertions.Commons reference is required (default: false)
• --include-version-in-classname - Append the specification version to generated class/proxy names (e.g. CCAP_1, CCAP_1_EntityProxy). Lets you generate distinct proxies for two specifications that share a name but differ in version (default: false)

Note: --use-nsj and --tmf-ver are command-line only options and are not saved in configuration files.

Configuration

Configuration file (config.json):

{
  "Namespace": "TMF.GeneratedSpecification",
  "OutputDir": "./TMF/GeneratedSpecification",
  "InputDir": "./Specs",
  "GenerateServiceSpecifications": true,
  "GenerateResourceSpecifications": true,
  "GenerateDependencies": false,
  "IncludeVersionInClassName": false
}

Note: The configuration file does not include UseNewtonsoftJson or TmfApiVersion as these options are only available via command-line and have limited support (Newtonsoft.Json is not currently supported, and only TMF API v4 is supported).

Input Format

Specification JSON files should follow the TMF API format:

{
  "data": {
    "ResourceSpecification": [
      {
        "name": "PhysicalServer",
        "resourceSpecCharacteristic": [
          {
            "name": "cpuCount",
            "valueType": "integer",
            "resourceSpecCharRelationship": [
              { "relationshipType": "primary-key" }
            ]
          }
        ]
      }
    ]
  }
}

Generated Code

The tool generates:

• Specification definitions - Static classes with characteristic definitions
• Entity proxies - Strongly-typed wrappers with validation
• Factory classes - Extension methods for creating proxies
• Helper classes - Validation and serialization support

Output Structure

OutputDir/
├── CharacteristicProxies.generated.cs
├── CharacteristicDefinition.generated.cs
├── CharacteristicValidator.generated.cs
├── ITmfEntityProxy.generated.cs
├── ISpecialObjectValue.generated.cs
├── ResourceSpecification/
│   ├── {SpecName}.generated.cs
│   ├── {SpecName}.proxy.generated.cs
│   └── EntityProxyFactory.type.generated.cs
└── ServiceSpecification/
    ├── {SpecName}.generated.cs
    ├── {SpecName}.proxy.generated.cs
    └── EntityProxyFactory.type.generated.cs

When IncludeVersionInClassName is enabled, both the generated class name and file name are suffixed with the spec version (e.g. CCAP_1.generated.cs and CCAP_1.proxy.generated.cs, with types CCAP_1 and CCAP_1_EntityProxy). This lets you keep multiple versions of the same specification side by side instead of one overwriting the other.

Specification version on proxies

Every generated proxy exposes the specification version that produced it:

public const string? SpecificationVersion = "1"; // null if the spec has no version
public string? GetSpecificationVersion() => SpecificationVersion;

The version is read from the spec JSON's version field (falling back to the export file's root version when the spec item doesn't define one). This is independent of IncludeVersionInClassName — the field is always emitted.

Usage Example

using TMF.GeneratedSpecification.ResourceSpecification;
using TmfApiClients.ResourceInventoryManagement.v4;
using TmfApiClients.ResourceCatalogManagement.v4;

// Get specification and entity
var specification = await catalogClient.GetResourceSpecificationAsync("PhysicalServer");
var resource = new Resource { Name = "Server01" };

// Create strongly-typed proxy
var proxy = resource.ToEntityProxy<PhysicalServerEntityProxy>(specification);

// Set characteristics with type safety
proxy.CpuCount = 16;
proxy.RamSize = 64;

// Apply default values
proxy.ApplyDefaultCharacteristicValues();

Features

• Type-safe characteristic access - Compile-time checking of characteristic names and types
• Built-in validation - Validates values against TMF characteristic specifications
• Primary key support - Identifies and exposes primary key characteristics
• Default values - Applies default values from specifications
• Dual serialization - Supports both System.Text.Json and Newtonsoft.Json
• Custom types - Supports custom types through annotation property
• Version-aware class names - Optionally append the spec version to generated class/proxy names so multiple versions of the same specification can coexist (IncludeVersionInClassName)
• Specification version on proxies - Each proxy exposes a SpecificationVersion constant and a GetSpecificationVersion() accessor populated from the spec JSON

Troubleshooting

Input directory does not exist

• Ensure the --input directory exists and contains JSON files

Configuration file is not valid JSON

• Validate JSON syntax using a JSON validator

No specifications found

• Verify JSON files contain ResourceSpecification or ServiceSpecification arrays

Tool command not found

• Ensure %USERPROFILE%\.dotnet\tools is in your PATH
• Verify tool installation with dotnet tool list --global

Development

Building

cd src/TmfSpecificationGenerator
dotnet build

Testing

dotnet run -- generate --input ./Specs --output ./TestOutput

Project Structure

TmfSpecificationGenerator/
├── Program.cs                      # Entry point
├── SpecificationGeneratorConfig.cs # Configuration model
├── CommandHandlers/                # CLI command handlers
├── Generators/                     # Code generators
├── Extensions/                     # Extension methods
├── Converter/                      # Serialization converters
├── Enums/                          # Enumerations
└── Templates/                      # Code templates
    └── Helper/                     # Helper templates