Main Content

MATLAB Function Signatures in JSON

For a RESTful client to acquire the function signatures of MATLAB® functions deployed to MATLAB Production Server™ using the discovery API, you must 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 have struct or cell data types as inputs or outputs, you can add their descriptions to the JSON file using typedef objects.

The JSON file does not support adding descriptions for datetime and enumeration values, although your MATLAB functions can have these data types as input or outputs.

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

Warning

The validateFunctionSignaturesJSON function does not support validating MATLAB Production Server <projectName>functionSignatures.json.

Example of a function signature JSON file.

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

Function Objects

Function objects automatically inherit their name from the name of the MATLAB functions that you add 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. Add a typedef object only if values to the argument objects are cells or structures. The JSON file template that the Production Server Compiler app generates does not have this object by default.

In the schema, indicate a typedef object by using the name _typedefs with its values as 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 as follows.

{
    "_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 as follows.

{
       "_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"
               }
           ]
       }
   }