JSON Schema for Published REST Operation

Introduction

When you publish a rest service, an OpenAPI (Swagger) documentation page is generated for it. It includes a description of the structure of the messages that the service can receive and return. This structure is described using JSON Schema.

Operations that have an import or export mapping defined on it will generate such a schema, but only for mappings that are based on message definitions.

The JSON schema is generated based on the rules documented here.

Definitions

The OpenAPI schema contains definitions for body parameters and return types. If a configured import or export mapping is based on a message definition, there will be a definition for it.

Definition of a Message

"#definition_name#": { 
  "type": "object",
  "properties": [
     #attribute_name#: #attribute_schema#
  ]
}

By default, the definition name is the name of the message definition that the mapping is based on. You can choose your own definition name by setting the Public name of a mapping.

Attribute

The schema of an attribute depends on the attribute type:

JSON Schema for an Operation Request Body

When the operation has a body parameter, it has a schema. This schema refers to a definition when you have selected an import mapping based on a message definition.

If the parameter is an object:

{ "$ref": "#/definitions/#definition_name#"}

If the parameter is a list:

{ 
  "type": "array",
  "items": [{ "$ref": "#/definitions/#definition_name#"}]
}

If there is no import mapping, or the mapping is not based on a message definition:

{ "type": "file" }

JSON Schema for an Operation Result

The result of an operation has a schema, too. The format of this depends on the type of result.

When there is no export mapping or the export mapping is not based on a message definition:

{ "type": "file" }

When the microflow returns an object:

{ "$ref": "#/definitions/#definition_name#"}

When the microflow returns a list:

{ 
  "type": "array",
  "items": [{ "$ref": "#/definitions/#definition_name#"}]
}

When the microflow returns a primitive, the schema depends on the type: