About creating a JSON request message for a Decision Service

A JSON request message has a body that describes the parameters for handling the request payload, and the payload.

Parameters of a JSON Request

{
   "name": "string",
   "majorVersion": "string",
   "minorVersion": "string",
   "effectiveTimestamp": "string",
   "Objects": [
      {}
   ]
}

• name - the name of the Decision Service -String
• majorVersion—Major version number, optional - String, converted to an integer in Corticon
• minorVersion—Minor version number, optional - String, converted to an integer in Corticon
• effectiveTimeStamp—DateTime of the Decision Service, optional - String
• Objects—JSONArray of JSONObjects that comprises the payload - String

Structure of JSON payload

A JSON payload is a standardized JSONObject that can be passed in to ICcServer.execute(…). The payload contains:

• "Objects": [<JSONArray>] where the JSONArray must contain JSONObjects that represent Root Entities of the payload.
• __metadataRoot (optional) - An annotation Attribute inside the main JSONObject that can contain execution specific parameters. (Note that the initial characters are TWO underscores.) These parameters are used only for that execution and will override Decision Service or CcServer level properties. The following example shows the supported properties:

  {
     "Objects": [<JSONArray>
     ],
     "__metadataRoot": {
        "#restrictResponseToRuleMessagesOnly": "true",
        "#locale": "en-US"  
      }
      }

  where:
  • #restrictResponseToRuleMessagesOnly—Returns only Rule Messages that were created during this execution; no data is returned. This setting is also enabled in a Ruletest's Execution Properties. - Boolean
  • #locale"—Instructs the CcServer to process this execution under a specific Locale, which might affect Datetime and Decimal values, since these values might be represented differently for a Locale. - String

The Corticon Server will translate JSONObjects that are inside the JSONArray under the name of "Objects".

{
    "name": <string>,          
    "majorVersion":  <number - optional>,
    "minorVersion":  <number - optional>,
     "Objects": [<JSONArray>
    ],
    "__metadataRoot": {
        <execution property>: “<value”,
       .
       .
    }
}

Metadata in requests is supported in Ruletests where it is the format of JSON output from a Ruletest when you choose Testsheet > Data > Output > Export JSON to File.

Native JSON

You can also use unannotated JSON payloads in a Ruletest and when calling a Decision Service. A JSON payload does not require Corticon-specific annotations to allow Corticon to map a payload to the Corticon vocabulary. That format complicated integration of Corticon from external applications by requiring passing JSON data in "Corticon’s format", not the "native format" of many applications. Eliminating the need for these annotations simplifies integrating Corticon with your applications. The annotations can still be provided but are optional.

__metadataRoot (optional)

This optional Attribute inside the main JSONObject can contain execution specific parameters. (Note that the initial characters are TWO underscores.) These parameters are used only for that execution, and will override a Decision Service or Server property. The following properties are supported:

• #restrictInfoRuleMessages
• #restrictWarningRuleMessages
• #restrictViolationRuleMessages
• #restrictResponseToRuleMessagesOnly
• #locale
• #timezoneId

The following example uses these properties in __metadataRoot:

{
    "Objects": [<JSONArray>
    ],
    "__metadataRoot": {
        "#restrictInfoRuleMessages": "true",
        "#restrictViolationRuleMessages": "true",
        "#restrictResponseToRuleMessagesOnly": "true",
        "#locale": "en-US"  
    }
}

Root Level Entities

All JSONObjects inside the JSONArray under Objects are Root Level Entities.

Every name-value in the JSONObject maps to a Corticon Vocabulary Entity name on the Root of the payload or as an Association Entity, each of which requires a __metadata String attribute with a value of a JSONObject that describes the Entity with name-value pairs.

Mandatory:

#type : The Entity type as defined in the Vocabulary.

Optional:

#id: A unique String value for each Entity.

If #id is not supplied in the payload, during execution of rules, a unique value will be set for each Entity. This is done during initial translation from JSON to Corticon Data Objects (CDOs). This is needed because Corticon does not know whether the rules will manipulate the Associations in such a way that #id values are needed. The output returned to the user will always contain #id value regardless if it was originally part of the “__metadata”.

Example of Root Level Entity with __metadata:

{
    "Objects": [{
        "dMarketValueBeforeTrade": "10216333.000000",
        "price": "950.000000",
       "__metadata": {
            "#id": "Trade_id_1",
            "#type": "Trade"
        }
    }],
}

JSON Entity Attribute and Association name-value pairs

All Entities can contain Attribute name-value pairs along with Association Role name-value pairs.

Attribute name-value pairs

Each JSON Entity can have any number of Attribute name-value pairings. The Attribute names inside the JSON Entity correspond to what has been defined in the Vocabulary for that JSON Entity type. The Attribute name inside the JSON Entity is used to look up the corresponding Vocabulary Attribute for that Vocabulary Entity type. If JSON Entity Attributes don’t match with any Vocabulary Entity Attribute, then the JSON Entity Attribute is ignored, and won’t be used by the rules.

The JSON Datatypes that can be used as a value are String, Boolean, Double, Int, Long.

For a Date value, use a String to represent the Date, which will be converted into a proper Date object for rule processing.

The value associated with a name does not have to be a String. However, the value must be of proper form to be converted into the Datatype as defined in the Vocabulary Attribute’s Datatype. If the value cannot be properly converted into the Vocabulary Attribute’s Datatype, a CcServerExecutionException will be thrown informing the user that the CcServer failed to convert the JSON “values”.

Example of Attribute name-value pairs

There is one Attribute, price, with a corresponding value. Based on the __metadata : #type, these Attribute values are looked up under the Vocabulary's Trade Entity.

Association name-value pairs

Each JSON Entity can have any number of Association name-value pairings. The Association names inside the JSON Entity correspond to a Vocabulary Entity Association Role Name, defined in the Vocabulary for that JSON Entity type. Like the Attribute, as described above, Association names inside the JSON Entity are used to look up the corresponding Vocabulary Association for that Vocabulary Entity type. Note that:

• The value associated with name can be either a JSONObject or a JSONArray (of other JSONObjects).
• If the original value was a JSONObject, a JSONArray could be in the output.
• If there is a rule that does a += operator on the Association, the JSONObject will be converted into a JSONArray so that multiple JSONObjects can be associated with that name.
• If JSON Entity Association names don’t match with any Vocabulary Entity Association Role Name, then the JSON Entity Association is ignored, and won’t be used by the rules.
• In an Associated JSONObject, the value, can be a Referenced Associated Object, which points to another JSONObject in the payload. In this scenario, a #ref_id is used to point to the intended Entity. As described above, the #type value is not needed when a Referenced Associated Object is used because the type can be inferred by the Rules Engine.

Example of Embedded Association name-value pairs:

In the following example, there is one Association, transaction that has corresponding JSON Object as a value. It is an Embedded Association -- an Entity under another Entity. The Transaction Entity, as defined by its __metadata : #type = Transaction is associated with Trade through a Role Name of transaction.

Example of Referenced Association name-value pairs:

XML Element Name overrides for Attributes and Association names

JSON Entity Attribute names are first matched against XML Name overrides, which are defined in the Vocabulary Attribute. If no XML Element Name is defined, then JSON Entity Attribute names are matched directly against the Vocabulary Attribute name.

Much like the Attribute’s XML Element Name override, Associations also have an XML Element Override.

See also Simplified JSON in requests .