JSON mapping

Data in Decision Server Insights can be represented in JavaScript Object Notation (JSON). Use the examples to map the data types of your business model definition into JSON.

Purpose

You can map the data types of your business model into JSON by using the examples. Data in JSON is either an object or an array. A JSON object is an unordered collection of names and values. A JSON array is an ordered sequence of values. A value can be a string, a number, a boolean, a null, an object, or an array.

The following business model definition (BMD) statement defines a concept named person.

a person is a concept with
a first name,
a last name,
an age(integer),
an address,
some phone numbers.

The following example shows the JSON representation of an instance of the person concept. The object has string values for first name and last name, a number value for age, an object value that represents the person's address, and an array value of phone number objects.

{
   "$class": "Person",
   "$CreationTime": null,                   
   "$IdAttrib": "id",    
   "firstName": "John",    
   "lastName": "Doe",    
   "age": 25,   
   "address": {        
      "streetAddress": "20 rue jean d'arc",        
      "city": "Rouen",       
      "postalCode": 76000    
      }, 
   "phoneNumbers": [        
      {            
         "type": "home",            
         "number": "0235066090"       
      },        
      {            
         "type": "mobile",            
         "number": "0648417050"
      }    
   ]
}
Important: The prefix symbol $ is reserved for internal usage, for example $IdAttrib is an internal field. All $ prefixed attributes other than $class, $CreationTime, and $ref are ignored when you input data by JavaGateway API, REST, or connectivity.

The $class is used to refer to named BMD elements (entity, event, concept class names), or predefined class names like "int".

The $CreationTime attribute represents the creation time of an entity. It can be null.

The $ref attribute is used to reference existing content in the same JSON document. The $ref attribute value is a JSONPATH expression that is evaluated to retrieve the corresponding object. When the JSON payload is used in JavaScript, you can use JSON.retrocycle to get the right graph of objects. When the JSON payload is produced from JavaScript, you can use JSON.decycle to produce the $ref with the right JSONPATH expressions. For more information, see JSON in JavaScript.

Syntax

Table 1. Examples of BMD elements in JSON
Business model elements Business model definition example JSON example

Attribute

 
a person is a concept. 
a person has a first name.
 
{ 
   "$class": "Person", 
   "firstName": "Smith" 
}

Concept

 
a person is a concept.
 
{ 
   "$class": "Person" 
}

Entity

 
an airport is a business entity identified by an airport code.
 
{ 
   "$class":"Airport",
   "airportCode": "LHR" 
}

Enumeration

 
a enum type can be one of : alpha , beta , gamma. 
{ 
   "enumType": "alpha" 
}

Event

 
a flight event is a business event time-stamped by a datetime.
 
{ 
   "$class":"FlightEvent",
   "datetime": "2012-06-29T12:32:40+01:00" 
}

List

 
a person is a business entity identified by an id.
a person has some assets. 
an asset is a concept.
an asset has a value (integer).
an artwork is an asset.
an artwork as an author. 
an artwork as a name.
a real estate is an asset. 
a real estate has a name. 
a real estate has a location (a point).
 
{
   "$class": "Person";
   "id": "William Randolph Hearst";
   "assets": [        
      {       
         "$class": "RealEstate",
         "location": {
            "coordinates": [35.6852076,-121.1682251]
          },
         "name": "Heart's Castle",
         "value": 1000000
      },
      {
         "$class": "Artwork",
         "author": "Antonio Canova",
         "name": "The tree graces",
         "value": 56657
      }      
   ]
}

Multiple relationship

 
a flight is related to some stopovers.
 
{ 
   "$class": "Travel",
   "stopovers": [ 
      {
         "key": "Paris";
         "type": "Place"
      },
      {
         "key": "London";
         "type": "Place"
       },
       {
          "key": "Paris";
          "type": "Place"
       }
   ]
}

Multiple relationship where each item is unique

 
a flight is related to several different boarded passengers. 
{ 
   "$class": "Flight",
   "boardedPassengers": [ 
      {
         "key": "5654";
         "type": "Person"
      },
      {
         "key": "7887";
         "type": "Person"
       }
   ]
}

Reference

 
a person is a business entity identified by an id.
a person has some assets. 
an asset is a concept.
an asset has a value (integer).
an artwork is an asset.
an artwork as an author. 
an artwork as a name.
a real estate is an asset. 
a real estate has a name. 
a real estate has a location (a point).
a person has a favorite asset. 
{
   "$class": "Person";
   "id": "William Randolph Hearst";
   "assets": [        
      {       
         "$class": "RealEstate",
         "location": {
            "coordinates": [35.6852076,-121.1682251]
          },
         "name": "Heart's Castle",
         "value": 1000000
      },
      {
         "$class": "Artwork",
         "author": "Antonio Canova",
         "name": "The tree graces",
         "value": 56657
      }      
   ], 
   "favoriteAsset": {"$ref": "$.assets[0]}
}

Relationship

 
a flight is related to an airport.
 
{
   "$class": "Flight",  
   "airport": 
   {
      "$class": "com.ibm.ia.model.Relationship",      
      "key": "LHR",      
      "type": "Airport"    
   }
}
Table 2. Main attribute types in JSON format
Values Business model definition example JSON equivalent

Boolean 

a trip can be completed.
 
{ 
 "$class": "Trip",  
 "completed" true
}

Number

 
a purchase has an amount (numeric).
an aircraft has a capacity (integer).
 
{  
 "$class": "Purchase",  
 "amount": 12.0
}
{
 "class": "Aircraft",
 "capacity": 150
}

String

 
an airport has a baggage handling system (text).
a flight has an original departure (date and time).
a person has a date of birth (date).
a flight has a regular time of departure (time).
a paper has a monthly publication date (a day of month).
a flight has a flight duration (duration).
a library has some weekly closed days (a day of week).
a coupon has a validity period (a time period).
a product has a release year (a year).
 
{
 "$class": "Airport",
 "baggageHandlingSystem": "P15"
}
{
 "$class": "Flight",
 "originalDeparture": "2015-12-12T12:25:27-05:00[America/New_York]"
}
{  
 "$class": "Person",  
 "dateOfBirth": "2015-12-12"
}
{
 "$class": "Flight",
 "regularTimeOfDeparture": "12:25:27"
}
{  
  "$class": "Paper",  
  "monthlyPublicationDate": "12"
}
{
 "$class": "Flight",
 "flightDuration": "PT2H"
}
{  
  "$class": "Library",  
  "weeklyClosedDays": ["1"]
}
{  
  "$class": "Coupon",  
  "validityPeriod": "2016-02-22T17:19:34+01:00[Europe/Paris]/2016-03-22T17:21:34+01:00[Europe/Paris]"
}
{  
  "$class": "Product",  
  "releaseYear": "2016"
}

Object

 
a person has a home (an address).
 
{
   "$class": "Address", 
   "street": "Privet drive",  
   "town": "Little Whinging",
   "country": "UK" 
}
Table 3. Geospatial attribute types in JSON format
Values Business model definition example JSON equivalent

Geometry

 
a parking lot has a location (a geometry).
 
{       
  "$class": "Car",       
  "location":      
   { 
     "$class": "Point", 
     "coordinates":    [35.04441810662473,32.80011518953123]    
   }  
}

Point 

a shop has a location (a point).
 
{       
  "$class": "Shop",       
  "location":      
   { 
     "coordinates":    [35.04441810662473,32.80011518953123]     
   }  
}
Parent topic: REST API