1 Scope

This document specifies the Cloud API of a Cloud Library for storing and retrieving OPC UA NameSpaces.

OPC Foundation

OPC is the interoperability standard for the secure and reliable exchange of data and information in the industrial automation space and in other industries. It is platform independent and ensures the seamless flow of information among devices from multiple vendors. The OPC Foundation is responsible for the development and maintenance of this standard.

OPC UA is a platform independent service-oriented architecture that integrates all the functionality of the individual OPC Classic specifications into one extensible framework. This multi-layered approach accomplishes the original design specification goals of:

Platform independence: from an embedded microcontroller to cloud-based infrastructure

Secure: encryption, authentication, authorization and auditing

Extensible: ability to add new features including transports without affecting existing applications

Comprehensive information modelling capabilities: for defining any model from simple to complex

CESMII

CESMII is the United States’ national institute on Smart Manufacturing, driving cultural and technological transformation and secure industrial technologies as national imperatives. By enabling frictionless movement of information – raw and contextualized data – between real-time Operations and the people and systems that create value in and across Manufacturing organizations, CESMII is ensuring the power of information and innovation is at the fingertips of everyone who touches manufacturing.

Founded in 2016, in partnership with DOE’s Office of Energy Efficiency and Renewable Energy (EERE), CESMII is the third institute funded by EERE’s Advanced Manufacturing Office. The Institute is accelerating Smart Manufacturing (SM) adoption through the integration of advanced sensors, data (ingestion – contextualization – modeling – analytics), platforms and controls to radically impact manufacturing performance, through measurable improvements in areas such as: quality, throughput, costs/profitability, safety, asset reliability and energy productivity. CESMII’s program and administrative home is with the University of California Los Angeles (UCLA).

2 Normative References

The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments and errata) applies.

OPC 10000-1, OPC Unified Architecture - Part 1: Overview and Concepts

OPC 10000-1

OPC 10000-3, OPC Unified Architecture - Part 3: Address Space Model

OPC 10000-3

OPC 10000-5, OPC Unified Architecture - Part 5: Information Model

OPC 10000-5

OPC 10000-6, OPC Unified Architecture - Part 6: Mappings

OPC 10000-6

OPC 10000-7, OPC Unified Architecture - Part 7: Profiles

OPC 10000-7

OPC 11020-1, OPC UA for Cloud Library – Part 1: Architecture and Use Cases

OAS, OpenAPI Specification v3.1.0

https://spec.openapis.org/oas/v3.1.0.html:

3 Terms, abbreviated terms and conventions

3.1 Overview

It is assumed that basic concepts of OPC UA information modelling (OPC 10000-5) and mappings (OPC 10000-6) are understood in this document. This document will use these concepts to describe the Cloud Library Information Model. For the purposes of this document, the terms and definitions given in OPC 10000-1, OPC 10000-3, OPC 10000-5, and OPC 11020-1 apply.

Note that OPC UA terms and terms defined in this document are italicized in the document.

3.2 OPC UA for Cloud Library terms

No specific terms for this part.

3.3 Abbreviated terms

4 Application Programming Interfaces (API) for Accessing the Cloud Library

4.1 General

4.1.1 OpenAPI

From https://spec.openapis.org/oas/v3.1.0.html:

“The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.”

4.1.2 Natural Language Search

“A natural language search is a search using regular spoken language, such as English. Using this type of search you can ask the database a question or you can type in a sentence that describes the information you are looking for. The database then uses a programmed logic to determine the keywords in the sentence by their position in the sentence.” See: https://www.usg.edu/galileo/skills/unit04/primer04_09.phtml

4.2 RESTful OpenAPI Definition of Cloud Library (mandatory)

Defined API endpoints shall follow REST principles as they are stateless. This decouples resources and representations. The data format for information exchange is JSON, therefore the encoding of existing OPC UA NodeSet files can be serialized to JSON (and consumed by the library), as well as being represented in the existing XML format. The new JSON format for the information models will be defined in an updated part 5 of the OPC UA spec.

The resource definitions of the REST API shall be defined self-descriptive using OpenAPI.

REST endpoints shall be provided for

search of information models

fuzzy search on information model metadata, but also custom fields like

commerce metrics (author, price, licence)

owner (who gets paid)

relationships from previous submissions (derivative info models, etc.)

retrieval and upload of information models

validation of information models before uploading

OpenAPI specification Version 3.0.1 is used.

Following is the formal definition of the interface methods:

4.2.1 Method Find

This method returns information model identifiers (implementation-specific) based on an array of keywords provided as input. The identifiers uniquely identify the information models stored in the UA Cloud Library.

Note: A recommended approach to generate these identifiers is to hash the NamespaceUri and the PublicationDate of the information model included in the nodeset file as these two fields uniquely identify an information model.

The keyword “*” (the asterisk character) an be used as a wildcard to return all information models currently available in the UA Cloud Library.

Signature

/informationmodel/find?keywords=”keyword”&keywords=”keyword2”

Parameters

None

Request Body Schema

None

Responses

Response Body Schema

[
  {
    "nodeset_id": uint,
    "nodesettitle": "string",
    "orgname": "string",
    "license": "string",
    "version": "string",
    "adressspacecreationtime": "2021-11-25T15:57:16"
  }
]

Comments

Fuzzy search may be implemented via the SQL ~ statement, i.e. to include information models that only partially match the search keywords.

4.2.2 Method Namespaces

This method returns all information model NameSpaceUris and associated information model identifiers of the information models found in the UA Cloud Library.

Signature

/informationmodel/namespaces

Parameters

None

Request Body Schema

None

Responses

Response Body Schema

[
	“string”
]

4.2.3 Method Names

This method returns all information model names and associated information model identifiers of the information models found in the UA Cloud Library.

Signature

/informationmodel/names

Parameters

None

Request Body Schema

None

Responses

Response Body Schema

[
	“string”
]

4.2.4 Method Download

This method returns a specific information model for the supplied information model identifier.

Signature

/informationmodel/download/{identifier}

Parameters

String Identifier (required) The information model identifier returned from any of the methods “find”, “namespaces” or “names”.

Request Body Schema

None

Responses

Response Body Schema

{
  "title": "string",
  "version": "string",
  "license": 0,
  "copyrightText": "string",
  "contributor": {
    "name": "string",
    "description": "string",
    "logoUrl": "string",
    "contactEmail": "string",
    "website": "string",
  },
  "description": "string",
  "category": {
    "name": "string",
    "description": "string",
    "iconUrl": "string",
  },
  "nodeSet": {
    "nodesetXml": "string",
    "publicationDate": "2022-01-25T19:52:09.664Z",
    "lastModifiedDate": "2022-01-25T19:52:09.664Z"
  },
  "documentationUrl": "string",
  "iconUrl": "string",
  "licenseUrl": "string",
  "keywords": [
    "string"
  ],
  "purchasingInformationUrl": "string",
  "releaseNotesUrl": "string",
  "testSpecificationUrl": "string",
  "supportedLocales": [
    "string"
  ],
  "numberOfDownloads": 0,
  "additionalProperties": [
    {
      "name": "string",
      "value": "string"
    }
  ]
}

4.2.5 Method Upload

This method uploads a specific information model to the UA Cloud Library.

Signature

/informationmodel/upload?overwrite=false

Parameters

Boolean overwrite (optional) An optional flag if an existing OPC UA information model with the same identifier found in the UA Cloud Library should be overwritten. Default value: false

Request Body Schema

{
  "title": "string",
  "version": "string",
  "license": 0,
  "copyrightText": "string",
  "contributor": {
    "name": "string",
    "description": "string",
    "logoUrl": "string",
    "contactEmail": "string",
    "website": "string",
  },
  "description": "string",
  "category": {
    "name": "string",
    "description": "string",
    "iconUrl": "string",
  },
  "nodeset": {
    "nodesetXml": "string",
    "publicationDate": "2022-01-25T19:55:07.348Z",
    "lastModifiedDate": "2022-01-25T19:55:07.348Z"
  },
  "documentationUrl": "string",
  "iconUrl": "string",
  "licenseUrl": "string",
  "keywords": [
    "string"
  ],
  "purchasingInformationUrl": "string",
  "releaseNotesUrl": "string",
  "testSpecificationUrl": "string",
  "supportedLocales": [
    "string"
  ],
  "numberOfDownloads": 0,
  "additionalProperties": [
    {
      "name": "string",
      "value": "string"
    }
  ]
}

Responses

Response Body Schema

string

Comments

Upload cannot overwrite a matching NameSpace from another organization.

The Namespace can be uniquely identified by its NamespaceUri and its PublicationDate and this is how the information model identifier can be generated. The reference implementation provided by the OPC Foundation on GitHub uses this approach.

4.3 GraphQL Query API Definition (optional)

Several Graph query interfaces exist today. GraphQL is popular and a good solution for building web APIs for all types of data stores and the one we chose. Alternatives are Gremlin and SPARQL (originally designed for querying RDF graphs). The GraphQL query API is an alternative to the mandatory REST interface described above and optional for the implementor. The GraphQL endpoint shall be /graphql.

GraphQL Schema

{
  "__validationErrors": [],
  "_queryType": "UACloudLibraryQuery",
  "_mutationType": null,
  "_subscriptionType": null,
  "_directives": [ "@include", "@skip", "@deprecated" ],
  "_typeMap": {
    "__DirectiveLocation": "__DirectiveLocation",
    "__TypeKind": "__TypeKind",
    "__EnumValue": "__EnumValue",
    "String": "String",
    "Boolean": "Boolean",
    "__Directive": "__Directive",
    "__InputValue": "__InputValue",
    "__Type": "__Type",
    "__Field": "__Field",
    "__Schema": "__Schema",
    "UACloudLibraryQuery": "UACloudLibraryQuery",
    "DatatypeType": "DatatypeType",
    "Int": "Int",
    "Long": "Long",
    "MetadataType": "MetadataType",
    "ObjecttypeType": "ObjecttypeType",
    "ReferencetypeType": "ReferencetypeType",
    "VariabletypeType": "VariabletypeType"
  },
  "_subTypeMap": {},
  "_implementationsMap": {}
}

5 Cloud Library Data Model for REST & GraphQL Interface

The following diagram describes the class hierarchy of the NameSpace query for the GraphQL interface. It is also used for uploading and downloading NameSpaces via the REST interface.

5.1 Organization

The Organization Definition represents an organization which may contribute Companion Specifications to the UA Companion Specification Cloud Library.

5.2 Category

The Category describes a collection of NameSpaces, for example all companion specifications released by the VDMA. Each NameSpace is assigned to one Category.

5.3 License

The License enumeration defines some predefined well known license types which are available for contributors of NameSpaces to use or select Custom as the enumeration value and provide a LicenseUrl where the consumer may find detailed license information.

5.4 NodeSet2

The NodeSet2 holds the OPC UA NodeSet for the related NameSpace. Access to this entity should only be provided to users allowed to download the NodeSet file.

5.5 NameSpace

The NameSpace contains meta data describing the NodeSet2 to provide relevant and searchable information. The NameSpace must contain a NodeSet2.

5.6 UANodesetResult

The UANodesetResult contains identification and other meta data for a search result for a given array of search strings.

5.7 Testing

The OpenAPI REST interface may be tested using existing tools available online, e.g. “Swagger Inspector”.

DotNet unit tests shall be added, allowing private implementations of the UA Cloud Library verify the behaviour according to specification.

6 UA Cloud Library Features

The following tables summarize mandatory and optional features that a potential UA Cloud Library implementation must provide. Table 7 briefly describes the features while table 8 marks them mandatory (M) and optional (O).

Annex A Use of Swagger (Informative)

Swagger may be used to document the REST API of the UA Cloud Library. Swagger Version 3 is OpenAPI compatible, see: https://swagger.io/solutions/getting-started-with-oas.

An example UA Cloud Library REST API Swagger definition can be accessed at https://uacloudlibrary.opcfoundation.org/swagger/v1/swagger.json

Annex B Reference implementation (Informative)

The reference implementation of the UA Cloud Library. The UA Cloud Library enables the storage in and querying of OPC UA Information Models from anywhere in the world.

Features

REST interface

GraphQL interface

Swagger UI

GraphQL UI

User management UI

Cross-platform: Runs on Microsoft Azure, Amazon Web Services and Google Cloud Platform

See https://github.com/OPCFoundation/UA-CloudLibrary.

Agreement of Use

COPYRIGHT RESTRICTIONS

This document is provided "as is" by the OPC Foundation and CESMII.

Right of use for this specification is restricted to this specification and does not grant rights of use for referred documents.

Right of use for this specification will be granted without cost.

This document may be distributed through computer systems, printed or copied as long as the content remains unchanged and the document is not modified.

OPC Foundation and CESMII do not guarantee usability for any purpose and shall not be made liable for any case using the content of this document.

The user of the document agrees to indemnify OPC Foundation and CESMII and their officers, directors and agents harmless from all demands, claims, actions, losses, damages (including damages from personal injuries), costs and expenses (including attorneys' fees) which are in any way related to activities associated with its use of content from this specification.

The document shall not be used in conjunction with company advertising, shall not be sold or licensed to any party.

The intellectual property and copyright is solely owned by the OPC Foundation and CESMII.

PATENTS

The attention of adopters is directed to the possibility that compliance with or adoption of OPC or CESMII specifications may require use of an invention covered by patent rights. OPC Foundation or CESMII shall not be responsible for identifying patents for which a license may be required by any OPC or CESMII specification, or for conducting legal inquiries into the legal validity or scope of those patents that are brought to its attention. OPC or CESMII specifications are prospective and advisory only. Prospective users are responsible for protecting themselves against liability for infringement of patents.

WARRANTY AND LIABILITY DISCLAIMERS

WHILE THIS PUBLICATION IS BELIEVED TO BE ACCURATE, IT IS PROVIDED "AS IS" AND MAY CONTAIN ERRORS OR MISPRINTS. THE OPC FOUDATION NOR CESMII MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, WITH REGARD TO THIS PUBLICATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OF TITLE OR OWNERSHIP, IMPLIED WARRANTY OF MERCHANTABILITY OR WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE OR USE. IN NO EVENT SHALL THE OPC FOUNDATION NOR CESMII BE LIABLE FOR ERRORS CONTAINED HEREIN OR FOR DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, RELIANCE OR COVER DAMAGES, INCLUDING LOSS OF PROFITS, REVENUE, DATA OR USE, INCURRED BY ANY USER OR ANY THIRD PARTY IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS MATERIAL, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

The entire risk as to the quality and performance of software developed using this specification is borne by you.

RESTRICTED RIGHTS LEGEND

This Specification is provided with Restricted Rights. Use, duplication or disclosure by the U.S. government is subject to restrictions as set forth in (a) this Agreement pursuant to DFARs 227.7202-3(a); (b) subparagraph (c)(1)(i) of the Rights in Technical Data and Computer Software clause at DFARs 252.227-7013; or (c) the Commercial Computer Software Restricted Rights clause at FAR 52.227-19 subdivision (c)(1) and (2), as applicable. Contractor / manufacturer are the OPC Foundation, 16101 N. 82nd Street, Suite 3B, Scottsdale, AZ, 85260-1830.

COMPLIANCE

The combination of CESMII and OPC Foundation shall at all times be the sole entities that may authorize developers, suppliers and sellers of hardware and software to use certification marks, trademarks or other special designations to indicate compliance with these materials as specified within this document. Products developed using this specification may claim compliance or conformance with this specification if and only if the software satisfactorily meets the certification requirements set by CESMII or the OPC Foundation. Products that do not meet these requirements may claim only that the product was based on this specification and must not claim compliance or conformance with this specification.

Trademarks

Most computer and software brand names have trademarks or registered trademarks. The individual trademarks have not been listed here.

GENERAL PROVISIONS

Should any provision of this Agreement be held to be void, invalid, unenforceable or illegal by a court, the validity and enforceability of the other provisions shall not be affected thereby.

This Agreement shall be governed by and construed under the laws of Germany.

This Agreement embodies the entire understanding between the parties with respect to, and supersedes any prior understanding or agreement (oral or written) relating to, this specification.