IBM Watson JSON Easy Tutorial

You probably know that you can build a Watson Chatbot solely by using the Watson GUI to create intents, entities, and dialogues, and subsequently glue them all together into a Watson Skill. For simple and small skills with less than ten or twenty of the mentioned elements, it will work fine. But for larger skills, that need to grow and be maintained, the GUI gets to troublesome and time-consuming, especially with many dialogue boxes referring to many intents!

Therefore IBM has made it possible to represent a Skill by the descriptive language JSON, alike XML or HTML, is only text and can be computer generated! This blogpost explains the basic elements of the Watson JSON structure and is mainly for developers and Watson architects.

Best practice for building effective Watson Assistant Chatbots with good and comprehensive Dialog Skills is done by (programmatically) creating the JSON code that defines the Skill, and then import it to your Watson Assistant in the IBM Cloud in order to create the Skill!

The JSON code itself is very structured, and basically only consists of four different blocks, which I will explain to you here.

It is a good idea to use a JSON parser while constructing the code, because wrong syntax of the JSON code is one of the biggest issues when importing Skills via JSON! There are many standalone and online tools for the job, and I often use the JSONFormatter:

https://jsonformatter.org/json-parser

My example is a simple chatbot, where you can ask for the address of a company, and use different synonyms for asking, and you will get back the answer “Our business is located in ‘Watson Square 5, NY 10040’ and ‘Discovery Avenue, AZ 85010′” or the usual “I didn’t get your meaning.” if the bot couldn’t recognize anything triggering an intent.

As you can see above, the INTENTS section of the bot starts with the keyword “intents”, followed by a “[” and the descriptor  “intent”: “descriptor_name”, which in our case is “business_address“.

After that you list all the examples of that Intent, overall defined by the descriptor “examples”, followed by each example.

A Watson Assistant Chatbot will normally contain many different intents, and they are then listed as sections beneath the first intent. The “intents” section ends with the “]”, which tells the importer, that all intents have been defined for import.

Remember to follow the JSON rules by getting all the “{“, “}”, “[“, “]” and commas right!

As for Intents, Entities has its own section “entities” and a descriptor “entity“:”descriptor_name” that defines the entity, which in our case is “business“.

Afterwards you list all the entity synonyms as “values“. The setting “fuzzy_match”: true means that you don’t have to write the exact intent to get a match – a partial match (like bureau <> bureu) will do, which is not the best choice in all cases!

A Watson Assistant Chatbot will normally contain many different entities, and they are then listed as sections beneath the first entity. The “entities” section ends with the “]”, which tells the importer, that all entities have been defined for import.

The DIALOG_NODES section normally consists of a minimum of three subsections, wherein the first is a “Welcome” and the last is the “Anything_else” (error handling) section. All the other subsections contain the real dialogues with the user and can be seen as handlers for the previous mentioned intents.

Each subsection has a name, defined by the descriptor “dialog_node” : “node name”. In our example the node names are: “Welcome“, “Business_Address” and “Anything_Else“.

To be able to define the right order of the dialogues when importing, each dialogue has the descriptor “previous_sibling“, which is, of course, not true for the “Welcome” dialogue that initiates the flow – it has no predecessor!

Some of the descriptors are system specific to Watson, such as “type” and “output”, where others are part of the flow. The one that links a dialogue to a specific intent is the descriptor “conditions”.

For the dialog_node “Business_Address”, the conditions is given the value “#business_address”, and as you might know from the Watson GUI, the “#” defines an intent! So the “Business_Address” dialogue is triggered by the questions in the #business_address intent.

The answer (return to the user) in the dialog_node is defined in values, and in our case it returns the two addresses for the company that we run.

The last block of the skill is the MAIN block, that mostly has a lot of system specific descriptors for the IBM Watson JSON. The most important to the user is the descriptor “name”, which simply defines the name of the whole skill! In our case “Business Address Skill”.

There can be many other descriptors defining a skill, making it quite more complex and sophisticated, but the ones shown here make up a simple skill!

To the left you can see how you upload the JSON code to the IBM Cloud in order to create the Watson Skill.

As you can see, there’s also a download menu item, and that’s where I first learned about Watson JSON, because here you can also export the JSON code from an existing Skill for investigation and further development.