OpenAPI literalData only String, inlineValue/referenceValue cannot specify uom / format; Merge complexData and literalData?

[jerstlouis]

While working on Workflows extension, we realized that literalData could only be string, while inlineValue/referenceValue did not allow specifying uom or format. The distinction between literalData vs. inlineValue is also not clear.

We're seeing potential to simplify the definition if we want to allow this extra flexibility by merging complexData and literalData, as we have done here:

https://app.swaggerhub.com/apis/jerstlouis/MOAW/MOAW-0.2#/inlineOrRefData

        inlineOrRefData:
          type: object
          properties:
            dataType:
               $ref: "#/components/schemas/nameReferenceType"
            uom:
               $ref: "#/components/schemas/nameReferenceType"
            format:
               $ref: "#/components/schemas/format"
            href:
              type: string
            value:
              oneOf:
                 - type: string
                 - type: number
                 - type: boolean
                 - type: object
          oneOf:
           - required: [href]
           - required: [value]

[christophenoel]

As discussed in another issue, the input and output definitions should be adapted from the XML paradigm to the new JSON schema world.
(disclaimer: i'm not talking about converting the whole process description as suggested during OGC Hackaton 2019, but only modify the input/output definitions)

Thus, I strongly recommend to review those schema and use JSON schema properties as follows for defining inputs/outputs. Major mappings would be as follows:

• Type:
  -- For literal: use type and format from JSON schema: string, integer, number (for decimal, double and float), boolean and new types: date, password, URI
  -- For complex: for JSON use type object , for others use type binary combined with mimeType extension
• Title: use the JSON scherma title property
• Abstract: use the JSON schema description property
• Min/maxOccurs: use minItems/maxItems from JSON schema (combined with type array)
• Constraints: use minum, maximum (for range),enum (for allowed values), default (for default value), and new expressions: multipleOf, min/maxLength, pattern, uniqueItem from JSON schema
• Metadata: use externalDocs from JSON schemas
• AdditionalProperties: define an x-properties extension
• etc.

This might be achieved by merging literal/complex or not. (If you merge the definition of literal/complex, the specificification will have to state the inputs with binary type can be provided by reference (url) and JSON object can be provided inline or by reference).

Some examples:

1. FIle input:

          inputImage:
            title: 'my input image'
            description: 'abstract of my input image'
            type: binary
            properties:
            x-mimeType:
                 - 'image/png'
            x-context:
              - offering:
                code: "http://www.opengis.net/spec/owc-atom/1.0/req/wms"
                operation:
                  - code: "GetMap"
                    method: "GET"
                    href: "http://acme.org/wms?REQUEST=GetMap&SRS=EPSG:4326&BBOX=3.5,-1.3,34,-1.8"

2. Integer input with some constraints:

          inputCustom:
            type: integer
            minimum: 1
            maximum: 100
            default: 20

[christophenoel]

See the Schema Object definition at : https://swagger.io/specification/#schema-object

[bpross-52n]

The respective changes should be merged now.