OOI.ModelCompiler 3.1.0-rc

Model Design - Domain-Specific Language

Table of Contents

• Preface
• Information Model Concept
• How to get started
• ModelDesign Domain-Specific Language
  • ModelDesign
  • Namespaces
    • Namespace
      • Name Attribute
      • Prefix Attribute
      • InternalPrefix Attribute
      • XmlNamespace Attribute
      • XmlPrefix Attribute
      • FilePath Attribute
      • Version Attribute
      • PublicationDate Attribute
  • NodeDesign
    • BrowseName
    • DisplayName
    • Description
    • Children
    • References
    • SymbolicName
    • SymbolicId
    • IsDeclaration
    • NumericId
    • StringId
    • WriteAccess
    • PartNo
    • Category
  • TypeDesign
    • ClassName
    • BaseType Attribute
    • IsAbstract Attribute
    • NoClassGeneration Attribute
  • ObjectTypeDesign
  • VariableTypeDesign
  • DataTypeDesign
  • ReferenceTypeDesign
  • InstanceDesign
  • ViewDesign
    • SupportsEvents Attribute
    • ContainsNoLoops Attribute
  • ObjectDesign
  • VariableDesign
  • MethodDesign
  • PropertyDesign
  • EncodingDesign
  • DictionaryDesign
  • Reference
  • Parameter
• See also

Preface

The Object Oriented Internet - Model Compiler Library generates C# equivalent code from XML (contain model) and CSV (contain NodeIds) files. The XML input format for the library conforms to the schema defined in UA Model Design.xsd. It defines a schema for domain-specific language (DSL), which is described below.

The output of the library includes:

1. A NodeSet that conforms to the schema defined in Part 6 Annex F;
2. An XSD and BSD (defined in Part 3 Annex C) that describes any data types;
3. Other data files used to load an information model into a Server built with the .NET sample libraries;
4. A CSV file that contains numeric identifiers.

Information Model Concept

To make systems interoperable, i.e. empower common processing of information by variety of computer systems, the data transfer mechanism must be associated with a consistent information representation model. OPC UA uses an object as a fundamental notion to represent data and behavior of an underlying system. The objects are placeholders of variables, events and methods and are interconnected by references. This concept is similar to well-known object-oriented programming (OOP) that is a programming paradigm using "objects" – data structures consisting of fields, events and methods – and their interactions to design computer programs. The OPC UA Information Model [1], [2], [3] provides features such as data abstraction, encapsulation, polymorphism, and inheritance.

For the purpose of unification of the information representation the producers (servers) and consumers (clients) use the type notion. The OPC UA object model allows servers to provide type definitions for objects and their components. Type definitions may be abstract, and may be inherited by new types to reflect polymorphism. They may also be common or they may be system-specific. Object types may be defined by standardization organizations, vendors or end-users. Each type must have a globally unique identifier that can be used to provide description of the data semantics from the defining body or organization. Using the type definitions to describe the information exposed by the server allows for:

• Development against type definition
• Unambiguous assignment of the semantics to the data expected by the client

Having defined types in advance, clients may provide dedicated functionality, for example: displaying the information in the context of specific graphics. It greatly improves reusability as a result of the possibility of designing a unique context for typical real-time processes. As an example, the section Adopting Companion Standard Models - Analyzer Devices Integration presents a case of unification of the model for chemical analyzers.

The OPC UA information modeling concept is based on domains. A domain is a named self-contained collection of definitions. Any domain name must be globally unique - it is an identification string that defines a realm of administrative autonomy and authority of responsibility. Type definition from one domain may be inherited from type definitions located in other domains. To avoid circular references domains should be organized in layers, which expand step by step the basic model provided by the OPC UA Specification.

Type definitions are exposed in the OPC UA Address Space using the specialized NodeClass i.e.: ObjectType, DataType, ReferenceType, VariableType (Section Address Space and Address Space Model). The main role of the types represented by the above NodeClasses is to provide a description of the Address Space structure and to allow clients to use this knowledge to navigate to the desired information in the Address Space exposed by the server. In other words, this way the clients obtain the definition of the data (meta-data) using the following two concepts:

1. NodeClass – as a formal description of the node defining the allowed attributes and references.
2. Type – as a formal description of the node defining values of the allowed attributes and references.

The OPC UA Information Model concept provides a set of predefined types and rules that must be applied to expand it. Even though the OPC UA specification contains a rich set of predefined types, the type concept allows designers to freely define types according to the application needs. New types are derived from the existing ones. The derived types inherit all features from the base types but can include modifications to make the new types more appropriate for information the designers are representing. To expand the standard model, independent domains must be defined. This new information model covered by the domain may be the subject of a companion specification or proprietary release. In any case the definitions must be uniquely named and self-contained except for external type references. All not predefined types (not belonging to the standard domain) must be exposed in the Address Space.

Types are called meta-data since they describe the data structure and not the actual data values. Simplifying, we can say that a NodeClass plays a role similar to the shape of a puzzle piece and the represented information is similar to the picture on the piece. Both are needed to enable us to see the final picture. In the above simplification we have lost that the OPC UA Address Space is capable of displaying movies, and not just static pictures.

From the above discussion we learn that before nodes making up the Address Space can be instantiated by the server, that Address Space must be designed first. Model designing is a process aimed at defining a set of types and their associations and, next, creating an Address Space representation in a format appropriate for implementation. More detailed description of this topic is captured in the section Address Space Model Life-cycle.

The Address Space concept based on types can be a foundation for exposing any information that is required. Clients understand the Address Space concept and have a browse service to navigate the Address Space. Since browsing is based on the incremental and relative passage among nodes it is apparent that each path must have an entry point defined, so we must address the question as to “where to start". To meet this requirement, the Information Model includes definition to create a predefined structure containing well defined nodes that can be used as anchors from which a client can discover the Address Space. Thus to design an Address Space instance using predefined new types, we must derive them from the existing ones. At the very beginning the only existing types are the standard ones defined by the OPC Foundation [1], [3]. The available standard types are briefly described in the sections Standard Information Model.

How to get started

1. Create an object that implements `OOI.ModelCompiler.ICompilerOptions'
2. Populate it with the compiler options
3. Call the compiler

Below is an example code snipped

      CompilerOptionsFixture options = new CompilerOptionsFixture();
      DesignFiles.Add(Path.Combine(SourcePath, "DemoModel.xml"));
      IdentifierFile = Path.Combine(SourcePath, "DemoModel.csv");
      OutputPath = DemoModelDir;
      Directory.CreateDirectory(OutputPath);
      ModelDesignCompiler.BuildModel(options);

Check out the repository to get more details. The full-featured example you will find in the ModelCompilerUnitTest.

ModelDesign Domain-Specific Language

The ModelDesign Domain-Specific language allows information modelers to define UA types in a machine-readable form. This definition can be used to generate code and documentation. The file compliant with the language is expected to contain a number of types and their instance declarations. Objects which are unique in the address space can also be defined. The validator embedded in the library is available to verify the consistency of the model. Once the model is validated it is passed to a generator that creates different types of code or documentation. The language is based on the widely accepted XML syntax. The language syntax is defined by the UA Model Design.xsd schema.

The comments provide an explanation of the schema, they do not explain the concept that is being modeled. It is assumed that the modeler is familiar with these concepts via the UA specifications. An XML file used for generating a model must start with a ModelDesign element.

ModelDesign

ModelDesign is the root element for the information model. The below list is a list of the valid constructs where each construct map to a model concept in UA definition using these construct must be assigned to a UA namespace, by the use of the TargetNamespace attribute, they can further be assigned to an XML namespace and have a default Locale assigned.

Namespaces

This defines the namespaces used in the model. Each namespace listed should also have a namespace prefix defined in the xs:schema element. The order of the namespaces is significant and used to assigned a numeric index to namespaces when they are used in BrowsePaths specified in the ModelDesign.

Namespace

Defines a single namespace along with identifiers for the namespace.The Name is used to create a program constant for the URL. The Prefix is the C# namespace which qualifies the generated types. The InternalPrefix is an optional C# namespace which qualifies the generated types used only by the server.

• The XmlNamespace is
• The FilePath is

Name Attribute

A symbolic name for the namespace that can used as a variable name.

Prefix Attribute

The .NET namespace used for the classes produced by the generator

InternalPrefix Attribute

The .NET namespace used for classes that are only used within a server application.

XmlNamespace Attribute

The URI for the XML namespace which the data types belong to if it is different from the URI for the model namespace

XmlPrefix Attribute

The prefix to be used in the XML file for the XML namespace which the data types belong to. Used only XmlNamespace is set.

FilePath Attribute

The path to the file containing the design file for the namespace.

Version Attribute

TBD: description not provided

PublicationDate Attribute

TBD: description not provided

NodeDesign

The base type of all node designs.

BrowseName

The BrowseName is the name used in the information model. The validator will create the BrowseName automatically from the SymbolicName. The BrowseName is qualified by the namespace used for the SymbolicName.

DisplayName

The DisplayName human readable name for the Node. This element includes an optional key that can be used to look up the display name for other locales in a resource DB. The validator automatically creates the DisplayName from the BrowseName.

Description

The Description the value of the Description attribute for the Node. This element includes an optional key that can be used to look up the description for other locales in a resource DB. The validator automatically creates a generic value of the Description from the BrowseName and NodeClass.

Children

The Children are the Properties or Components of a Node.

References

The References specify additional references from the Node. These references may refer to other children of the same Node or children of other Nodes defined in the ModelDesign.

SymbolicName

The SymbolicName identifies the Node within the the ModelDesign or within the containing Node. The SymbolicName should always be specified. It is used to create the BrowseName and SymbolicId if they are not specified.

SymbolicId

The SymbolicId is a globally unique identifier for the Node. The validator will create the SymbolicId automatically from the SymbolicName if it is not specified.

IsDeclaration

The IsDeclaration flag indicates that the Node is defined elsewhere and no code will be generated. Nodes that are declarations do not need to be completely defined. They only need to have the information required to generate code for nodes that reference it (e.g. the BaseType).

NumericId

The NumericId specifies the unique numeric id for the Node. It is filled in automatically by reading a CSV file containing the SymbolicId names and an associated UInt32. The validator will automatically assign a unique id if no CSV input is provided. The NumericId or StringId are combined with the Namespace used for the SymbolicId to create the well known UA NodeId for the Node. The generator will create programmatic constants that can be used to reference the Node in code.

StringId

The StringId is an alternate unique identifier for the node. It is used instead of the NumericId if it is specified in the CSV input file.

WriteAccess

The bit mask which indicates which attributes are writeable.

PartNo

The part that defines the node.

Category

A comma separated list of categories assigned to the node (e.g. Part4/Services or Part5/StateMachines).

TypeDesign

A base type for all Type Nodes (ObjectType, VariableType, DataType and ReferenceType).

ClassName

This is the name for the instance of the type. If not specified the validator creates it by removing the 'Type' suffix from the SymbolicName for the Node.

BaseType Attribute

The SymbolicId for the BaseType.

IsAbstract Attribute

Whether the Type is abstract.

NoClassGeneration Attribute

Whether to suppress class generation for the type.

ObjectTypeDesign

ObjectTypeDesign define structure of an Object in the information model.

VariableTypeDesign

VariableTypeDesign defines structure of a Variable in the information model.

DataTypeDesign

DataTypes define structure of a Value for Variables in the information model.

ReferenceTypeDesign

ReferenceType define typed references between Nodes

InstanceDesign

A base type for all Instance Nodes (Object, Variable, and Method)

ViewDesign

A View Node.

SupportsEvents Attribute

Whether the View generates events.

ContainsNoLoops Attribute

Specifies that the View contains a non-looping hierarchy.

ObjectDesign

Defines the structure of an Object in the information model

VariableDesign

Defines the structure of a Variable in the information model.

MethodDesign

Defines the a Method in the information model.

PropertyDesign

Defines a Variable which is a Property for a Node.

EncodingDesign

Defines an Object which is a DataTypeEncoding for a DataType

DictionaryDesign

Defines an Variable which is a DataTypeDictionary.

Reference

Defines a reference between two nodes. The SourceId is the SymbolicId of the Node that contains the Reference. The SourcePath and TargetPath are RelativePaths specified using the syntax defined in Part 4. The order of the Namespaces defined in the Namespaces element is used to determine the namespace index used in the RelativePaths

Parameter

Defines a Field in a DataType or Argument of a Method.

See also

• [1] OPC Unified Architecture e-book
• [2] Jürgen Lange, Frank Iwanitz, Thomas J. Burke. Von Data Access bis Unified Architecture. Hüthig Fachverlag, 2009.
• [3] OPC Unified Architecture Specification Part 5: Information Model, OPC Foundation, Rel. 1.04, 2017-11-22
• [4] Address Space Model Life-cycle
• [5] Address Space and Address Space Model
• [6] Standard Information Model
• [7] UA Model Design.xsd