Working with Schema

LightWave Client schema describes the data types used in API request and response data mappings. The schema definitions are stored as part of the API. Ordinarily, there is no need for you to create schema definitions directly. The LightWave Client Console API editor automatically creates schema definitions for you when, while defining an API, you create a request or response mapping and select "Add by Example" for 'Schema Type'. In addition, when importing an API definition from a Swagger or OpenAPI definition, the API editor translates the type definitions it contains to LightWave Client schema.

To view or edit the schema attached to your API, click the 'Edit API Schema' icon  in the API detail view toolbar. The schema is defined in Javascript Object Notation (JSON) regardless if data types are serialized as JSON or XML.

Although the Console API editor ordinarily creates the schema for you, there are times that you may want to modify the generated schema. The reason for this is due to differences in JSON schema or XML schema used in REST APIs and the invariant structured data types used in HPE NonStop applications. Both JSON and XML support the concept of unbounded strings – character strings without a defined maximum length. Likewise, both JSON and XML support unbounded arrays – arrays without a defined maximum size. Because the programming languages (C, COBOL, TAL, etc.) used by client applications on NonStop do not support unbounded data structures, it's necessary for LightWave to impose a maximum limit on string length and array size. When the API editor generates schema, it uses a minimum default length for strings of 32 and a minimum default array size of 4. (If the structure provided 'by example' contains a longer string or larger array, the example size is used.)  Fortunately, these limits may be modified – on an element-by-element basis – by modifying the schema the Console API editor has generated for you. 

The image above shows the 'Add by Example' dialog. Note the simple example JSON object consisting of two properties, "aStringProperty" and "anArrayOfStrings", and their respective sample values. The image below shows schema generated by the examples above.

Each schema type definition consists of an array of elements describing the properties or fields of the object it's describing. Each element minimally has a 'name' and a 'type'. See Built-in primitive types, below, for a list of available types. There are additional properties that may be added to an element's schema to further describe the element. See Schema Element Properties, below for a list of those properties.

Note that aStringProperty has been given a default "size", or length, of 32. If we know that aStringProperty will never hold a value greater than 12 characters, we can modify the size property accordingly. Likewise, if we know that a value for aStringProperty may be as long as 100 characters, we must modify the size property accordingly. (If at run time, a web service returns a value longer than ‘size' allows, LightWave will copy 'size' characters to the buffer and return a 'field truncated' warning.) If your client application will use zero-padded or NULL terminated strings as a 'C’ or TAL language program typically would, be sure to account for the terminator when calculating 'size'. See stringPadding in Schema Element Properties, below.

Regarding anArrayOfStrings in the example, note that again, a default size of 32 has been generated. The size property should be adjusted as needed. Additionally, since anArrayOfStrings is an array, the schema generator has emitted the maxOccurs property and given it the default value of 4, meaning the array may hold a maximum of four elements. If we know that the array must hold more or less than that amount, we would modify the maxOccurs property accordingly. (If the number of array items returned by the web service exceeds maxOccurs, LightWave will return an 'array truncated' warning.) Finally, note the dependsOn property. The schema generator has inserted an 'array count' element named 'anArrayOfStrings-count' into the type definition to hold the logical length of the anArrayOfStrings array. During serialization, only anArrayOfStrings-count items will be serialized to JSON. During deserialization, LightWave will store the actual number of items converted from JSON and copied into anArrayOfStrings in anArrayOfStrings-count. 

Another reason you may wish to modify schema generated by the API editor is to change the primitive data type (string, integer, float, etc.) of a schema element. JSON and XML primitive types do not map one-to-one with NonStop primitive types. When generating a schema 'by example', the API editor attempts to infer the corresponding NonStop data type and size of each example element's JSON or XML value. Sometimes the inference made by the API editor is incorrect – for example if the example data value is 1, the API editor infers a type of 'int' (32-bit), when the element, in fact, needs to hold values requiring a 64-bit integer. Again, you may edit the generated schema as needed to adjust any improperly inferred element data types.

Add Schema by Example for 'ExampleType'

{
  "ProductCategory": 123
}

Generated Schema for Example Above

  "ExampleType": {
    "anonymous": false,
    "elements": [
      {
        "name": "ProductCategory",
        "type": "int"
      }
    ]
  }

Because the example value of CustomerNumber provided is 123, the schema generator infers that the data type for the property should be 'int', which can store values between  –2,147,483,648 to 2,147,483,647.  However, if we know that product category will never be greater than 65,635, for example, we can modify "type" to be "unsignedShort".  This will decrease the amount of space in the interprocess message (IPM) buffer from four bytes to two. Likewise, if we know that ProductCategory can be larger, we can modify "type" to be "unsignedLongLong", for example.

Schema Element Properties

The following properties may be applied to elements in the schema. Note that properties prefixed with @Xml are a subset of Java JAXB annotations.

"anElement": {
  "anonymous": false,
  "elements": [
    {
      "name": "theAttribute",
      "type": "string",
      "size": 32,
      "@XmlAttribute": {}
    }
  ]
}

<anElement theAttribute="the-contents-of-theAttribute" />

{
  "RootElement": {
    "anonymous": false,
    "@XmlRootElement": {
      "name": "root"
    },
    "elements": [
      {
        "name": "theArray",
        "type": "string",
        "size": 32,
        "maxOccurs": 4,
        "@XmlElementWrapper": {
          "name": "aWrappedArray"
        },
        "@XmlElement": {
          "name": "item"
        }
      }
    ]
  }
}

<root>
  <aWrappedArray>
    <item>1</item>
    <item>2</item>
    <item>3</item>
  </aWrappedArray>
</root>

"anElement": {
  "anonymous": false,
  "elements": [
    {
      "name": "value",
      "type": "string",
      "size": 32,
      "@XmlValue": {}
    }
  ]
}

<anElement>the-contents-of-value</anElement>

<anElement>
  <value>the-contents-of-value</value>
</anElement>

Built-in 'primitive' Types