Tutorial01_HelloWorld.md

Determine whether a DTDL model is valid

This tutorial demonstrates basic interaction with this library's core class, ModelParser. This class is used to determine whether one or more DTDL models are valid, to identify specific modeling errors, and to enable inspection of model contents. This tutorial walks through the first of these uses: determining whether a model is valid. An asynchronous version of this tutorial is also available. More detailed uses are covered in further tutorials.

Create a ModelParser

To parse a DTDL model, you need to instantiate a ModelParser. No arguments are required.

var modelParser = new ModelParser();

Obtain the JSON text of a DTDL model

The DTDL language is syntactically JSON. The ModelParser expects a string value, which is JSON text of a DTDL model.

string jsonText1 =
@"{
  ""@context"": ""dtmi:dtdl:context;3"",
  ""@id"": ""dtmi:example:anInterface;1"",
  ""@type"": ""Interface"",
  ""contents"": [
    {
      ""@type"": ""Telemetry"",
      ""name"": ""currentDistance"",
      ""schema"": ""double""
    }
  ]
}";

Submit the JSON text to the ModelParser

The main synchronous method on the ModelParser is Parse(). One argument is required: a string containing the JSON text to parse as DTDL. If the submitted model is invalid, a ParsingException will be thrown. If the submitted model is referentially incomplete, a ResolutionException will be thrown. If no exception is thrown, the model is valid.

try
{
    var objectModel = modelParser.Parse(jsonText1);
    Console.WriteLine($"DTDL model is valid!");
}
catch (ResolutionException ex)
{
    Console.WriteLine($"DTDL model is referentially incomplete: {ex}");
}
catch (ParsingException ex)
{
    Console.WriteLine($"DTDL model is invalid: {ex}");
}

The JSON text above is valid DTDL, so the code snippet above will display:

DTDL model is valid!

Obtain the JSON text of a DTDL model containing multiple Interface definitions

The JSON text of a DTDL model can contain a JSON array with multiple Interface definitions as elements of the array.

string jsonText2 =
@"{
  ""@context"": ""dtmi:dtdl:context;3"",
  ""@id"": ""dtmi:example:anotherInterface;1"",
  ""@type"": ""Interface"",
  ""contents"": [
    {
      ""@type"": ""Property"",
      ""name"": ""expectedDistance"",
      ""schema"": ""double"",
      ""writable"": true
    }
  ]
}";

string jsonText = $"[ {jsonText1}, {jsonText2} ]";

Submit the combined JSON text to the ModelParser

try
{
    var objectModel = modelParser.Parse(jsonText);
    Console.WriteLine($"DTDL model is valid!");
}
catch (ResolutionException ex)
{
    Console.WriteLine($"DTDL model is referentially incomplete: {ex}");
}
catch (ParsingException ex)
{
    Console.WriteLine($"DTDL model is invalid: {ex}");
}

The JSON text above, which contains two Interface definitions, is valid DTDL. The code snippet above will display:

DTDL model is valid!

Submit an enumeration of JSON text strings

The ModelParser also expects an enumeration of strings, each of which is JSON text of a DTDL model.

string[] jsonTexts = { jsonText1, jsonText2 };

The synchronous Parse() method on the ModelParser, in addition to accepting a single string, also accepts an enumeration of string values containing the JSON text to parse as DTDL.

try
{
    var objectModel = modelParser.Parse(jsonTexts);
    Console.WriteLine($"DTDL model is valid!");
}
catch (ResolutionException ex)
{
    Console.WriteLine($"DTDL model is referentially incomplete: {ex}");
}
catch (ParsingException ex)
{
    Console.WriteLine($"DTDL model is invalid: {ex}");
}

The enumeration of JSON texts above is valid DTDL, so the code snippet above will display:

DTDL model is valid!