Metadata (OpenAPI specification)

All HTTP API/IP resources are fully documented using OpenAPI (fka Swagger) specifications. Those specifications can be retrieved from a live system. The system uses Open API Specification 3.0. The details for the specifications can be found at xref: Swagger Specification

OpenAPI Concepts

The specification describes a REST API completely: URI, HTTP methods, HTTP status code, payloads: all are defined. See this trimmed example below (in JSON):

{
    "openapi": "3.0.1",
    "info": {
        "title": "integrations",
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "http://127.0.0.1:8080/oig/api/generic/"
        }
    ],
    "security": [
        {
            "BasicAuth": []
        }
    ],
    "paths": {
        "/integrations/{id}": {
            .. more paths
        }
    },
    "components": {
        "schemas": {
            "integration": {
                "required": [
                    "code",
                    "type",inher
                    "enabled",
                    "descr"
                ],
                "type": "object",
                "properties": {.. more properties and schemas},
                "securitySchemes": {
                    "BasicAuth": {
                        "type": "http",
                        "name": "BasicAuth",
                        "scheme": "basic"
                    }
                }
            }
        }
    }
}

This specification can be broken down into 3 parts:

  1. a summary section with generic information about the API: "info", "servers", "security".

  2. The "paths" section that describes the supported URI’s and HTTP methods

  3. The "components/schemas" part that defines object types/payloads. Those schemas in most cases will be representation of Oracle Health Insurance Objects / Entities.

This guide assumes knowledge about OpenAPI / Swagger to be present.

Paths

The paths defined for the Http IP in Oracle Health Insurance Applications, the swagger also includes links to a create-form or edit-form if it applies. If the path/operation defined in swagger is a POST/PUT/PATCH http method and requires a payload to be sent in, the operation in swagger definition will also include a link to the respective create-form or edit-form:It will be included as property x-create-form or x-edit-form.

Example:

"/purge/technicaldata": {
  "post": {
    "summary": "Requests the purge of technical data.",
 "operationId": "purgetechnicaldata",
 "requestBody": {
      "content": {
        "application/xml": {
          "schema": {
            "$ref": "[host-url]purge/technicaldata/definition#/purgeTechnicalData"
 }
        },
 "application/json": {
          "schema": {
            "$ref": "[host-url]purge/technicaldata/definition#/purgeTechnicalData"
 }
        },
 "application/vnd.oracle.insurance.resource+xml": {
          "schema": {
            "$ref": "[host-url]purge/technicaldata/definition#/purgeTechnicalData"
 }
        },
 "application/vnd.oracle.insurance.resource+json": {
          "schema": {
            "$ref": "[host-url]purge/technicaldata/definition#/purgeTechnicalData"
 }
        }
      },
 "description": "The input details for purge of technical data.",
 "x-create-form": "[host-url]purge/technicaldata/create-form"  }

Metadata Resources

The OpenAPI specification as a whole is represented by an Oracle Health Insurance schema resource. The schema resource may include or reference one or more schemas.

A included schema is part of the metadata resource itself and shown under "components/schemas". In this example, this array contains objects of type "title" which is defined under "components/schemas":

"items": {
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/title"
  }
}
...
"components": {
    "schemas": {
       "title": {
         "type": "object",
          "required": [
            "active"
...other required attributes
           ],
           "properties": {
             "active": {
               "type": "boolean"
              },
             "code": {
               "type": "string",
               "maxLength": 30
             }
          }
       }
  }
}

A reference to an external schema may look like this:

"type": "array",
"items": {
  "$ref": "http://[hostName]:[portNumber]/[api-context-root]/generic/policies/definition#/policies"
}

Definition Resource

Typically, a definition resource looks like this:

{
  "properties": {
    "": {
       ... attributes of property 1 here
    },
    "": {
       ... attributes of property 2 here
    },
...
    "": {
       ... attributes of property n here
    }
  },
  "required": [
    "", ""..., ""  ]
}

The attributes of a property may differ per property type and are described below.

Dynamic field specific metadata

When defining a dynamic field, a few indicators can be set. Those are included in the metadata definition as custom properties starting with "x-oi".

Number format type is included if set (can only be done for numeric dynamic fields):

"": {
  "type": "integer",
  "minimum": -9|99|999|9...
  "maximum": 9|99|999|9...
  "x-oi-dyn-number-format": "Amount|Number|Integer|FormattedInteger"
}

The "search" indicator is included:

"": {
  "type": "string",
  "maxLength":
  "x-oi-searchable": "true|false"
}

The "unique" indicator is included:

"": {
  "type": "string",
  "maxLength":
  "uniqueItems": "true|false"
}

Character fields

For each character field (either fixed or dynamic), a property is present in the metadata like this:

"": {
  "type": "string",
  "maxLength":
}

Example:

"code": {
  "type": "string",
  "maxLength": 30,
}

Integer fields

For each integer field (either fixed or dynamic), there is a property present in the metadata like this:

"": {
  "type": "integer",
  "minimum": -9|99|999|9...,
  "maximum": 9|99|999|9...
}

A dynamic field is an integer if the field type is numeric and the number format type is I(nteger) or F(ormatted Integer). The maximum is derived from the field definition.

Number fields

For each number field not being an integer (either fixed or dynamic), there is a property present in the metadata like this:

"": {
  "type": "number",
  "minimum": "-9|9.99|999.9999|9...99.9...9"
  "maximum": "9|9.99|999.9999|9...99.9...9"
}

A dynamic field is an number if the field type is numeric and the number format type is N(umber).

Money fields

For money fields (fixed fields only, dynamic money fields do not exist), there is a property present in the metadata like this:

"": {
  "type": "object",
  "properties": {
    "currency": {
      "type": "string"
    },
    "value": {
      "type": "number"
      "minimum": ""
      "maximum": ""
    }
  }

Date fields

For each date field (either fixed or dynamic), there is a property present in the metadata like this:

"": {
  "type": "string",
  "format": "date",
}

Datetime fields

For each datetime field (either fixed or dynamic), there is a property present in the metadata like this:

"": {
  "$ref": "#/components/schemas/timestampobject"
}

"timestampobject" is defined as:

"components": {
  "schemas" : {
  "timestampobject": {
    "type": "object",
    "required": [
      "value"
    ],
    "properties": {
      "timezone": {
        "type": "string"
      },
      "value": {
        "type": "string",
        "format": "date-time"
      }
    }
  }
}
}

Boolean Fields

For each boolean field (only fixed, dynamic fields of type boolean do not exist), there is a property present in the metadata like this:

"": {
  "type": "boolean"
}

Domain Fields

For each domain based field (only fixed, dynamic fields based on a domain do not exist), the enum keyword is added:

"": {
  "type": "string",
  "title": ""
  "enum": "",
  "x-oi-meaning": [],
}

Example:

"status": {
  "type": "string",
  "title": "ClaimStatus",
  "enum": ["INITIAL", "CHANGE", "FINALIZED"],
  "x-oi-meaning": ["Initial", "Change", "Finalized"],
}

The "enum" array contains the list of allowable values that can be used for this domain based field. "x-oi-meaning" gives the associated human readable domain meanings in the language of the current user.

Reference Fields

For each field referencing another object/entity, there is a ref present to point to the definition of the referenced property

"": {
  "$ref": "http://[hostName]:[portNumber]/[api-context-root]/generic//definition#/"
}

Please note, that these are available for every property kind except for reference properties, that is the properties that only have a $ref. This is due to specification limitation on not being able to include these extensions on reference based properties. This is overcome by providing an extension on the main resource for reference based properties. The extension used is : 'x-oi-ref-properties' and it contains a map structure for all reference fields along with their relevant characteristics, like, resource name, updatable, insertable, readonly etc. PLease also note, that if a non-updatable or non-insertable property is sent in a payload, it is ignored.

  • x-oi-resource-name: Refers to the resource name of the super resource, in case it is needed to fetch the main metadata of it from the generic discoverable url itself.

  • x-oi-insertable: If a property is not insertable, this attribute will be included in metadata with value false.

  • x-oi-updatable: If a property is not updatable, this attribute will be included in metadata with value false.

  • readOnly: If a property is not insertable and is not updatable, this attribute will be included in metadata with value true. The above two will NOT be included in this case.

"x-oi-ref-properties" : {
  "bloodGroup" : {
    "x-oi-resource-name" : "testbloodgroups"
  },
  "parent" : {
    "x-oi-updatable" : false,
    "x-oi-resource-name" : "testentities"
  },
  "contact" : {
    "x-oi-resource-name" : "testcontacts"
  },
  "contact2" : {
    "x-oi-resource-name" : "testcontacts"
  }
}

Non Reference Fields with pickup values

If a resource has a a plain property that is not an actual reference, but its values are can only be a subset of a pickup list coming from another resource. It is included in the metadata using 'x-oi-reference-link'.

"credentialKey": {
  "maxLength": 50,
  "type": "string",
  "xml": {
     "attribute": true
   },
   "x-oi-reference-link": "<<enviroment>>/oig-ws/api/credentials"
}

Inheritance based fields

If a resource has property that is inheritance based and can have one of the possible subtypes of the inheritance structure, the metadata includes the information using a composed schema and detailing every schema reference that is possible for such a property. It also mentions the discriminator property and its respective mapping with the schemas.

Along with the above, there are two Oracle Health Insurance specific properties that are present in the metadata of inheritance based fields

  • x-oi-super-resource-link: Refers to the link of the definition of the super resource in context of the main resource which the metadata is given. This can be helpful to get information on the super resource of the inheritance based resources to show a common page or to query on. IN the example integrationSteps is the property of integrations resource and this link will refer to the metadata on integrationSteps in the scope of integrations.

  • x-oi-resource-name: Refers to the resource name of the super resource, in case it is needed to fetch the main metadata of it from the generic discoverable url itself.

"integrationSteps": {
    "type": "array",
    "xml": {
      "name": "integrationSteps",
      "wrapped": true
    },
    "items": {
      "xml": {
        "name": "baseIntegrationStep"
      },
      "discriminator": {
        "propertyName": "subtype",
          "mapping": {
            "QUERY": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/querysteps/definition#/querystep",
            "PROCESS": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/processsteps/definition#/processstep",
            "CUSTOM": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/customsteps/definition#/customstep",
            "SUBFLOW": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/subflowsteps/definition#/subflowstep",
            "TRANSFORM": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/transformsteps/definition#/transformstep",
            "ACTIVITY": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/activitysteps/definition#/activitystep",
            "EXTRACT": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/extractsteps/definition#/extractstep",
            "DELIVERY": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/deliverysteps/definition#/deliverystep"
          }
      },
      "oneOf": [
        {
          "$ref": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/transformsteps/definition#/transformstep"
        },
        {
          "$ref": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/deliverysteps/definition#/deliverystep"
        },
        {
          "$ref": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/activitysteps/definition#/activitystep"
        },
        {
          "$ref": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/extractsteps/definition#/extractstep"
        },
        {
          "$ref": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/customsteps/definition#/customstep"
        },
        {
          "$ref": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/processsteps/definition#/processstep"
        },
        {
          "$ref": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/querysteps/definition#/querystep"
        },
        {
          "$ref": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/subflowsteps/definition#/subflowstep"
        }
      ],
      "x-oi-resource-name": "integrationsteps",
      "x-oi-super-resource-link": " [hostName]:[portNumber]/oig-ws/api/generic/integrations/integrationsteps/definition#/integrationstep"
    }
}

Dynamic Reference Fields (Provider, Procedure, Diagnosis)

Fields of this type are restricted to a certain subset of all the reference objects: only the procedures/providers/diagnoses of a certain flexcode system/set can be used.

The metadata for these types of dynamic fields also contains a link to the resource that gives the possible values for these dynamic fields. This can be used by the consumer of the metadata to fill up a drop down list.

"": {
  "type": "object",
  "properties": {
    "flexCodeDefinitionCode": {
      "type": "string",
      "maxLength": 30
    },
    "value": {
      "type": "string",
      "maxLength": 30
    }
  },
  "required": [
    "flexCodeDefinitionCode",
    "value"
  ],
  "x-oi-dyn-flex-link": "http://[hostName]:[portNumber]/[api-context-root]/generic/?q=flexCodeSystem.id.eq()"
}
This is not the full definition of the provider, diagnosis and procedure object, but a special one only to be used for references. The reason is that dynamic fields have special reference properties "flexCodeDefinitionCode" and "value".
The same applies to diagnosis and procedure.

Dynamic Reference Fields (Flexcode)

The metadata for this type is identical to the metadata for the provider, diagnosis and procedure case, with the edition of the "descriptor" property:

"": {
  "type": "object",
  "properties": {
    "flexCodeDefinitionCode": {
      "type": "string",
      "maxLength": 30
    },
    "value": {
      "type": "string",
      "maxLength": 20
    },
    "descriptor": {
      "type": "string"
    }
  },
  "required": [
    "flexCodeDefinitionCode",
    "value"
  ],
  "x-oi-dyn-flex-link": "http://[hostName]:[portNumber]/[api-context-root]/generic/flexcodes/?q=flexCodeSystem.id.eq()"
}

The key field of an flex code definition is always a character field. The descriptor field however can also be of type "Date" or "Number".

Multi-valued field (MVNTV)

Multi-valued dynamic field are defined as an array of the elementary type:

"": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "flexCodeDefinitionCode": {
        "type": "string",
        "maxLength": 30
      },
      "value": {
        "type": "string",
        "maxLength": 30
      }
    },
    "required": [
      "flexCodeDefinitionCode",
      "value"
    ]
  },
  "x-oi-searchable": false,
  "x-oi-dyn-unique": false
}

Time-valid dynamic field (SVTV)

Time-valued fields are defined as an array of the elementary type with the addition of startDate and endDate.

Example of a time-valid character field:

"": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "flexCodeDefinitionCode": {
        "type": "string",
        "maxLength": 30
      },
      "value": {
        "type": "string",
        "maxLength": 30
      },
      "startDate": {
        "type": "string",
        "format": "date"
      },
      "endDate": {
        "type": "string",
        "format": "date"
      }
    },
    "required": [
      "flexCodeDefinitionCode",
      "value"
    ]
  }
}

Multi-valued reference field

An example of a multi-valued field are the addresses of a relation. Multi-valued field are defined as array:

"addressList": {
  "type": "array",
  "items": {
    "$ref": "http://[hostName]:[portNumber]/[api-context-root]/generic/addresses/definition#/address"
  }
}

Dynamic Record

Dynamic records are handled as an array of embedded objects:

Multivalue and/or time valid records will have the following structure

"": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "": {
        ... definition depending on the type of record field 1.
      },
      "": {
        ... definition depending on the type of record field 2.
      },
      "startDate": {
        "type": "string",
        "format": "date"
      },
      "endDate": {
        "type": "string",
        "format": "date"
      }
    }
  }
}

Single value and non time valid records will have the following structure

"": {
    "type": "object",
    "properties": {
      "": {
        ... definition depending on the type of record field 1.
      },
      "": {
        ... definition depending on the type of record field 2.
      },
      "startDate": {
        "type": "string",
        "format": "date"
      },
      "endDate": {
        "type": "string",
        "format": "date"
      }
   }
}

Updatable/Insertable/ReadOnly properties

The metadata also includes information if the property can be updated, or can be inserted or if it is readonly.

  • x-oi-insertable: If a property is not insertable, this attribute will be included in metadata with value false.

  • x-oi-updatable: If a property is not updatable, this attribute will be included in metadata with value false.

  • readOnly: If a property is not insertable and is not updatable, this attribute will be included in metadata with value true. The above two will NOT be included in this case.

The above will only be included in metadata where the value is other than default values.

Boilerplate

The metadata also exposes the boilerplate ("labels") for the resource and its properties in the language of the current user:

"x-oi-labels": {
  "title": "Claim",
  "titleplural": "Claims",
  "properties": {
    "claimForm": "Claim Form",
    "flexcodeSV": "Field Display Name",
    "myRecord": {
      "title": "Record Display Name",
      "properties": {
        "recordField1": "Display Label of first record field",
        "recordField3": "Display Label of second record field"
      }
    }
  }
}

Functional Key

If a resource has a (composite) functional key, the x-oi-functional-key attribute is included in the definition. This attribute defines an array of all the properties of the (composite) key.

"x-oi-functional-key": ["", ""..., ""]

Retrieving a Specification

The specification can be found by following links of type "describedBy".

{
  "rel": "describedBy",
  "href": "http://localhost:7001/api/generic/fields/metadata"
}

Those links will be present in:

  1. The HTTP API root resource for every collection resource.

  2. The HTTP IP root resource for every IP.

More details will be given in the chapters that describe both HTTP IP and HTTP API.