Mapping-OWL to OpenAPI Specification (OAS)¶

This document describes how to generate an OpenAPI Specification (OAS) from OWL.

Authors:

Paola Espinoza-Arias (Ontology Engineering Group, Universidad Politecnica de Madrid)
Daniel Garijo (Information Sciences Institute, University of Southern California)

Version: 1.0.0

Release date: 23/05/2020

Want to contribute?: Check out our GitHub repository

Introduction¶

This is a document defining how to translate OWL to OAS to allow developers to determine how ontologies may be represented as an interface descriptions for REST APIs. In this document you will find the similiarities between the two specifications a well as simple examples of how an ontology code is represented in the OAS.

Definitions from OAS¶

The following definitions from the OAS version 3.0.3 are a condensed version of the definitions of the specification. Only those definitions that will be used in the mapping section are briefly presented.

It is worth noting that the remaining definitions provided in OAS should be followed according to that specification.

Components Object¶

Holds a set of reusable objects for different aspects of the OAS. All objects defined within the Components Object will have no effect on the API unless they are explicitly referenced from properties outside the components object.

Paths Object¶

Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the Server Object in order to construct the full URL.

Path Item Object¶

Describes the operations available on a single path (get, put, post, among others). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available. To check more details provided in the OAS refer to Path Item Object.

Reference Object¶

A simple object to allow referencing other components in the specification, internally and externally. The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules. For OAS, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification.

Schema Object¶

The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object has several properties taken directly from the JSON shema definition, such as title, required, maximum, among others. In addition, this object manages other properies taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification, such as type, allOf, oneOf, etc.

Alternatively, any time a Schema Object can be used, a Reference Object can be used in its place. This allows referencing definitions instead of defining them inline. Other than the JSON Schema subset fields, the following fields MAY be used for further schema documentation: nullable, deprecated, readOnly, etc.

Data Types¶

Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00. In addition, primitives have an optional modifier property: format. OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the format property is an open string-valued property, and can have any value. Formats such as "email", "uuid", and so on, MAY be used even though undefined by this specification. Types that are not accompanied by a format property follow the type definition in the JSON Schema. Tools that do not recognize a specific format MAY default back to the type alone, as if the format is not specified.

Mapping between OWL and OAS¶

In this section the similiarities between OWL and OAS are provided. All mappings include examples provided in Turtle and YAML serializations for human-friendly readability. The code of both serializations as well as an ontology diagram are provided in examples. Also, the full example in the YAML serialization may be opened in the Swagger editor to be viewed as API documentation. A list with all the OWL constructs covered and those not covered by this mapping specification is provided in the OWLtoOAS Profile.

The prefixes that will be used in this section are:

@prefix : <https://w3id.org/example#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix xml: <http://www.w3.org/XML/1998/namespace> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix prov: <http://www.w3.org/ns/prov#> .

Class¶

A class will be treated as an object in OAS according to the Schema Object definition as it is explained in this section. However, it is worth noting that a class also must be included in API paths and operations, which will be explained later in this document.

OWL	OAS	Comments
`owl:Class`	`Schema Object`	It should be defined as a Schema Object in the Component Object definition. The `Schema Object` must be a`type: object`. The schema name should be the `rdfs:label` value defined in the OWL Class. It is worth noting that the name should not contain blank spaces. See example
Class axioms
`rdfs:subClassOf`	`allOf`	It should be defined as a model composition of the common property set and class-specific properties. Thus, a subclass should be defined as a Schema Object in the Component Object definition including the field `allOf`. Such field must include a `type: object` and the corresponding Reference Object to the parent class (`$ref`:'reference to the parent class'). Finally, the specific properties of the subclass should be defined in the `properties` field. See example

Class definition example¶

This example shows the definition of the Person class. However, its properties have been omitted because the details on how to define Data and Object properties will be provided in the next section.

TTL

:Person rdf:type owl:Class ;
rdfs:label "Person"@en.

YAML

components:
  schemas:
    Person:
      type: object

Back to the Class mapping

Subclass definition example¶

This example shows the definition of the Professor and Student subclasses. However, the specific properties of each subclass have been omitted because details on how to define Data and Object properties will be provided in the next section.

TTL

:Professor rdf:type owl:Class ;
    rdfs:subClassOf :Person ;
    owl:disjointWith :Student ;
    rdfs:label "Professor"@en .

:Student rdf:type owl:Class ;
    rdfs:subClassOf :Person ;
    owl:disjointWith :Professor ;
    rdfs:label "Student"@en .

YAML

components:
  schemas:
    Person:
      type: object
    Professor:
      allOf:
      - $ref: '#/components/schemas/Person'
      - type: object
    Student:
      allOf:
      - $ref: '#/components/schemas/Person'
      - type: object

Back to the Class mapping

Data Types¶

The similarities between data types are shown below.

OWL	OAS	Comments
`xsd:integer`	`integer`
`xsd:int`	`integer`	The `format` must be defined as `int32` (signed 32 bits)
`xsd:long`	`integer`	The `format` must be defined as `int64` (signed 64 bits)
`xsd:float`	`number`	The `format` must be defined as `float`
`xsd:double`	`number`	The `format` must be defined as `double`
`xsd:string`	`string`
`xsd:date`	`string`	The `format` must be defined as `date` (As defined by `full-date` - RFC3339)
`xsd:dateTime`	`string`	The `format` must be defined as `date-time` (As defined by `date-time` - RFC3339)
`xsd:dateTimeStamp`	`string`	The `format` must be defined as `date-time` (As defined by `date-time` - RFC3339)
`xsd:byte`	`string`	The `format` must be defined as `byte` (base64 encoded characters)
`xsd:anyURI`	`string`	The `format` must be defined as `uri`
`xsd:boolean`	`boolean`

Properties¶

A property will be treated as an object property in OAS according to the Schema Object definition. In this section, details on how to define data and object properties are presented.

OWL	OAS	Comments
`owl:DatatypeProperty`	`properties`	It should be defined as a property of the corresponding Schema Object instance, as aforementioned in the `owl:Class` mapping. The property name will be the `rdfs:label` value defined in the data property. It is worth noting that the name should not contain blank spaces. See example
`owl:ObjectProperty`	`properties`	It should be defined as a property of the corresponding Schema Object instance, as aforementioned in the `owl:Class` mapping. The property name will be the `rdfs:label` value defined in the object property. It is worth noting that the name should not contain blank spaces. See example
Property axioms
`rdfs:domain`	`Schema Object`	The domain of a property corresponds to the Schema Object that must include that property. Thus, it should be defined as a Schema Object inside of the Component Object definition, as explained in the `owl:class` mapping.
`rdfs:range`	`type`	a) when the range corresponds to an `owl:DatatypeProperty`: if the range is single-valued the `type` value should be the data type of the data property; else if the range is multi-valued the `type` value should be the data type of the data property and the possible values defined as an enumeration (`enum`). See example. b) when the range corresponds to an `owl:ObjectProperty`: if the range cardinality >=1 it should be defined as an array (`type: array`) and the `items` as a Reference Object (`$ref:`'reference to the Range Class'); else if the range cardinality <1 it could be defined as an array (`type: array`) and `items` as a Reference Object (`$ref:`'reference to the single Range Class') or only as an object (`type: object`) and a Reference Object (`$ref:`'reference to the single Range Class'). This last decision will depend on the developer's decision. See example
Property characteristics
`owl:FunctionalProperty`	`maxItems`	The property with this characteristic should be defined as an array (`type: array`) with 1 as the maximum number of items (`maxItems:` 1) and a) if it corresponds to an `owl:DatatypeProperty` the type of array items must be the data type of the property; b) if it corresponds to an `owl:ObjectProperty` the type of array items must contain a Reference Object to the range Class (`$ref:`'reference to the range Class'). See example

DatatypeProperty example¶

The following example presents how to define a Data Property of the Person class. A single-value and a multi-value ranges has been included to show how they look in OAS.

TTL

:identifier rdf:type owl:DatatypeProperty ;
  rdfs:domain :Person ;
  rdfs:range xsd:string ;
  rdfs:label "name"@en .

:gender rdf:type owl:DatatypeProperty ;
  rdfs:domain :Person ;
  rdfs:range [ rdf:type rdfs:Datatype ;
    owl:oneOf [ rdf:type rdf:List ;
      rdf:first "female" ;
      rdf:rest [ rdf:type rdf:List ;
        rdf:first "male" ;
        rdf:rest rdf:nil
        ]
      ]
    ] ;
  rdfs:label "gender"@en .

YAML

components:
  schemas:
    Person:
      type: object
      properties:
        name:
          type: string
        gender:
          type: string
          enum:
            - male
            - female
          nullable: true

In addition, the following example shows how to define a Data Property of the Professor subclass.

TTL

:researchField rdf:type owl:DatatypeProperty ;
    rdfs:domain :Professor ;
    rdfs:range xsd:string ;
    rdfs:label "research field"@en .

YAML

components:
  schemas:
    Person:
      type: object
      properties:
        name:
          type: string
        gender:
          type: string
          enum:
            - male
            - female
    Professor:
      allOf:
        - $ref: '#/components/schemas/Person'
        - type: object
      properties:
        researchField:
          type: string

Back to the Properties mapping

ObjectProperty example¶

The following example shows how to define an Object Property of the Professor class:

TTL

:teachesTo rdf:type owl:ObjectProperty ;
    rdfs:domain :Professor ;
    rdfs:range :Student ;
    rdfs:label "teaches to"@en .

YAML

components:
  schemas:
    Person: {...} #Rest of the schema omitted
    Professor:
      allOf:
        - $ref: '#/components/schemas/Person'
        - type: object
      properties:
        researchField:
          type: string
        teachesTo:
          items:
            $ref: '#/components/schemas/Student'
          type: array

Back to the Properties mapping

FunctionalProperty examples¶

This example shows how to define a Functional Data Property of the Person class.

TTL

:identifier rdf:type owl:DatatypeProperty , owl:FunctionalProperty ;
  rdfs:domain :Person ;
  rdfs:range xsd:string ;
  rdfs:label "identifier"@en .

YAML

components:
  schemas:
    Person:
      type: object
      properties:
        identifier:
          items:
            type: string
          type: array
          maxItems: 1

The next example shows how to define a Functional Object Property of the Student.

TTL

:hasRecord rdf:type owl:ObjectProperty , owl:FunctionalProperty ;
    rdfs:domain :Student ;
    rdfs:range :StudentRecord ;
    rdfs:label "has record"@en .

YAML

components:
  schemas:
    Person: {...} #Rest of the schema omitted
    Student:
      allOf:
        - $ref: '#/components/schemas/Person'
        - type: object
      properties:
        hasRecord:
          items:
            $ref: '#/components/schemas/StudentRecord'
          type: array
          maxItems: 1

Back to the Properties mapping

Restrictions¶

Depending on the restriction, it will be treated according to the details provided below.

OWL	OAS	Comments
`owl:onProperty`	`properties`	The restriction should refers to the property name where it is applied.
`owl:onClass`	`Schema Object`	The restriction should refers to the schema name where it is applied.
`owl:someValuesFrom`	`type` and `nullable`	The restricted property should be defined as a not null (`nullable: false`) array (`type: array`) and depending on the restriction a) when it is on an `owl:DatatypeProperty`the value of the items type should be the restricted data type; b) when it is on an `owl:ObjectProperty` the `items` should be a Reference Object to the restricted class (`$ref:`'reference to the restricted Class'). See example
`owl:allValuesFrom`	`type` and `nullable`	The restricted property should be defined as a nullable (`nullable: true`) array (`type: array`) and depending on the restriction a) when it is on an `owl:DatatypeProperty` the value of the items type should be the restricted data type; b) when it is on an `owl:ObjectProperty` the `items` should be a Reference Object to the restricted class (`$ref`:'reference to the restricted Class'). See example
`owl:hasValue`	`default`	It should be defined as a `default` value of the property. Depending on the restriction a) when it is on an `owl:DatatypeProperty` the property `type` should be the corresponding data type and the default value should be the specific literal value, b) when it is on an `owl:ObjectProperty` the property type should be a string (`type: string`) with `format: uri` and the default value should be the individual URI value. See example
`owl:minCardinality`	`minItems`	It should be defined as the minimum number of the array items which contains as Reference Object a scheme of the `owl:Thing` (`$ref:`'reference to the owl:Thing'). The value of `minItems` must be a non-negative number.
`owl:maxCardinality`	`maxItems`	It should be defined as the maximum number of the array items which contains as Reference Object a scheme of the `owl:Thing` (`$ref:`'reference to the owl:Thing'). The value of `maxItems` must be a non-negative number.
`owl:cardinality`	`minItems` and `maxItems`	It should be defined as the same minimum and maximum number of the array items which contains as Reference Object a scheme of the `owl:Thing` (`$ref:`'reference to the owl:Thing'). The value of `minItems` and `maxItems` must be a non-negative number.
`owl:minQualifiedCardinality`	`minItems`	It should be defined as the minimum number of array items and a) if it corresponds to an `owl:DatatypeProperty` the value of the items type must be the restricted data type; b) if it corresponds to an `owl:ObjectProperty` the array items must contain the Reference Object to the restricted Class (`$ref:`'reference to the restricted Class'). The value of `minItems` must be a non-negative number. See example
`owl:maxQualifiedCardinality`	`maxItems`	It should be defined as the maximum number of array items and a) if it corresponds to an `owl:DatatypeProperty` the value of the items type must be the restricted data type; b) if it corresponds to an `owl:ObjectProperty` the array items must contain the Reference Object to the restricted Class (`$ref:`'reference to the restricted Class'). The value of `maxItems` must be a non-negative number. See example
`owl:qualifiedCardinality`	`minItems` and `maxItems`	It should be defined as the same minimum and maximum number of array items and a) if it corresponds to an `owl:DatatypeProperty` the value of the items type must be the restricted data type; b) if it corresponds to an `owl:ObjectProperty` the array items must contain the Reference Object to the restricted Class (`$ref:`'reference to the restricted Class'). The value of `minItems` and `maxItems` must be a non-negative number. See example

someValuesFrom example¶

This example shows how to represent that Professor teaches some Courses.

TTL

:Professor rdf:type owl:Class ;
  rdfs:subClassOf :Person ,
    [ rdf:type owl:Restriction ;
      owl:onProperty :teachesCourse ;
      owl:someValuesFrom :Course
    ] .

YAML

components:
  schemas:
    Person: {...} #Rest of the schema omitted
    Professor:
      allOf:
        - $ref: '#/components/schemas/Person'
        - type: object
      properties:
        teachesCourse:
          items:
            $ref: '#/components/schemas/Course'
          type: array
        nullable: false

Back to the Restrictions mapping

allValuesFrom example¶

This example shows how to represent that a Professor teaches to only Students.

TTL

:Professor rdf:type owl:Class ;
  rdfs:subClassOf :Person ,
    [ rdf:type owl:Restriction ;
      owl:onProperty :teachesTo ;
      owl:allValuesFrom :Student
    ] .

YAML

components:
  schemas:
    Person: {...} #Rest of the schema omitted
    Professor:
      allOf:
        - $ref: '#/components/schemas/Person'
        - type: object
      properties:
        teachesTo:
          items:
            $ref: '#/components/schemas/Student'
          type: array
        nullable: true

Back to the Restrictions mapping

hasValue example¶

This example presents how to represent that an American Student has an American nationality.

TTL

:AmericanStudent rdf:type owl:Class ;
  rdfs:subClassOf :Student ,
    [ rdf:type owl:Restriction ;
      owl:onProperty :nationality ;
      owl:hasValue "American"
    ] .

YAML

components:
  schemas:
    Student: {...} #Rest of the schema omitted
    AmericanStudent:
      allOf:
        - $ref: '#/components/schemas/Student'
        - type: object
      properties:
        nationality:
          type: string
          default: "American"

In addition, imagine that the nationality property would have been defined as an owl:ObjectProperty therefore the American Student's nationality property should have been described with a default value corresponding to the individual URI as follows:

TTL

:AmericanStudent rdf:type owl:Class ;
  rdfs:subClassOf :Student ,
    [ rdf:type owl:Restriction ;
      owl:onProperty :nationality ;
      owl:hasValue <http://example.org/resource/nationality/American>
    ] .

YAML

components:
  schemas:
    Student: {...} #Rest of the schema omitted
    AmericanStudent:
      allOf:
        - $ref: '#/components/schemas/Student'
        - type: object
      properties:
        nationality:
          type: string
          format: uri
          default: http://example.org/resource/nationality/American

Back to the Restrictions mapping

minQualifiedCardinality example¶

This example shows how to represent that a Student should take minimum 2 Courses.

TTL

:Student rdf:type owl:Class ;
  rdfs:subClassOf :Person ,
    [ rdf:type owl:Restriction ;
      owl:onProperty :takesCourse ;
      owl:minQualifiedCardinality "2"^^xsd:nonNegativeInteger ;
      owl:onClass :Course
    ]  .

YAML

components:
  schemas:
    Person: {...} #Rest of the schema omitted
    Student:
    allOf:
    - $ref: '#/components/schemas/Person'
    - type: object
      properties:
        takesCourse:
          type: array
          items:
            $ref: '#/components/schemas/Course'
          minItems: 2

Back to the Restrictions mapping

maxQualifiedCardinality example¶

This example shows how to represent that a Course should have enrolled maximum 20 Students.

TTL

:Course rdf:type owl:Class ;
  rdfs:subClassOf [ rdf:type owl:Restriction ;
    [ rdf:type owl:Restriction ;
      owl:onProperty :hasStudentEnrolled ;
      owl:maxQualifiedCardinality "20"^^xsd:nonNegativeInteger ;
      owl:onClass :Student
    ] .

YAML

components:
  schemas:    
    Course:
      properties:
        hasStudentEnrolled:
          items:
            $ref: '#/components/schemas/Student'
          type: array
          maxItems: 20

Back to the Restrictions mapping

qualifiedCardinality example¶

This example shows that a Student has exactly 1 Student Record.

TTL

:Student rdf:type owl:Class ;
  rdfs:subClassOf :Person ,
  [ rdf:type owl:Restriction ;
    owl:onProperty :hasRecord ;
    owl:qualifiedCardinality "1"^^xsd:nonNegativeInteger ;
    owl:onClass :StudentRecord
  ]  .

YAML

components:
  schemas:
    Person: {...} #Rest of the schema omitted
    Student:
      allOf:
        - $ref: '#/components/schemas/Person'
        - type: object
      properties:
        hasRecord:
          type: array
          items:
            $ref: '#/components/schemas/StudentRecord'
          minItems: 1
          maxItems: 1

Back to the Restrictions mapping

Boolean combinations¶

In this section some complex combinations allowed in OWL are presented in the OAS.

OWL	OAS	Comments
`owl:intersectionOf`	`allOf`	It should be defined as `allOf` which validates the value against all the subschemas. See example
`owl:unionOf`	`anyOf`	It should be defined as `anyOf` which validates the value against any (one or more) the subschemas. See example
`owl:complementOf`	`not`	It should be defined as `not` which validates the value is not valid against the specified schema See example
`owl:oneOf`	`enum`	It should be defined as an `enum` and the values included in this enumeration list. See example

IntersectionOf example¶

This example shows how to represent that a Professor in Artificial Intelligence must be a Professor and belongs to the Artificial Intelligence Department.

TTL

:ProfessorInArtificalIntelligence rdf:type owl:Class ;
  rdfs:subClassOf [ owl:intersectionOf ( :Professor
    [ rdf:type owl:Restriction ;
      owl:onProperty :belongsTo ;
      owl:hasValue <https://w3id.org/example/resource/Department/ArtificialIntelligenceDepartment> ]
    ) ;
    rdf:type owl:Class
  ] .

YAML

components:
  schemas:
    Professor: {...} #Rest of the schema omitted
    ProfessorInArtificalIntelligence:
      allOf:
        - $ref: '#/components/schemas/Professor'
      properties:
        belongsTo:
          type: string
          format: uri
          default: https://w3id.org/example/resource/Department/ArtificialIntelligenceDepartment

Back to the Boolean combinations mapping

UnionOf example¶

This example shows how to represent that a Student will be enrolled in any of the Student Programs listed. Note that in this example is also represented the owl:someValuesFrom restriction on the enrrolledIn property.

TTL

:Student rdf:type owl:Class ;
  rdfs:subClassOf :Person ,
    [ rdf:type owl:Restriction ;
      owl:onProperty :enrolledIn ;
      owl:someValuesFrom [ rdf:type owl:Class ;
        owl:unionOf ( :BachelorProgram
          :MasterProgram
          :PhDProgram
        )
      ]
    ] .

YAML

components:
  schemas:
    Person: {...} #Rest of the schema omitted
    Student:
      allOf:
      - $ref: '#/components/schemas/Person'
      - type: object
      properties:
        enrolledIn:
          type: array
          items:
            type: object
            anyOf:
            - $ref: '#/components/schemas/MasterProgram'
            - $ref: '#/components/schemas/PhDProgram'  
            - $ref: '#/components/schemas/BachelorProgram'
      required:
        - enrolledIn

Back to the Boolean combinations mapping

ComplementOf example¶

This example shows how a Professor in Other Department is not a Professor In Artifical Intelligence.

TTL

:ProfessorInOtherDepartment rdf:type owl:Class ;
  rdfs:subClassOf
    [ rdf:type owl:Class ;
      owl:complementOf :ProfessorInArtificalIntelligence
  ] ;

YAML

components:
  schemas:
    ProfessorInArtificalIntelligence: {...} #Rest of the schema omitted
    ProfessorInOtherDepartment:
      not:
        type: object
        $ref: '#/components/schemas/ProfessorInArtificalIntelligence'

Back to the Boolean combinations mapping

OneOf example¶

This example shows how to represent the gender data property as a enumeration.

TTL

:gender rdf:type owl:DatatypeProperty ;
  rdfs:domain :Person ;
  rdfs:range [ rdf:type rdfs:Datatype ;
    owl:oneOf [ rdf:type rdf:List ;
      rdf:first "female" ;
      rdf:rest [ rdf:type rdf:List ;
        rdf:first "male" ;
        rdf:rest rdf:nil
        ]
      ]
    ] .

YAML

components:
  schemas:
    Person:
      type: object
      properties:
        gender:
          type: string
          enum:
            - male
            - female
          nullable: true

Back to the Boolean combinations mapping

Paths and Operations¶

Paths¶

Paths in OAS are resources that the API exposes therefore its similiarity with OWL are classes represented in the following manner:

OWL	OAS	Comments
`owl:Class`	`/{path}`	A class should be defined as a path (`/{path}`); following the Path Item Object format. The `{path}` value should be defined according to the Path Naming Strategy.

Path example

The following example corresponds to the path definition of the Professor class. In this case we use the label value (rdfs:label) to name the path. This value has been defined as plural and lowercase.

TTL

:Professor rdf:type owl:Class ;
rdfs:label "Professor"@en.

YAML

paths:
  /professors:

The next example shows the path definition of the StudyProgram class. In this case we use the label value (rdfs:label) to name the path. This value has been defined as plural and lowercase. We also use a hyphen delimiter because the label value is composed by several words.

TTL

:StudyProgram rdf:type owl:Class ;
rdfs:label "Study Program"@en.

YAML

paths:
  /study-programs:

The last part regarding to Paths is the Path Templating which allows using template expressions in curly braces {} to mark a section of a URL path as replaceable using path parameters.

Operations¶

Operations in OAS are the HTTP methods used to manipulate these paths. Such operations are defined in Path Item Objects as Operation Objects. It is worth mentioning that a single path can support multiple operations but only one instance of them, for example it is allowed to define only one GET an only one POST for the same path.

Each operation should deal with a response or request that contains the returned or requested resources from executing the operation according to the details described below.

OWL	OAS	Comments
`owl:Class`	`schema`	If the operation is a GET, the class should be defined as part of the Response Object and as a Reference Object of the `schema`. In addition, if the operation is a POST or PUT it must be included as part of the Request Body Object and as a Reference Object of the `schema`.

Next, some basic examples about get and put operations are provided. For simplicity the response of the 200 HTTP status code is show together with the content defined as application/json media type. In OAS further details about all supported HTTP codes and Media Types are provided.

Operation examples

This example shows the get operation to retrieved all instances of a class. Note that only the Response Object is included; however, other fields (e.g. parameters) not presented in this example may be added such as described in the Operation Object definition.

/classlabel:
  get:
    responses:
      '200'
      description: A message describing the result of the operation.
      content:
        application/json:
          schema:
            items:
              $ref: ‘#/components/schemas/ClassLabel’
            type: array

The next example shows the get operation to retrieve an instance of a class by id. Note that in this case the response corresponds to a single instance of the class instead of an array of items of the class as was presented in the previous example.

/classlabel/{id}:
  get:
    parameters:
     - description: Filter by resource id
       in: path
       name: id
       required: true
       schema:
         type: string
    responses:
      '200'
      description: A message describing the result of the operation.
      content:
        application/json:      
          schema:
            $ref: ‘#/components/schemas/ClassLabel’

In addition, the put operation to create a new instance of a class is presented.

/classlabel:
  put:
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClassLabel'
    responses:
      '200':
        description: A message describing the result of the operation.

Finally, the following examples show the aforementioned operations for the Professor class.

/professors:
  get:
    responses:
      '200':
        description: The list of Professor has been retrieved successfully
        content:
          application/json:
            schema:
              items:
                $ref: ‘#/components/schemas/Professor’
              type: array
  put:
    description: Create a new instance of Professor
    requestBody:
      description: A new Professor to be created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Professor'
    responses:
      200:
        description: Professor created successfully

/professors/{id}:
  get:
    parameters:
     - description: Filter by resource id
       in: path
       name: id
       required: true
       schema:
         type: string
    responses:
      '200':
        description: The Professor has been retrieved successfully
        content:
          application/json:
            schema:
              $ref: ‘#/components/schemas/Professor’

Ontology metadata¶

In this section the mapping between the most common annotation properties describing OWL ontologies and the OAS specification is presented.

OWL	OAS	Comments
`dcterms:title`	`title`	The annotation value should used in the `title` field of Info Object.
`rdfs:label`, `skos:label`	`Schema Object`'s name	The annotation value should be applied in the Schema Object as the name of the corresponding class or property. Note that name is not an OAS keyword for the `Schema Object`, but it is provided as a way to make sense to that similiarity. Please, refer to the Schema Objects naming strategy to see further details on how to do it. In addition, the label value may be used in the Operation Object as the value of the `tags` field. Tags can be used for logical grouping of operations by resources or any other qualifier.
`rdfs:comment`, `dcterms:description`, `prov:definition`, `skos:definition`	`description`	These annotations should be applied in the Schema Object as a string description of the corresponding class or property.

Note that due to the aforementioned annotation properties are usually included in several languages (e.g. xml:lang="en") it will be necessary to specify what language will be used in the OAS. This decision will depend on the developer.

Path naming strategy¶

In REST APIs a clear strategy on how to define resource URIs is defined. Therefore, in the OAS this strategy should be adopted in order to be consistent with the REST API paradigm. Summarizing, the main rules on how resource URIs should be structured are: - Use a slash separator to indicate a hierarchical relationship. - Use hyphens instead of underscores to delimit words. - Use lowercase letters in URI paths. - Use plural for naming collections.

Regarding this mapping, when the label annotation (rdfs:label, skos:label) of the ontology class is available the aforementioned rules should be adopted when translating the label value to the corresponding Path Item name.

However, in those cases where label annotations are not included in the ontology it will be necessary to adopt other naming strategy for Paths Items. The alternative strategy may be taking the term name from the ontology term path, e.g. http://w3id.org/example/def/#term_name. In this solution it is important to consider that the resource naming strategy in ontologies is not made in a standardized way and the only the rule is to keep it consistent, whichever is chosen. As a result, two cases may happen:

Meaningful URIs, where ontology classes and properties have natural language names. For example, following a UpperCamelCase format.
Opaque URIs, where ontology classes and properties have obfuscated names. For exmaple, using specific codes.

In the first case, the REST API naming strategy may be followed in the same manner as the label translation to the corresponding Path Item. In the second case, this strategy may not be useful because a human being looking at the schema or path can not figure out what is on the other end. Thus, developers should name the Path Item is such a manner that conveys an understandable REST API’s resource to its potential client developers instead of the opaque design.

Schema Objects naming strategy¶

The Schema Objects naming may include objects and properties and, as the case of Path Items, when the label annotation (rdfs:label, skos:label) of the ontology class/property is available the label value must be used to name them. To this end, blank spaces must be removed and depending on the developer's decision the names may follow, for example, a UpperCamelCase structure to name objects and a lowerCamelCase to name properties. Remember that these names must be in singular.

However, in those cases where label annotations are not included in the ontology it will be necessary to adopt other naming strategy for Schema Objects. The alternative strategy may be taking the term name from the ontology term path, e.g. http://w3id.org/example/def/#term_name. This strategy might involve two cases that may be solved according as follows: 1. Meaningful URIs, in this case the naming strategy may be followed in the same manner as the label value translation to the corresponding Schema Object. 2. Opaque URIs, in this case developers should name the Path Item is such a manner that conveys an understandable REST API’s resource to its potential client developers instead of the opaque design.

OWLtoOAS Profile¶

The subset of the constructs that can be used in a conforming ontology is:

Existential quantification to a class expression (ObjectSomeValuesFrom) or a data range (DataSomeValuesFrom)
Universal quantification to a class expression (ObjectAllValuesFrom) or a data range (DataAllValuesFrom)
Existential quantification to an individual (ObjectHasValue) or a literal (DataHasValue)
Enumerations involving a single individual (ObjectOneOf) or a single literal (DataOneOf)
Intersection of classes (ObjectIntersectionOf)
Intersection of data ranges (DataIntersectionOf)
Union of classes (ObjectUnionOf)
Class negation (ObjectComplementOf)
Data range negation (DataComplementOf)
Class inclusion (SubClassOf)
Domain restrictions (ObjectPropertyDomain and DataPropertyDomain) and range restrictions (ObjectPropertyRange and DataPropertyRange)
Functional data properties (FunctionalDataProperty) and object properties (FunctionalObjectProperty)
Cardinality restrictions (ObjectMaxCardinality, ObjectMinCardinality, ObjectExactCardinality, DataMaxCardinality, DataMinCardinality, and DataExactCardinality)

In addition, the following constructs are not supported in the OWLtoOAS specification:

Self-restriction (ObjectHasSelf)
Class equivalence (EquivalentClasses)
Class disjointness (DisjointClasses)
Disjoint properties (DisjointObjectProperties and DisjointDataProperties)
Object property inclusion (SubObjectPropertyOf) with or without property chains, and data property inclusion (SubDataPropertyOf)
Property equivalence (EquivalentObjectProperties and EquivalentDataProperties
Transitive object properties (TransitiveObjectProperty)
Reflexive object properties (ReflexiveObjectProperty)
Irreflexive object properties (IrreflexiveObjectProperty)
Inverse object properties (InverseObjectProperties)
Inverse-functional object properties (InverseFunctionalObjectProperty)
Symmetric object properties (SymmetricObjectProperty)
Asymmetric object properties (AsymmetricObjectProperty)
Assertions (SameIndividual, DifferentIndividuals, ClassAssertion, ObjectPropertyAssertion, DataPropertyAssertion, NegativeObjectPropertyAssertion, and NegativeDataPropertyAssertion)
Keys (HasKey)

Limitations¶

It is worth noting that complex boolean combinations are not supported by the mapping. Some of these cases are:

subclass of the intersection between a class and the negation of other class: ClassA rdfs:subClassOf (ClassB owl:intersectionOf (owl:complementOf ClassC)), e.g. Childless Person is a Person who is not a Parent.
Complex range restrictions on a property such as the union of two intersections: (ClassA owl:intersectionOf ClassB) owl:unionOf (ClassC owl:intersectionOf ClassD)