MATLAB Function Signatures in JSON - MATLAB & Simulink (original) (raw)
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 theCreate 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 andenumeration 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 (MATLAB) function does not support validatingMATLAB Production Server _`<projectName>`_functionSignatures.json.
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.
| Property | Description | JSON 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.
The name of the input or output argument, specified as a JSON string. You must specify this property and its corresponding value. The name property does not need to match the argument name in the function, but it is a best practice for it to match any help documentation.
Example: "name":"myArgumentName"
The type property defines what MATLAB data type the argument must have.
| Value | Argument Description |
|---|---|
| "double" | Must be a double precision number |
| "single" | Must be a single precision number |
| "int8" | Must be an 8-bit signed integer |
| "uint8" | Must be an 8-bit unsigned integer |
| "int16" | Must be a 16-bit signed integer |
| "uint16" | Must be a 16-bit unsigned integer |
| "int32" | Must be a 32-bit signed integer |
| "uint32" | Must be a 32-bit unsigned integer |
| "int64" | Must be a 64-bit signed integer |
| "uint64" | Must be a 64-bit unsigned integer |
| "logical" | Must be a logical array |
| "char" | Must be a character array |
| "string" | Must be a string array |
For cell and struct, see Typedef Object.
The JSON file does not support adding descriptions fordatetime and enumeration values.
Example: { "name": "in", "type": ["double"] }
The size property defines the array dimensions of the inputs. It is a comma-separated list of integers.
Example: { "name": "in", "type": ["double", "size=1,1"] }
purpose — Description for Argument
The purpose property provides a description for the arguments.
Example: { "name": "in", "type": ["double", "size=1,1", "purpose": "Input argument" }
If you want to use international characters for the purpose argument, enable UTF-8 support for your server machine.
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" } ] } }