Minimally Invasive Semantification of Light Weight Service Descriptions

Unification and automation of RESTful web services' documentation and descriptions is currently receiving increasing attention. The open-source OpenAPI Specification (formerly known as Swagger) has become core of this effort and has been adopted by a number of major companies. It allows the description of RESTful web services using objects represented in JSON or YAML file formats. As a result, the created descriptions are human and machine-readable, but not machine-understandable. In this paper, we propose a nonintrusive approach for the addition of semantic annotations (similar to RDFa and JSON-LD for HTML) to specific fields of the OpenAPI Specification. We created a lightweight vocabulary for describing RESTful web services using this specification. Furthermore, we practically demonstrate how OpenAPI objects can be enriched with semantic descriptions in a minimally invasive way by adding URIs in the values of chosen OpenAPI properties.