Understand the digital twins model parser

The Digital Twins Definition Language (DTDL) is described in the DTDL Specification. Users can use the Digital Twins Model Parser NuGet package to validate and query a model defined in multiple files.

Install the DTDL model parser

The parser is available in NuGet.org with the ID: Microsoft.Azure.DigitalTwins.Parser. To install the parser, use any compatible NuGet package manager such as the one in Visual Studio or in the dotnet CLI.

dotnet add package Microsoft.Azure.DigitalTwins.Parser

Note

At the time of writing, the parser version is 3.12.7.

Use the parser to validate a model

A model can be composed of one or more interfaces described in JSON files. You can use the parser to load all the files in a given folder and use the parser to validate all the files as a whole, including any references between the files:

1. Create an IEnumerable<string> with a list of all model contents:

   using System.IO;
   
   string folder = @"c:\myModels\";
   string filespec = "*.json";
   
   List<string> modelJson = new List<string>();
   foreach (string filename in Directory.GetFiles(folder, filespec))
   {
       using StreamReader modelReader = new StreamReader(filename);
       modelJson.Add(modelReader.ReadToEnd());
   }
   

2. Instantiate the ModelParser and call ParseAsync:

   using Microsoft.Azure.DigitalTwins.Parser;
   
   ModelParser modelParser = new ModelParser();
   IReadOnlyDictionary<Dtmi, DTEntityInfo> parseResult = await modelParser.ParseAsync(modelJson);
   

3. Check for validation errors. If the parser finds any errors, it throws an ParsingException with a list of errors:

   try
   {
       IReadOnlyDictionary<Dtmi, DTEntityInfo> parseResult = await modelParser.ParseAsync(modelJson);
   }
   catch (ParsingException pex)
   {
       Console.WriteLine(pex.Message);
       foreach (var err in pex.Errors)
       {
           Console.WriteLine(err.PrimaryID);
           Console.WriteLine(err.Message);
       }
   }
   

4. Inspect the Model. If the validation succeeds, you can use the model parser API to inspect the model. The following code snippet shows how to iterate over all the models parsed and displays the existing properties:

   foreach (var item in parseResult)
   {
       Console.WriteLine($"\t{item.Key}");
       Console.WriteLine($"\t{item.Value.DisplayName?.Values.FirstOrDefault()}");
   }
   

Next steps

The model parser API reviewed in this article enables many scenarios to automate or validate tasks that depend on DTDL models. For example, you could dynamically build a UI from the information in the model.