Skip to main content

Common Info

Contains information about details that are shared between all API actions

Section

Description

JSON Action request

details the API action to be performed and its associated parameters.

JSON Action response

provides the result of the API request.

responseOptions

allows the user to customize how the server returns data and properties.

JSONPath

enables users to navigate and select specific elements or values within a JSON document.

propertyPath

specifies the location of a value within an existing JSON document.

recordPath

specifies the precise location of a value within a database record.

JSON Conventions

identifies JSON conventions that FairCom applies to JSON formatting.

JSONPath

Use JSONPath to query for JSON values

Several of FairCom's JSON API properties, including "propertyPath" and "recordPath", use JSONPath to specify the location of properties in a JSON document.

FairCom's implementation of JSONPath

  • It uses the period "." character to define the nesting of properties in objects, such as "personNames.givenName".

  • It uses straight brackets to define the position of a value in an array, such as "favoriteFoods[0]".

    • The first item in an array is always 0.

  • It supports the last keyword to refer to the last item in the array, such as "favoriteFoods[last]".

  • It also supports referencing elements before the last item in the array, such as "favoriteFoods[last-1]" and "favoriteFoods[last-2]".

  • FairCom's JSONPath does not use "$." to refer to the root object.

    • If you use an online JSONPath evaluator to create JSONPath expressions, such as jsonpath.com, you may need to add "$." to the JSONPath to make it work, such as $.personNames.legalName[1].

    • When you want to use a JSONPath that you created in an online JSONPath evaluator, you need to remove the "$." from you JSONPath expressions.

Example JSON document with property paths

The "jsonPaths" property contains a JSONPath for each property in the document.

{  
  "id": 1,
  "type": "person",
  "birthdate": "2000-01-01",
  "favoriteFoods": [ "pizza", "ice cream", "steak" ],


  "personNames": {
    "givenName": "Michael",
    "surname": "Bowers",
    "nickname": "Mike",
    "legalName": [ "Michael", "Bowers" ]
  },
  
  "emailList": [
    {
      "emailPurpose": "home",
      "emailAddress": "myhome@gmail.com"
    },
    {
      "emailPurpose": "work",
      "emailAddress": "mywork@gmail.com"
    }    
  ]
}

Examples using JSONPath property to read and write JSON values

JSONPath can refer to any value in the previous JSON document.

Table 6. JSONPath examples

JSONPath

Value

"id"

1

"type"

"person"

"birthdate"

"2000-01-01"

"favoriteFoods"

[ "pizza", "ice cream", "steak" ]

"favoriteFoods[0]"

"pizza"

"favoriteFoods[1]"

"ice cream"

"favoriteFoods[2]"

"steak"

"favoriteFoods[last]"

"steak"

"favoriteFoods[last-1]"

"ice cream"

"favoriteFoods[last-2]"

"pizza"

"personNames" 

{
  "givenName": "Michael",
  "surname": "Bowers",
  "nickname": "Mike",
  "legalName": [ "Michael", "Bowers" ]
}

"personNames.givenName"

"Michael"

"personNames.surname"

"Bowers"

"personNames.nickname"

"Mike"

"personNames.legalName"

[ "Michael", "Bowers" ]

"personNames.legalName[0]"

"Michael"

"personNames.legalName[1]"

"Bowers"

"emailList"

"emailList": 
[
  {
    "emailPurpose": "home",
    "emailAddress": "myhome@gmail.com"
  },
  {
    "emailPurpose": "work",
    "emailAddress": "mywork@gmail.com"
  }    
]

"emailList[0]"

{
  "emailPurpose": "home",
  "emailAddress": "myhome@gmail.com"
}

"emailList[0].emailPurpose"

"home"

"emailList[0].emailAddress"

"myhome@gmail.com"

"emailList[1]"

{
  "emailPurpose": "work",
  "emailAddress": "mywork@gmail.com"
}

"emailList[1].emailPurpose"

"work"

"emailList[1].emailAddress"

"mywork@gmail.com"



FairCom JSONPath features

FairCom supports the following JSONPath features to read or write one JSON value:

  • The property selector . identifies a JSON property, such as .humidity.

  • You can nest property selectors, such as .humidity.temperature.

  • The array element selector [n] uses a zero-based number to specify one array element, such as .temperatures[0].

    • You can also use .temperatures[last] to retrieve the last element.

    • You can also use .temperatures[last-1] to retrieve the element before the last element.

  • You can mix property and array element selectors, such as .humidity.temperatures[2].celsius.

FairCom JSONPath limitations

FairCom's JSONPath feature supports reading and writing one JSON value. Thus, it does not support JSONPath features that return multiple values:

  • The recursive descent .. wildcard returns all values associated with the specified property name, such as ..name.

  • The wildcard expression * selects all child items, such as all the array items in names[*] or all the child properties in address.*.

  • Array range expressions select more than one value, such as [index1, index2, ...], [start:end], [start:], [:n], [-n:], [?(expression)], and [(expression)].

  • @ to represent the current node in expressions.

  • The root expression $ typically occurs at the beginning of the JSONPath statement. FairCom assumes JSONPath starts with the root node; thus, you must omit $.

  • FairCom also does not support embedded expressions.

FairCom's JSON API uses JSONPath to precisely locate values within JSON documents, particularly for properties like "propertyPath" and "recordPath". This implementation navigates nested objects using dot notation (e.g., "personNames.givenName") and accesses array elements using bracket notation (e.g., "favoriteFoods[0]"), supporting both numerical indices and the "last" keyword for flexible array referencing, including offsets like "favoriteFoods[last-1]". A key distinction from some online JSONPath evaluators is that FairCom's version does not require the "$." prefix for the root object, meaning users should remove it when adapting expressions from external tools.

JSONPath query syntax
how to query JSON data
JSON value extraction
JSON navigation
JSON data paths
JSONPath
JSON API JSONPath
propertyPath JSON API
recordPath JSON API
JSONPath dot notation
JSONPath array access brackets
JSONPath array index
JSONPath last keyword
JSONPath negative indexing
JSONPath root element
JSONPath nested objects
JSONPath examples
how to use JSONPath in API
JSONPath for data manipulation
JSONPath for reading JSON
JSONPath for writing JSON

FairCom JSON Conventions

A JSON string may store any UTF-8 character. The following characters must be escaped in JSON.

  • \ is escaped as \\

  • " is escaped as \"

  • Backspace is escaped as \b

  • Formfeed is escaped as \f

  • Linefeed is escaped as \n

  • Carriage Return is escaped as \r

  • Horizontal Tab is escaped as \t

  • Special Unicode characters may be included using a hexadecimal Unicode escape sequence that is at least four digits and may be up to twelve digits.

    \uABCD

Example property paths that group related properties

The MTConnect protocol provides metadata about each data value that you collect. This metadata includes the data type, category, device ID, component ID, and data item ID.  You may want to include this metadata in the JSON documents generated by FairCom's MTConnect connector. This metadata is useful for troubleshooting and providing context. The MTConnect timestamp is particularly useful because it tracks the actual time the device collected the data.

You can use property paths to organize a JSON document to associate a data value with its metadata. One approach is to nest related properties inside the same JSON object. Another approach is to add the same name prefix to related properties.

The examples in this topic use the following MTConnect XML as the data source for generating JSON results.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

Grouping related properties in the same parent object

The following "createInput" example configures the MTConnect Connector to nest related properties inside a "temperature" object. This approach has the advantage of a short, easy-to-read property names, but the disadvantage of a more complex JSON structure.

{
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "mymtconnect",
    "serviceName": "mtconnect",
    "settings": {
      "host": "195.167.1.5:5000",
      "propertyMapList": [
        {
          "propertyPath": "temperature.value",
          "dataType": "string",
          "mtconnectDeviceUuid": "X1_373f-4ab9-9c7a-173edd23e4f3",
          "mtconnectDataItemId": "X1_Stamper1_Temperature",

          "mtconnectCategoryPropertyPath": "temperature.category",
          "mtconnectComponentNamePropertyPath": "temperature.component",
          "mtconnectDataItemIdPropertyPath": "temperature.dataItemId",
          "mtconnectDataNamePropertyPath": "temperature.dataName",
          "mtconnectDataTypePropertyPath": "temperature.dataType",
          "mtconnectDeviceNamePropertyPath": "temperature.device",
          "mtconnectDeviceUuidPropertyPath": "temperature.deviceUuid",
          "mtconnectSequencePropertyPath": "temperature.sequence",
          "mtconnectTimestampPropertyPath": "temperature.timestamp"
        }
      ]
    },
    "tableName": "mtconnectTable"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

When configured with the previous "createInput" example, FairCom's MTConnect Connector collects data and generates a JSON document like the following example.

{
  "temperature": 
  {
    "value": 20.1,
    "category": "SAMPLE",
    "component": "Stamper1",
    "dataItemId": "X1_Stamper1_Temperature",
    "dataName": "Temperature",
    "dataType": "REAL",
    "device": "Device1",
    "deviceUuid": "X1_373f-4ab9-9c7a-173edd23e4f3",
    "sequence": 5,
    "timestamp": "2010-04-06T06:19:35.153141"
  }
}

Grouping related properties using prefixed property names

The following "createInput" example configures the MTConnect Connector to name related properties with the same "temperature" prefix. This approach has the advantage of a simpler JSON structure, but the disadvantage of longer property names.

{
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "mymtconnect",
    "serviceName": "mtconnect",
    "settings": {
      "host": "195.167.1.5:5000",
      "propertyMapList": [
        {
          "propertyPath": "temperatureValue",
          "dataType": "string",
          "mtconnectDeviceUuid": "X1_373f-4ab9-9c7a-173edd23e4f3",
          "mtconnectDataItemId": "X1_Stamper1_Temperature",

          "mtconnectCategoryPropertyPath": "temperatureCategory",
          "mtconnectComponentNamePropertyPath": "temperatureComponent",
          "mtconnectDataItemIdPropertyPath": "temperatureDataItemId",
          "mtconnectDataNamePropertyPath": "temperatureDataName",
          "mtconnectDataTypePropertyPath": "temperatureDataType",
          "mtconnectDeviceNamePropertyPath": "temperatureDevice",
          "mtconnectDeviceUuidPropertyPath": "temperatureDeviceUuid",
          "mtconnectSequencePropertyPath": "temperatureSequence",
          "mtconnectTimestampPropertyPath": "temperatureTimestamp"
        }
      ]
    },
    "tableName": "mtconnectTable"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

When configured with the previous "createInput" example, FairCom's MTConnect Connector collects data and generates a JSON document like the following example.

{
  "temperatureValue": 20.1,
  "temperatureCategory": "SAMPLE",
  "temperatureComponent": "Stamper1",
  "temperatureDataItemId": "X1_Stamper1_Temperature",
  "temperatureDataName": "Temperature",
  "temperatureDataType": "REAL",
  "temperatureDevice": "Device1",
  "temperatureDeviceUuid": "X1_373f-4ab9-9c7a-173edd23e4f3",
  "temperatureSequence": 5,
  "temperatureTimestamp": "2010-04-06T06:19:35.153141"
}