MATLAB Function Signatures in JSON

In order for a RESTful client to acquire the function signatures of MATLAB® functions deployed to MATLAB Production Server™ using the discovery API, you need to embed information about your MATLAB functions in a JSON file while packaging your deployable archive.

After adding the MATLAB functions to deploy to the Production Server Compiler app, in the Include MATLAB function signature file section, select the Create File button. This action creates a template of the JSON file with the name <projectName>functionSignatures.json.

The <projectName>functionSignatures.json file is a single JSON object. It contains a schema version and a list of function objects. Each function object contains a list of signature objects, and each signature object contains a list of argument objects.

If your MATLAB functions pass struct or cell data types, you can add their descriptions to the JSON file as well.

You can access the JSON object file from the server by using the Discovery Service.

The schema version has a value that is a JSON string in the format <major#>.<minor#>.<patch#>, with each number specified as a nonnegative integer.

Function Objects

Function objects automatically inherit their name from the name of the MATLAB functions you have added to the project. The purpose line for the function object is inherited from the function description provided in the MATLAB function. The value of each function object is a signature object.

{
  "functionName1": { signatureObj1},
  "functionName2": { signatureObj2}
}

Signature Objects

A signature object defines the list of input and output arguments and supported platforms for the function. The value of the properties is an array of argument objects.

{
  "functionName1":
  {
     "inputs": [ argumentObj1, argumentObj2 ]
  }
}
Each signature can include the following properties.

PropertyDescriptionJSON Data Type of Value

inputs

List of function input arguments

Array of argument objects

outputs

List of function output arguments

Array of argument objects

Argument Objects

Argument objects define the information for each of the input and output arguments.

{
  "functionName1":
  {
     "inputs":
     [
        {"name":"in1",  "type":["double"], "purpose":"<input 1 description>"},
        {"name":"in2",  "type":["logical"], "purpose":"<input 2 description>"}
     ]
  }
}
The order that the inputs appear in the JSON file is significant. For example, in a call to the functionName1 function, in1 must appear before in2.

Each argument object can include the following properties.

 name — Name of Argument

 type — Data Type of Argument

 size — Array Dimensions

 purpose — Description for Argument

Typedef Object

A typedef object defines cell arrays and structures. It needs to be defined only if any of the values to the argument objects are cells or structures. The JSON file template generated does not have this object by default, you are expected to add it if and when needed.

In the schema, it is indicated using the name _typedefs and its value is the name of one or more cell or structure objects. The type is the same as the argument object.

Example of Using a Homogeneous Cell Array: If a MATLAB function sortinput, accepts a cell array as input and returns a cell array as output, and each cell in the input consists of a structure, its JSON representation is:

{
    "_schemaVersion": "1.1.0",
    "_typedefs" : {
        "struct_names_scores_of_students": {
            "purpose": "Names and scores of students",
            "type": "struct",
            "fields": [
                {"name": "Name",  "type": "char"},
                {"name": "Score", "type": ["double","size=1,1"]}
            ]
        },
        "cell_student_information": {
            "purpose": "Cell representing student information",
            "type": "cell",
            "elements": {
                "type": "struct:struct_names_scores_of_students"
            }
        }
    },
    "sortinput": {
        "inputs": [
            {
                "name": "unsorted_input",
                "type": ["cell:cell_student_information"],
                "purpose": "Unsorted list of students and their scores"
            }
        ],
        "outputs": [
            {
                "name": "sorted_output",
                "type": ["cell:cell_student_information"],
                "purpose": "Sorted list of students with respect to their scores"
            }
        ]
    }
}

Example of Using a Heterogeneous Cell Array: If a MATLAB function organize, accepts a cell array with length 3 containing a character, a square matrix, and a string as input, and returns a vector of doubles as output, its JSON representation is:

{
       "_typedefs": {
           "cell_het_mydata": {
               "purpose": "cell containing character, matrix, and string",
               "type" : "cell",
               "elements" : [
                   { "type": ["char", "size=1,1"], "purpose": "cell element 1 is a character" },
                   { "type": ["double", "size=N,N"], "purpose": "cell element 2 is a square matrix" },
                   { "type": "char", "purpose": "cell element 3 is a string" }
           ]
       },
       "organize": {
           "inputs": [
               {
                   "name": "data",
                   "type": ["cell:cell_het_mydata","size=3,1"],
                   "purpose": "heterogenous cell array"
               }
           ],
           "outputs": [
               {
                   "name": "numerator",
                   "type": "double",
                   "purpose": "result of function"
               }
           ]
       }
   }

Related Topics