Recipe Data

The recipe data is a JSON document that defines the actual data and configuration on which a recipe will run. It will describe all of the data being passed to the recipe’s inputs, as well as the workspace for storing the output for all of the recipe’s jobs. The recipe data is required when creating and queuing a recipe.

Consider our previous example recipe definition from Recipe Definition. The recipe data for creating a recipe with that example definition could be defined as follows:

Example recipe data:

{
   "version": "1.0",
   "input_data": [
      {
         "name": "image",
         "file_id": 1234
      },
      {
         "name": "georeference_data",
         "file_id": 1235
      }
   ],
   "workspace_id": 12
}

The input_data value is a list detailing the data to pass to each input in the recipe. In this case the input called image that takes a PNG image file is being passed a file from the Scale system that has the unique ID 1234, and the input called georeference_data which takes a CSV file is being passed a Scale file with the ID 1235. The workspace_id value indicates that any files produced by the jobs in the recipe should be stored in the workspace with the unique ID 12. To see all of the options for defining recipe data, please refer to the Recipe Data Specification below.

Recipe Data Specification Version 1.0

A valid recipe data is a JSON document with the following structure:

{
   "version": STRING,
   "input_data": [
      {
         "name": STRING,
         "value": STRING
      },
      {
         "name": STRING,
         "file_id": INTEGER
      },
      {
         "name": STRING,
         "file_ids": [
            INTEGER,
            INTEGER
         ]
      }
   ],
   "workspace_id": INTEGER
}

version: JSON string

The version is an optional string value that defines the version of the data specification used. This allows updates to be made to the specification while maintaining backwards compatibility by allowing Scale to recognize an older version and convert it to the current version. The default value for version if it is not included is the latest version, which is currently 1.0. It is recommended, though not required, that you include the version so that future changes to the specification will still accept your recipe data.

input_data: JSON array

The input_data is a list of JSON objects that define the actual data the recipe receives for its inputs. If not provided, input_data defaults to an empty list (no input data). For the recipe data to be valid, every required input in the matching recipe definition must have a corresponding entry in this input_data field. The JSON object that represents each input data has the following fields:

name: JSON string

The name is a required string that gives the name of the input that the data is being provided for. It should match the name of an input in the recipe’s definition. The name of every input in the recipe data must be unique.

The other fields that describe the data being passed to the input are based upon the type of the input as it is defined in the recipe definition, see Recipe Definition Specification Version 1.0. The valid types from the recipe definition specification are:

property

A “property” input has the following additional field:

value: JSON string

The value field contains the string value that will be passed to the “property” input.

file

A “file” input has the following additional field:

file_id: JSON number

The required file_id field contains the unique ID of a file in the Scale system that will be passed to the input. The file must meet all of the criteria defined in the recipe definition for the input.

files

A “files” input has the following additional field:

file_ids: JSON array

The required file_ids field is a list of unique IDs of the files in the Scale system that will be passed to the input. Each file must meet all of the criteria defined in the recipe definition for the input. A “files” input will accept a file_id field instead of a file_ids field (the input will be passed a list containing the single file).

workspace_id: JSON number

The workspace_id is required if any of the jobs in the recipe produce any output files. The workspace_id value is an integer providing the unique ID of the workspace to use for storing any files produced by the recipe’s jobs.