Create a Vocabulary from a JSON payload

Suppose you are writing rules for a B2B e-commerce application that will determine what, if any, discounts should be applied to an order. An order contains contact information about the customer, their partnership status ('elite' or 'standard') and the items in the order. Your rules will examine this information to determine a discount rate for the order in line with the promotions being offered by your company. For example, 'elite' customers might get 15% off on orders over $10,000.

Working with IT, you've been supplied this sample JSON file representing an order. JSON in this format is used by other components of your e-commerce application:

{
    "orderId": 494748,
    "customer": "Acme Industries",
    "customerStatus": "elite",
     "shippingAddress": {
        "street address1": "1234 Industrial Lane",
        "street address2": null,
        "city": "Boston",
        "state": "MA",
        "zip": "01234"
    },
    "products": [
        {
            "sku": "XYZ-BB-43",
            "unitPrice": 2300.00,
            "quantity": 2,
            "tags": [
                "industrial",
                "compressor"
            ]
        }
    ],
    "discount": 0.0
}

To populate a Vocabulary from a JSON payload:

  1. Copy the preceding JSON and then save in a temporary file. Set the file extension to .json.
  2. In Corticon Studio, create a new Rule Project named OnlineRetail.
  3. In the project, create a Vocabulary named Orders.
  4. Click in the Vocabulary edit window, and then select Vocabulary > Populate Vocabulary from JSON.
  5. Choose the temporary file with the JSON you saved, and then click Open.

The Vocabulary that the JSON generates is the following:



Let's take a closer look at the Vocabulary:

  • Root entity—The JSON source has an object definition at root, indicated by the JSON starting with initial brace. You know this root entity is an order. Corticon does not know that, so it named the top-level entity Root. After vocabulary generation completes you can refactor the root entity name to Order:


  • Attributes—The ShippingAddress entity, renamed Order, has six attributes.
    • The values in the source data were suggested as dates, numbers, and Strings. Review each one, and revise each attribute's data type as appropriate.
    • Each attribute will store the name:
      • If the name in the source JSON is valid, no value is copied into the JSON Element Name field in the Vocabulary.
      • If the name in the source JSON is not valid, an override is attempted, and added to the vocabulary while the JSON Element field stores the source name. In this example, the source has an element named street address1. As spaces are not valid in Corticon names, the name street_address1 with an underscore is inferred, and the JSON Element Name is assigned street address1. This is the incoming payload identifier that will map to its Vocabulary attribute name:


        Note: If an attribute has a null value in the source JSON, the data type String is assumed.
  • Non-root entities—Other entities take the name in the source JSON:


  • Associations: Corticon added the Products entity, and then added an association from Root (Order) to products:


  • Scalar arrays—A scalar array is handled as an association from the entity with its own identifying Entity. The JSON Array's relationship is that products are relative to root ($) and one or more tags are related to products:


Note: Corticon does not support JSON arrays mixing scalar values and objects. For example: 
"A": [1,2,3, {"B": {"color" : "red"}}]
This JSON snippet defines an array "A" containing the scalar values 1,2,3 and the object "B". In Corticon, an array must be either all scalar values or all objects.

Update a vocabulary from a JSON payload

Suppose your Sales department wants to enhance the discount program to provide an additional discount to government agencies and whether an order is marked for expedited handling. In support of this IT has provided an updated sample JSON the includes the new information.

An update generates new entities, attributes, and associations. The existing entities, attributes, and associations are not revised by regenerating over the existing Vocabulary. If you want one element to be regenerated, delete it before you perform the update. You could even delete the vocabulary entirely, and then start fresh. The original sample payload adds a requirement for Billing Address to the sampleCustomer Vocabulary.

{
    "orderId": 494748,
    "customer": "Acme Industries",
    "customerStatus": "elite",
    "governmentAgency": false,

    "shippingAddress": {
        "street address1": "1234 Industrial Lane",
        "street address2": null,
        "city": "Boston",
        "state": "MA",
        "zip": "01234"
    },
    "shippingDetails": {
        "expedite": true,
        "mode": "ground"
    },

    "products": [
        {
            "sku": "XYZ-BB-43",
            "unitPrice": 2300.00,
            "quantity": 2,
            "tags": [
                "industrial",
                "compressor"
            ]
        }
    ],
    "discount": 0.0
}
When you regenerate your vocabulary from this JSON, it will add new entities, attributes and associations to your vocabulary for the new items in the JSON. The Vocabulary shows the added entity, attributes, and association:


Note: If you rename or refactor entity or attribute names, an update from the same source will generate duplicate entities and attributes for the ones you renamed in the Vocabulary. You will need to delete the duplicates. In this example, Root was refactored to Order, so Root will be deleted.

Integrating multiple sources into a Vocabulary

To build a single vocabulary that integrates multiple data feeds, it is convenient to import additional sources into separate vocabulary domains. Corticon enables you to import into an added domain without impacting the rest of the Vocabulary.

Consider a variation on the customer info so that it identifies a partner:

{
"orderId": 494749,
"partner": "Acme Partners",
"partnerStatus": "elite",
"shippingAddress": {
	"street address1": "2000 Industrial Ave",
	"street address2": null,
	"city": "Boston",
	"state": "MA",
	"zip": "01234"
},
"shippingDetails": {
	"expedite": true,
	"mode": "ground"
}
}
"discount": 25.0
}
In the Vocabulary file, right-click at the root and then choose Add Domain:

Click on the new domain to change the name to Partners.

Right-click on the Partners domain and then choose Populate Domain From JSON:

Choose the file where the preceding listing was saved, and click Open.

The data is added to the Vocabulary.

Refactor Root to a preferred name, in this example, Partners:

Note that a reference to an attribute in an added domain requires the domain as a qualifier of the attribute when used in rules. In this example, the regular ShippingAddress.address1 in a Rulesheet would be differentiated from Partners.ShippingAddress.address1.