API versions

As Knowledge Model Management has evolved more functionality has been added. Semantic Enhancement has added the ability to view this. However, some of this functionality breaks the original contract on the API. Therefore, we have added the ability to render the SES results in different versions. To select the version of the output format you would like, for REST model results, the first path element after the “ses” itself, should be the version number. If this is not present then SES output will be v1.0 (legacy writer) or v1.2 (one field writer). For CGI style requests append the version to the end of the template parameter (e.g. template=service.xml1.2 or template=service.json1.2).

V1.0

This is the legacy version - nearly backward compatible with the output generated by SES from Semaphore 3.x - the differences in output are available.

V1.1

In many places in SES v1.0, we output concepts related to the current one, in lists the form

<FIELD FREQ=“0” ID=“b0eb4c12-4857-4391-aac6-e68c688d3c46” NAME=“term”>Another concept</FIELD>

We had removed the “CLASS” attribute from the element because with Knowledge Model Management it is possible to have multiple classes on a single concept. By specifying v1.1 or greater, you can now get this class information. Because of this possibility of having multiple classes on a concept each class is output as a separate element

<FIELD FREQ=“0” ID=“b0eb4c12-4857-4391-aac6-e68c688d3c46” NAME=“Another concept”>
    <CLASS NAME="Concept"/>
</FIELD>

Note we have also removed the redundant “NAME” attribute on the FIELD element.

The JSON equivalent is that we have added to each “field” object a new property, “classes” this an array containing a list of the classes attached to this concept.

This API version was first introduced for Semaphore 4.1.7 in September 2017.

V1.2

In Knowledge Model Management, it is possible to have multiple values for the same type of metadata. For the XML output, this is not a problem as we are outputting each instance as a separate metadata element. However, in the JSON output, in older versions of the API, we output the metadata fields as map from metadata name to metadata value as a string. This format cannot cope with multiple values.

To fix this, in the JSON format, we now output the metadata as a map from metadata name to metadata value as an array of strings - except for URI, which is still presented as a string as multiple values of this cannot be present.

Prior to V1.2

      "metadata" : {
        "editorial note" : "Editorial Note 2",
        "URI" : "http://example.com/OrderedModel#ChildConcept2"
      }

V1.2 and forward

      "metadata" : {
        "editorial note" : [ "Editorial Note 1", "Editorial Note 2" ],
        "URI" : "http://example.com/OrderedModel#ChildConcept2"
      }

This API version was first available in Semaphore 4.1.15 (February 2018).