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 that is 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 firstName and lastName, a number value for age, an object value that represents the person's address, and an array value of phoneNumbers 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 the Java Gateway 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. It is always written in the top-level object. It can also be written in sub objects when the value type is not the attribute type. For example, in table 3, the value of the Geometry attribute is defined by the subtype Point. This is known as type polymorphism.

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 has an author. 
an artwork has 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 relationships 
a flight is related to some stopovers.
 
{ 
   "$class": "Travel",
   "stopovers": [ 
      {
         "key": "Paris";
         "type": "Place"
      },
      {
         "key": "London";
         "type": "Place"
       },
       {
          "key": "Paris";
          "type": "Place"
       }
   ]
}
Multiple relationships 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 has an author. 
an artwork has 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
Type of attribute 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": "Person", 
  "home": 
   {
    "street": "Privet drive",  
    "town": "Little Whinging",
    "country": "UK" 
   }
}
Table 3. Geospatial attribute types in JSON format
Type of attribute Business model definition example JSON equivalent
Geometry 
a parking lot has a location (a geometry).
 
{       
  "$class": "ParkingLot",       
  "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
Related reference:
Data formats