Page tree
Skip to end of metadata
Go to start of metadata

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 (aka 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 Edit API Schemain 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 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 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 (a/k/a 'null-terminated') strings (as a 'C' language program would typically), 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 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.

property namedescription
namerequired; the name of the element
typerequired; the type of the element; either a primitive type, or a type defined elsewhere in the schema. See below for supported primitive types.
ddlNamethe name for the element that should be used in DDL generation; overrides the default name-to-ddlName mapping
dependsOnwhen the element represents an array (minOccurs > 0), the name of another element in the current type definition that contains the actual count of 'in use' array elements
hideboolean; specifies that the item should not be serialized, often used in an element targeted by dependsOn, sizeIs or scaleIs (synonymous with private)
isNullboolean; when type is "nillable", the name of another element in the current type definition that indicates whether or not the field contains the value null  when de/serialized
isSetReferences an integer fields that indicates whether of not the field should be present in the request, or was present in the response. See Handling Optional Fields
jsonTypethe JSON type ("number", "string", or "boolean") that should be used to de/serialize the element; overrides the default primitive-type to JSON-type mapping
mapspecifies that the element represents a JSON map
minOccurswhen "type" is "string", if minOccurs = 0, zero-length string values will not be serialized
maxOccursindicates the element represents an array; the maximum number of array elements that can be de/serialized
nillableboolean; indicates that the field may contain the value null.
privateboolean; specifies that the item should not be serialized, often used in an element targeted by dependsOn, sizeIs or scaleIs. (synonymous with hide)
scalefor integer and numeric types, the scale that should be used in the generated DDL element
sizewhen "type" is "string", "base64Binary" or "hexBinary", the maximum length of the value
sizeIswhen "type" is "string", "base64Binary" or "hexBinary"; the name of another element in the current type definition that contains the actual length of the item de/serialized
stringPadding"spaces" or "zeros"; indicates how LightWave expects to receive, returns string values from the client application. The default value is set in the API definition (which can be overridden by a CLIENT command-line parameter). Typically only set on the element level if more that one setting is needed for separate elements in a single API.

timestampFormat

when type="timestamp", indicates the de/serialization format: "ISO8601", "ISO8601:full-date", "RFC2822", or "XSD:dateTime"
wrappedboolean; indicates if an array is wrapped in an array container or a type/element is wrapped by its parent. Default is true.
@XmlAttribute

object; indicates that the value of the field is an attribute of the parent type. The object may contain the following properties

PropertyDescription
nameMay be used to override the name of the attribute.
namespaceIndicates that the attribute it qualified with the specified namespace


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

Yields

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

object; allows various properties to be applied to an XML element. The object may contain the following properties:

PropertyDescription
nameMay be used to override the name of the element.
namespaceSets the namespace of the element. If omitted, the namespace is inherited from the parent element.
nillableboolean; indicates that the field may contain the value null.
isNullboolean; when type is "nillable", the name of another element in the current type definition that indicates whether or not the field contains the value null  when de/serialized.
@XmlElementWrapper

object; causes a wrapper to be created around the element and is most commonly used to declare wrapped arrays. The object may contains the following properties:

PropertyDescription
nameMay be used to override the name of the wrapper element.
namespaceSets the namespace of the wrapper element. If omitted, the namespace is inherited from the parent element.

For example:

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

Yields

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

object; allows various properties to be applied to an XML document root element. The object may contain the following properties:

PropertyDescription
nameMay be used to override the name of the element.
namespaceSets the namespace of the root element. If omitted, the namespace is inherited from the parent element.
@XmlValue

object; causes the contents of the field to be mapped as the text content of the parent type. The object has no properties. For example:

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

Yields

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

Not

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


Built-in 'primitive' Types

namedescriptionDDL typeJSON type
base64Binaryserialized as base-64 encoded string; n=sizePIC X(n)

string

booleanzero serialized as "false";
non-zero values as "true"
BINARY 32

boolean

byte-128 <= value <= 127BINARY 8number
doubledouble precision floating pointFLOAT 64number
floatsingle precision floating pointFLOAT 32number
hexBinaryserialized hex binary string; n=sizePIC X(n)string
int–2,147,483,648 to 2,147,483,647BINARY 32number
longsame as intBINARY 32number
longlong–9,223,372,036,854,775,808 to 9,223,372,036,854,775,807BINARY 64number
numeric

numeric string; n=precision;
s=scale

PIC S9(n)
PIC S9(n)V9(s)

number
numericSignEmbedded

numeric string; n=precision
s=scale

PIC T9(n)
PIC T9(n)V9(s)

number
numericSignTrailing

numeric string; n=precision
s=scale

PIC 9(n)S
PIC 9(n)V9(s)S

number
numericSignTrailingEmbedded

numeric string; n=precision
s=scale

PIC 9(n)T
PIC 9(n)V9(s)T

number
short-32768 <= value <= 32767
(optional scale)
BINARY 16number
string

character string
s=size

PIC X(s)string
timestamp

serialized as timestamp;
see 55345251

BINARY 64string
unsignedByte0 <= x <= 256BINARY 8, UNSIGNEDnumber
unsignedInt

0 <= x <= 232 - 1
(optional scale)

BINARY 32, UNSIGNEDnumber
unsignedLongsame as unsignedInt
(optional scale)
BINARY 32, UNSIGNEDnumber
unsignedLongLong0 <= x <= 264 - 1
(optional scale)
BINARY 64, UNSIGNEDnumber
unsignedNumeric

number
unsignedShort0 <= x <= 65535
(optional scale)
BINARY 16, UNSIGNEDnumber
  • No labels


LightWave Client 1.1.2