Publication Date: 2021-01-13

Approval Date: 2020-12-15

Submission Date: 2020-11-19

Reference number of this document: OGC 20-033

Reference URL for this document: http://www.opengis.net/doc/PER/t16-D020

Category: OGC Public Engineering Report

Editor: Sam Meek

Title: OGC Testbed-16: OpenAPI Engineering Report


OGC Public Engineering Report

COPYRIGHT

Copyright © 2021 Open Geospatial Consortium. To obtain additional rights of use, visit http://www.opengeospatial.org/

WARNING

This document is not an OGC Standard. This document is an OGC Public Engineering Report created as a deliverable in an OGC Interoperability Initiative and is not an official position of the OGC membership. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an OGC Standard. Further, any OGC Public Engineering Report should not be referenced as required or mandatory technology in procurements. However, the discussions in this document could very well lead to the definition of an OGC Standard.

LICENSE AGREEMENT

Permission is hereby granted by the Open Geospatial Consortium, ("Licensor"), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement.

If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.

THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD. THE INTELLECTUAL PROPERTY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.

This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.

Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications.

This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.

None of the Intellectual Property or underlying information or technology may be downloaded or otherwise exported or reexported in violation of U.S. export laws and regulations. In addition, you are responsible for complying with any local laws in your jurisdiction which may impact your right to import, export or use the Intellectual Property, and you represent that you have complied with any regulations or registration procedures required by applicable law to make this license enforceable.

1. Subject

This OGC Testbed 16 Engineering Report (ER) documents the two major aspects of the Testbed 16 OpenAPI Thread. These are:

  • A Unified Modeling Language (UML) metamodel that describes OpenAPI and a profile of that model to describe OGC API - Features - Part 1: Core;

  • An implementation of a transformation procedure in the ShapeChange open source software. This procedure was designed to transform a UML representation of the OGC API - Features - Part 1: Core model into an OpenAPI 3.0 document.

The process for creating the model and doing the transformation relied upon the Model Driven Architecture (MDA) approach. MDA takes a platform independent model (PIM) and transforms that model into a platform specific model (PSM).

2. Executive Summary

The OGC Testbed-16 OpenAPI thread and work items were focused on utilizing the Model Driven Architecture (MDA) approach for generating OpenAPI documents. The approach required a Platform Independent Model (PIM) to be transformed into a target Platform Specific Model (PSM) to create the physical artifacts. For Testbed-16 these were a JavaScript Object Notation (JSON) representation of an OpenAPI definition.

OpenAPI is constructed as a specification and has no official UML representation. Therefore the UML model describing OpenAPI including relationships, constraints, attributes and classes, was constructed using the specification as guidance. The OpenAPI specification was modeled in full. However, Application Programming Interface (API) requirements specified in OGC API standards were not explicitly modeled during this Testbed. This approach provides other interested parties with the broadest interpretation of the requirements for an OpenAPI based specification. In the future, business rules may be implemented for OGC API - Common to control the building blocks of new OGC APIs. Another approach for future work is to implement OGC API - Common as the metamodel, rather than the full OpenAPI specification.

The modeling aspect of the project required two separate models to be created: The OpenAPI metamodel and a specialization of that model to describe an existing OGC Standard. The latter is the UML model that was used in the ShapeChange experimentation. At the time of Testbed-16, the only ratified OGC API Standard was OGC API - Features - Part 1: Core. Therefore, OGC API - Features was used as an example standard to transform using the ShapeChange software.

The approach to using the metamodel-model construct was to invoke a UML specialization relationship. The metamodel provides the generalized versions of each of the OpenAPI constructs created from the specification. This was done to provide the user with rules to describe what should be included as part of any class specialization as well as providing the ShapeChange implementation with a set of supertypes that rules can be implemented against. Therefore, any class specializing from the metamodel is treated the same as part of the ShapeChange implementation. As the OpenAPI specification is not designed in UML, design decisions were made throughout the modeling process as to how to represent relationships and group attributes into classes. This resulted in a highly complex model that fully represents the OGC API - Features Part 1:Core standard. However, the utility of generating APIs using this approach is questionable.

The implementation was completed in ShapeChange with a specific goal of creating a pipeline for converting the UML model into a JSON representation of the interface. The approach taken was to create a first pass for converting the UML model into the JSON representation. The lessons learned from the ShapeChange implementation will be used in future Testbeds, potentially involving extra components such as a rules engine.

The recommendations from the project are as follows:

  • The project demonstrated that an MDA approach can be used to model APIs using the metamodel/model approach. However, the process is complex and models can quickly become very large. Work should be undertaken to simplify the modeling process. This could be done by creating blocks of modeling artifacts that can be reused when creating new standards and simplify the process for the modeler and model generation process.

  • Currently, the only target considered for the modeling work is OpenAPI. A wider consideration for the OGC is whether OpenAPI is the only target worth considering, or whether other targets should be implemented.

  • This project raised the question whether there should be a separation between a Standard and an encoding. Currently the OGC API work is heavily invested in OpenAPI, but there will come a time when some other encoding, language or approach may be more suitable. A recommendation is that conceptual models for new standards are the ideal starting point and the encoding aspect is secondary. This observation also highlights the concept of domain knowledge, which is captured in the standard definition process, but expressed in the encoding. Requirements for standards captured in domain knowledge does not change very often, but technologies do. By keeping the domain knowledge aspect of a standard separate from the encoding may enable more forward interoperability with future versions of the standard.

  • ShapeChange is an excellent piece of software. However, there are some changes that could be made to make the experience of developing with it more palatable. ShapeChange seems reliant on SCXML, which means that any transformations are reliant on the contents of the SCXML. A salient example of this is the association class, where the class information is captured but the relationship between the association class and the relationship it describes is omitted.

2.1. Document contributor contact points

All questions regarding this document should be directed to the editor or the contributors:

Contacts

Name Organization Role

Sam Meek

Helyx SIS

Editor

Dan Bala

Helyx SIS

Contributor

Anneley Hadland

Helyx SIS

Contributor

2.2. Foreword

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

3. References

4. Terms and definitions

For the purposes of this report, the definitions specified in Clause 4 of the OWS Common Implementation Standard OGC 06-121r9 shall apply. In addition, the following terms and definitions apply.

● metamodel

a metamodel or surrogate model is a model of a model

4.1. Abbreviated terms

  • COTS Commercial Off The Shelf

  • JSON JavaScript Object Notation

  • MDA Model Driven Architecture

  • OGC Open Geospatial Consortium

  • OO Object-oriented

  • SCXML ShapeChange Extensible Markup Language

  • UML Unified Modeling language

  • XML Extensible Markup Language

5. Overview

The rest of this ER is structured accordingly: Chapter 6 introduces the ER and provides an overview of the Testbed-16 OpenAPI thread objectives.

Chapter 7 provides the background to this ER including relevant work in previous Testbeds and Pilots as well as the MDA approach, OpenAPI and ShapeChange.

Chapter 8 discusses the OpenAPI modeling aspect of the project including the metamodel and the derived OGC API - Features model.

Chapter 9 documents the implementation of the ShapeChange extension and process.

Chapter 10 discusses the work and includes recommendations, future work and conclusions for the ER and the project.

6. Introduction

This Engineering Report (ER) provides the documentation for the OpenAPI thread in the Open Geospatial Consortium (OGC) Testbed-16 interoperability initiative. The thread consists of two official work items:

  1. A UML model and ShapeChange extension to enable transformation of a UML API model to an OpenAPI JSON representation.

  2. This document.

The work documented in this ER is a follow-on to the work done in the UML-to-GML Application Schema (UGAS2020) Pilot (completed November 2020) [1]. UGAS2020 had four main work items, two of which are the foundation for the work described in this Testbed-16 ER. These two work items are: Rules for conversion of UML to JSON schema and initial considerations for using the MDA approach to transforming a UML model of an OpenAPI interface to a JSON representation. The work on JSON schemas is relevant to this ER as the OpenAPI specification uses JSON schema in several places throughout the interface specification.

A UML representation of both the OpenAPI specification and OGC API - Features - Part 1: Core was created. The OpenAPI model is used as a metamodel for creating models of OGC standards. The metamodel is a UML representation of the OpenAPI specification. However, some design decisions were made to fit a JSON representation into an Object Oriented (OO) modeling language. This was done because JSON encodings do not utilize OO concepts such as inheritance. Details regarding this can be found in both the related Testbed-14 ER [2] and the UGAS-2020 Pilot ER [1].

Development of the metamodel was done for two main reasons: 1.) Understanding the process for modeling the specification in UML, and 2.) Creating a model to specialize implementations from. As the implementations are specialized, it is possible to enforce the conversion to JSON in ShapeChange using rules defined at the metamodel level. For example, the OGC definition of a Landing Page is a specialized version of OpenAPI type defined in the specification.

OGC API - Features - Part 1: Core was modeled via specialization of the metamodel and using ShapeChange to produce a JSON representation of the API definition. This approach was chosen because at the time of Testbed-16, Part 1 of the Features API was the only OGC standard from the OGC APIs suite approved as an official OGC Standard. The Features API also contains many of the building blocks specified in the draft OGC API - Common. A drawback to the approach of modeling an OGC standard is that it is complex in MDA terms and utilizes much of the OGC API specification. In retrospect, first attempting using the MDA process on a simple OpenAPI implementation and at a later date attempting complex models would have been prudent.

7. Background

OGC has adopted OpenAPI as the basis for its resource based suite of standards that are being developed in parallel with the XML based web services standards. The first OGC standard using OpenAPI was OGC API - Features. This new OGC Web API complements the OGC Web Feature Service (WFS) standard and may be used as a replacement. Alternatively, a facade between the OGC API -Features instance and the OGC WFS endpoint can be implemented.

OpenAPI utilizes REST endpoints and well-known HTTP verbs including:

  • GET

  • POST

  • PUT

  • OPTIONS

  • HEAD

  • DELETE

The development of OGC Web APIs to JSON based OGC APIs is a major shift in the work of the OGC and has ramifications beyond simply defining and standardizing REST endpoints. For example, many of the return types for geospatial data are XML based, such as GML, as well as the ISO standards that form the basis of defining "returns" from metadata catalogs. Therefore, moving to an API based structure involves having sensible return types and schemas while maintaining the domain knowledge of the standard.

In addition to OGC API - Features, there are other emerging standards being developed to complement the OWS approach. There is also a foundation API standard named OGC API – Common that is being developed. At the time Testbed 16 was being executed, the following new OGC Web APIs were in development:

  • OGC API – Common – Part 1: Core

  • OGC API – Features – Part 2: Core (approved on November 2nd, 2020)

  • OGC API – Coverages – Part 1: Core

  • OGC API – Records – Part 1: Core

  • OGC API – Processes – Part 1: Core

  • OGC API – Tiles – Part 1: Core

  • OGC API – Maps – Part 1: Core

  • OGC API – Styles – Part 1: Core

  • OGC API – Environmental Data Retrieval

The draft OGC API - Common contains common requirements across each of the emerging Web API standards. This standard was particularly important for this Testbed 16 activity as it helps define the rules that go beyond what is supported in the OpenAPI specification. The specification of standards within the OGC is performed in Standards Working Groups (SWGs), with input from the Domain Working Groups (DWGs). These groups are responsible for generating new standards or contributing to existing standards based on a particular domain of interest. The process of contributing to domains or standards varies across the different working groups and therefore the process of creating new standards is also different across the groups. Some groups start with an existing standard and adapt it based on requirements defined from use cases, others are created from first principles such as in an OGC Innovation Program initiative, and some are brought into the OGC from external communities.

Using the Model Driven Architecture (MDA) process is one approach to attempt to standardize generation of artifacts from conceptual and logical principles. MDA has been mainly used to generate data models for specific platforms from a common logical base. An oft-used strategy is to create a logical model, usually in the form of a UML Class diagram, and then put that model through a piece of software to generate a target output. An advantage to this approach is that the logical model is created once and maintained in a single place and the updated artifacts can be generated automatically for each physical model or implementation. However, the modeling can be complex and therefore unwieldy for all but a few experts with knowledge of the approach and process. Additionally, a typical MDA process starts with a UML class diagram.

This makes the assumption that the platform independent model is object-oriented (OO). In principle, the MDA approach can be used to save time and resources. However, MDA does require development upfront to generate the artifacts for a particular platform. Additionally, if there are changes to the target technology the code to generate the artifact for that platform may also have to be modified. One of the bottlenecks in MDA is the availability of code to generate suitable targets. Additionally, there are usually exceptions to generic rules in MDA. Therefore, targets have to be modified before they can be used.

7.1. Previous work

Using UML to model data structures and interface definitions is the original purpose of the MDA approach to architectures. This section does not provide a history of the use of MDA in geospatial technologies as this ER assumes that the reader is familiar with MDA.

This section presents the recent work done within OGC Testbeds and Pilots to provide a grounding for the decisions made in the OpenAPI Thread of Testbed-16.

The UML to GML Application Schema (UGAS) Pilot is the work that directly precedes the Testbed-16 OpenAPI activity. The output of that Pilot was an Engineering Report (https://portal.ogc.org/files/?artifact_id=95469&version=1) and a version of ShapeChange that was used in the OpenAPI thread of Testbed-16.

The UGAS Pilot sought to address four key issues with respect to JSON schemas:

  1. Refine the UML to JSON rules for the NSG wide UML application schema first established in OWS-9.

  2. Create JSON encodings for relevant conceptual schemas such as the ISO 19100 series of standards.

  3. Understand the utility of the Shapes Constraint Language (SHACL) for Resource Description Framework (RDF) documents and the transformation process from UML to JSON.

  4. A preliminary investigation into the utility of deriving OpenAPI 3.1 conformant JSON schemas using the MDA approach.

Points 1 and 4 are all relevant to the work done in Testbed-16 and are reviewed in the following paragraphs.

The UML application schema to JSON schema rules are primarily defined to convert application schemas, that is, a data model for a particular application to a JSON representation. The conversion rules are designed for a direct mapping between UML classes to JSON fragments without implementing inheritance in an object-oriented manner. The authors correctly point out that JSON schemas do not directly support the concept of inheritance, which can be managed through a virtual inheritance approach described in the ER. Additionally, as rules are enforced at the supertype level, but not the subtype level, JSON schema does not support class specialization. The approach to class specialization used in this (or UGAS?) was to extend a class data type to and include both in the JSON schema as both are part of the model. A different approach taken is to use a metamodel, model construct where the metamodel is abstract and the model and classes specialized from the generalized metamodel. This ER describes the completed initial work into deriving OpenAPI based interfaces from UML and identifies the building blocks that are required to produce a successful UML model. However, the participants in the UGAS activity did not attempt to produce a UML model to define the interface due to that work item being included in Testbed-16.

In Testbed 14, the participants in the application schema-based ontology development work activity attempted to express Web Ontology Language (OWL) in UML that could then be translated via an MDA process and ShapeChange into an Application Schema. This is a similar problem to the OpenAPI work described in this Testbed 16 ER but with a different target based upon different encoding rules. Essentially, the participants had similar challenges with how to express out of bounds information, much in the same way that conformance classes are used in OpenAPI to describe conformance to clients.

The Testbed-14 participants also wrote an ER that describes conversion of UML application schemas to JSON and JSON-LD (http://docs.opengeospatial.org/per/18-091r2.html). The authors identified several issues with conversion of application schemas to JSON that included: Lack of support of typical object-oriented concepts in JSON such as inheritance, lack of methods to verify schemas in JSON - notably the lack of the ability within JSON to identify its parent schema, and lack of support for other validation mechanisms such as namespaces. The MDA approach requires many of these concepts to either be directly available or to be virtualized. Therefore, many design decisions made in the modeling process were made to make up for these short comings.

One of the recommendations of this ER was to develop an extension to ShapeChange with the JSON schema target. Although this project was not designed to realize that goal, it did provide some lessons learned for would-be implementers that are discussed in a future section. The second recommendation was to develop JSON schemas for ISO schemas. This is a broader question that needs to be better understood. ISO separates their conceptual model standards from their encoding standards (ISO 19115-1:2014 and ISO/TS 19115-3:2016). JSON potentially needs the same treatment, which would have real-world implications for emerging OGC standards such as OGC API - Records as that in development API will serve metadata that is largely ISO derived.

OGC API – Features was the first OGC Web API Standard to be approved that uses OpenAPI to document the API based on the resource paradigm. As OGC API - Features was the first Web API to be approved by the OGC membership, it provides a template for other, new OGC API standards. OGC API - Features has several parts. At the time of Testbed 16, only OGC API - Features - Part 1 was approved. Therefore, Part 1 was considered in this Testbed 16 project as a case study. The structure of the Features API provides a foundation for other standards in the emerging OGC API suite. For example, OGC API - Records has the same structure as OGC API - Features but instead contains conformance classes such as FullTextQuery that allows for operations such as searching metadata records. An additional reason for using API Features is that the draft OGC API - Common uses many of the conformance classes in Features. Therefore, these classes will likely form the basis of the building blocks for future work in the OGC API suite of standards.

7.2. OpenAPI

The OpenAPI Specification (formerly Swagger Specification) is an API description format for APIs that implement principles of Representational State Transfer (REST). An OpenAPI file allows the developer to describe an entire API including: Available endpoints (/users) and operations on each endpoint (GET /users, POST /users), Operation parameters, and input and output for each operation, and so forth. The use of OpenAPI was experimented with during the development of OGC API Features. Based on that experience, the OGC Membership approved recommending the use of OpenAPI to document any OGC API standard either in development or in the future. OpenAPI provides a well-defined specification for documenting a structure and conformance rules to be adhered to when implementing an API. Additionally, there are many developer tools for generating an API document or stubbing code from an existing API document.

However, OpenAPI is not object-oriented and therefore modeling the OpenAPI specification within the UML class construct requires compensating for this issue. Many of the relationships between OpenAPI objects are straight forward, and can be represented using a simple composition or aggregation depending on the relationship. However, OpenAPI does contain more difficult constructs such as map types (aka dictionary - https://swagger.io/docs/specification/data-models/dictionaries/) in which key/value pairs are both variable. This is slightly more difficult to model in a UML class diagram that relies more upon simple attribute names and variable of fixed type. Additionally, OpenAPI contains arrays of types that need to be ordered, which also are difficult to represent.

Another feature of OpenAPI is that it inherits and extends JSON Schema in an object-oriented manner, but does not explicitly define JSON schema types in the specification. Therefore, a true UML model would also include all of the aspects of JSON schema and all of its extensions. While possible, this was considered out of scope in Testbed 16.

7.3. Model Driven Architecture (MDA)

MDA has been a recognized approach to artifact design and generation for decades. One of the motivating principles behind MDA is the approach to design and the ability to remain technology agnostic. MDA involves creating an initial model, called the Platform Independent Model (PIM) and then generating Platform Specific Models (PSM) automatically from the model. This provides several advantages including: Standardized documentation of artifacts, ability to change implemented technologies without changing the underlying model and the ability to extend the underlying model and quickly generate the artifacts required for implementation.

Generation of OGC API standards using the MDA approach is sensible as the new suite of OGC API standards utilize the same underlying model. Changes and extensions to the model are allowed. However, this can be done in a consistent and therefore controlled manner. The modeling language for the MDA approach is often UML class diagrams as they describe the class attributes, relationships and methods. This combination of entities allows the model to express both structure and behavior and is therefore suited to modeling APIs and associated data schemas.

MDA can also be used for interface definitions. However, MDA has also been used for data structure definitions using UML class diagrams. When employed for data definitions, the transformations are rather simplistic as it involves taking the PIM and transforming it into different versions of SQL rather than enforcing encoding rules used for an interface definition.

7.4. ShapeChange

To transform a UML representation of a model into a configuration file for a target platform, software is used to perform the translation and transformation. ShapeChange was the choice of software for this job in Testbed-16 as it has been utilized in previous Testbeds and Pilots and is mature enough to enable a lot of the functionality required. ShapeChange supports JSON schemas through the work completed in UGAS2020 Pilot and the version used in this project was the development branch taken from the recently concluded UML to GML Pilot as this Testbed thread essentially picks up where that piece of work left off.

ShapeChange connects directly to an Enterprise Architect (EA) model created using the EA (https://sparxsystems.com/) software. Through some configuration, it then takes the UML model and transforms it into ShapeChange XML (SCXML). The SCXML is the starting point for the development effort to convert the UML model into the chosen target, that is, the developer works only on the XML and manipulates it into the format required for the target. The target is then output from ShapeChange according to the rules applied to the SCXML.

8. OpenAPI Modeling

The OpenAPI component delivery has two main aspects to it: The UML model and the ShapeChange implementation. This section covers these aspects in turn with an initial focus on the design decisions made for the UML modeling exercise, and the ShapeChange implementation.

model tradeoff 1
Figure 1. The OpenAPI Main View

Overall, the design decisions were made to manage the trade-off between certain aspects of the project. These are as follows:

  • UML conformance - UML models are governed by an ISO standard and the usage of the different aspects of the modeling language is defined and controlled by said standard. Therefore, UML conformance is a requirement of the model, else it is not understandable by would-be users or ShapeChange.

  • Model usability - The model described was created with usability in mind, this includes aspects such as; consistency, readability, traceability and reuse of elements. This aspect was potentially the most challenging, as the OpenAPI specification is complex at times and geared towards JSON encodings that do not support typical OO constructs such as inheritance.

  • ShapeChange capabilities - UML models ingested in ShapeChange are converted to SCXML prior to being worked on by any implemented code and extension to ShapeChange. Therefore, implementing an extension to ShapeChange uses the SCXML representation as a baseline and any further implementation to ShapeChange’s capabilities starts with the SCXML representation of the UML model. An example of a shortcoming in ShapeChange is that whilst is recognizes association classes as entities, it does not recognize the connection that is made between the association class and the relationship it refers to. Therefore, any use of an association class is a challenge because SCXML does not specify the relationship it refers to.

  • Implementation time - OGC Testbeds are designed to understand ideas and produce proof of concept software as well as making recommendations for future work. The Minimum Viable Product (MVP) for this work is to create a UML model and ShapeChange implementation to produce a JSON encoding and representation of an OpenAPI interface. There are several out-of-scope items that include:

    • Validating models (beyond the model-metamodel relationship).

    • Enforcing OGC conventions such as conformance classes.

    • Producing a generic solution that covers all eventualities.

8.1. OpenAPI UML Models

As mentioned in the introduction, there is no authoritative UML model for OpenAPI that was suitable for the needs of the project. Therefore, a UML model was created from the OpenAPI documentation. Although the model represents the OpenAPI standard and guidance in the most accurate way possible, there is a trade-off between the following factors:

  • UML 'correctness' - the model is built in UML and should be compliant with the standard.

  • ShapeChange requirements and access to internal variables - ShapeChange needs access to the internal variables expressed in the UML model in order to implement them.

  • Aesthetic quality - the model needs to be logical and readable to encourage use.

The UML modeling described and completed in this thread is two-fold:

  • An OpenAPI metamodel created from the specification using the relationships and classes described.

  • a model that implements the metamodel, OGC API - Features - Part 1 Core.

This approach was chosen to provide future implementers with a metamodel that they could use as a reference for further OGC standard development and documentation.

8.2. OpenAPI UML metamodel

The OpenAPI metamodel was created from the OpenAPI specification version 3.0.2 and is presented as a set of classes that interact via relationships. OpenAPI is prescriptive about the majority of the OpenAPI objects and relationships. However it is not strictly OO. Therefore, interpretations and design decisions were made to represent OpenAPI as closely as possible whilst adhering to UML convention. An additional factor that influences the design of the model was the requirement to implement a plugin to ShapeChange to produce the OpenAPI document from the UML model using an MDA approach. This has a direct influence on the use of methods within UML, as ShapeChange currently does not recognize methods, therefore the operation call within OpenAPI would naturally sit as a method in a class diagram, but has been included as an attribute due to the shortcomings of ShapeChange. This section shows the views of the UML model as well as some of the design decisions taken.

The metamodel was designed with consistency as a key factor for determining success. For example, the Reference object could be presented as a String type with the name $ref and the value as the variable. From a ShapeChange implementation perspective, this would be the simplest option, as it would follow the typical key/value pairing. However, many reference objects are reused throughout the model and have rules enforced upon them. Therefore, from a UML perspective, implementing a Reference class is prudent so that the specializations of the Reference class can be acted upon accordingly. A similar approach was taken for the Map class, which is discussed later in this section.

The metamodel design process included the entire OpenAPI specification and was done as a reference for implementing classes and as a hook for the ShapeChange implementation. The OGC API - Features - Part 1: Core specialization only uses a subset of the metamodel, but the full model is available in the accompanying Enterprise Architect project.

8.2.1. OpenAPI Main view

Main
Figure 2. The OpenAPI Main View

The OpenAPI main view in Figure 2 shows the OpenAPI class as an entry point for the specification, it sits at the top level of the resultant OpenAPI document tree. The model follows the OpenAPI specification with relationships between the classes as compositions as the conceptual relationship between the classes is strong; in JSON when encapsulating brackets are destroyed, the inner contents of those brackets is also destroyed. This maybe a heuristic for modeling JSON in UML generally. The OpenAPI type is also straightforward in terms of its variables with each having a simplistic key, value or key and array of values paring.

8.2.2. OpenAPI Paths views