parameters.json

Describe custom block metadata, user parameters, UI controls, and conditional parameter behavior in parameters.json.

The parameters.json file is included at the root of the directory of a custom block. It is used to describe the block itself and identify the parameters available for its configuration. The parameters defined in this file are the input options rendered for the block in Studio and passed into the block as arguments when the it is run.

File structure

The file can be considered in two sections: a header section and a parameters section. The header section identifies the block type and its associated metadata. The metadata required varies by block type. This information is followed by an array of parameters items.

AI labeling

type AIActionBlockParametersJson = {
    version: 1,
    type: 'ai-action',
    info: {
        name: string,
        description: string,
        requiredEnvVariables: string[] | undefined;
        operatesOn: ['images_object_detection' | 'images_single_label' | 'audio' | 'other'] | undefined;
    },
    parameters: DSPParameterItem[];
};

Parameter item

type DSPParameterItem = {
    // Rendered as the label
    name: string,
    // Default value
    value: string | number | boolean;
    // Type of UI element to render
    type: 'string' | 'int' | 'float' | 'select' | 'boolean' | 'bucket' | 'dataset' | 'flag' | 'secret';
    // Optional help text (rendered as a help icon, text is shown on hover)
    help?: string,
    // Parameter that maps back to your block (no spaces allowed)
    param: string,
    // When type is "select" lists all options for the dropdown menu
    // you can either pass in an array of strings, or a list of objects
    // (if you want to customize the label)
    valid?: (string | { label: string, value: string })[];
    // If this is set, the field is rendered as readonly with the text "Click to set"
    // when clicked the UI changes to a normal text box.
    optional?: boolean,
    // Whether the field should be rendered as readonly.
    // These fields are shown, but cannot be changed.
    readonly?: boolean,
    // If set, this item is only shown if the implementation version of the block matches
    // (only for processing blocks)
    showForImplementationVersion: number[] | undefined;
    // Show/hide the item depending on another parameter
    showIf: ({
        parameter: string,
        operator: 'eq' | 'neq',
        value: string,
    }) | undefined;
    // Processing blocks only. If set, a macro is created like:
    // #define EI_DSP_PARAMS_BLOCKCPPTYPE_PARAM     VALUE
    createMacro?: boolean,
    // When type is "select" the value passed into your block will be a string,
    // you can use configType to override the type (used during deployment only)
    configType?: string,
    // (Optional) UX section to show parameter in.
    section?: 'advanced' | 'modelProfiling';
    // Only valid for type "string". If set to true, renders a multi-line text area.
    multiline?: boolean,
    // If set, shows a hint about the input format below the input. Use this
    // sparingly, as it clutters the UI.
    hint?: string,
    // Sets the placeholder text on the input element (for types "string", "int", "float" and "secret")
    placeholder?: string,
};

File examples

Below you will find full examples of parameter files for the various types of blocks.

AI labeling

{
    "version": 1,
    "type": "ai-action",
    "info": {
        "name": "Bounding box labeling with OWL-ViT",
        "description": "Zero-shot object detector to automatically label objects using bounding boxes with OWL-ViT. To detect more complex objects you can combine this block with 'Bounding box re-labeling with GPT-4o'. First, roughly find objects using this block, then re-label (or remove) bounding boxes using the GPT4o block.",
        "requiredEnvVariables": [
            "BEAM_ENDPOINT",
            "BEAM_ACCESS_KEY"
        ],
        "operatesOn": [
            "images_object_detection"
        ]
    },
    "parameters": [
        {
            "name": "Prompt",
            "value": "A person (person, 0.2)",
            "type": "string",
            "help": "A prompt specifying the images to label. Separate multiple objects with a newline. You can specify the label and the min. confidence rating in the parenthesis.",
            "param": "prompt",
            "multiline": true,
            "placeholder": "A prompt specifying the images to label. Separate multiple objects with a newline. You can specify the label and the min. confidence rating in the parenthesis.",
            "hint": "Separate multiple objects with a newline. You can specify the label and the min. confidence rating in the parenthesis (e.g. 'A person (person, 0.2)')."
        },
        {
            "name": "Delete existing bounding boxes",
            "value": "no",
            "type": "select",
            "valid": [
                { "label": "No", "value": "no" },
                { "label": "Only if they match any labels in the prompt", "value": "matching-prompt" },
                { "label": "Yes", "value": "yes" }
            ],
            "param": "delete_existing_bounding_boxes"
        },
        {
            "name": "Ignore objects smaller than (%)",
            "optional": true,
            "value": 0,
            "type": "float",
            "param": "ignore-objects-smaller-than",
            "help": "Any objects where the area is smaller than X% of the whole image will be ignored"
        },
        {
            "name": "Ignore objects larger than (%)",
            "optional": true,
            "value": 100,
            "type": "float",
            "param": "ignore-objects-larger-than",
            "help": "Any objects where the area is larger than X% of the whole image will be ignored"
        },
        {
            "name": "Non-max suppression",
            "help": "Deduplicate boxes via non-max suppression (NMS)",
            "value": true,
            "type": "flag",
            "param": "nms"
        },
        {
            "name": "NMS IoU threshold",
            "help": "Threshold for non-max suppression",
            "value": 0.2,
            "type": "float",
            "param": "nms-iou-threshold",
            "showIf": {
                "parameter": "nms",
                "operator": "eq",
                "value": "true"
            }
        }
    ]
}

Parameter types

Parameter items are defined as JSON objects that contain a type property. For example:

{
    "name": "Scale axes",
    "value": 1.0,
    "type": "float",
    "help": "Multiplies axes by this number.",
    "param": "scale-axes"
}

The parameter type options available are shown in the table below, along with how the parameter is rendered in Studio and how it will be passed to your custom block. In general, parameter items are passed as command line arguments to your custom block script.

Type	Renders	Passes
Boolean	Checkbox	--<param-name> 1 (true) | --<param-name> 0 (false)
Bucket	Dropdown	--<param-name> "<bucket-name>"
Dataset	Dropdown	--<param-name> "<dataset-name>"
Flag	Checkbox	--<param-name> (true) | (false)
Float	Text box	--<param-name> <value>
Int	Text box	--<param-name> <value>
Secret	Text box	<param-name> (environment variable)
Select	Dropdown	--<param-name> <value>
String	Text box	--<param-name> "<value>"

Processing blocks do not receive command line arguments

Instead of command line arguments being passed to the block as shown above, processing blocks receive an HTTP request with the parameters in the request body, which are subsequently passed to the function generating the features in your processing block. In this case, dashes in parameter names are replaced with underscores before being passed to your function as arguments:

A processing block parameter named custom-processing-param is passed to your feature generation function as custom_processing_param.

Secrets are passed as environment variables instead of command line arguments

All parameter types rendered in Studio

Boolean

{
    "name": "Boolean example",
    "value": true,
    "type": "boolean",
    "help": "An example boolean parameter type to show how it is rendered.",
    "param": "do-boolean-action"
}

--do-boolean-action 1

Boolean parameter type rendered in Studio

Bucket

Only available for AI labeling, synthetic data, and transformation blocks

{
    "name": "Bucket example",
    "value": "",
    "type": "bucket",
    "help": "An example bucket parameter type to show how it is rendered.",
    "param": "bucket-example-param"
}

--bucket-example-param "edge-impulse-customers-demo-team"

Bucket parameter type rendered in Studio

Dataset

Only available for AI labeling, synthetic data, and transformation blocks

{
    "name": "Dataset example",
    "value": "",
    "type": "dataset",
    "help": "An example flag parameter type to show how it is rendered.",
    "param": "dataset-example-param"
}

--dataset-example-param "Gestures"

Dataset parameter type rendered in Studio

Flag

{
    "name": "Flag example",
    "value": true,
    "type": "flag",
    "help": "An example flag parameter type to show how it is rendered.",
    "param": "do-flag-action"
}

--do-flag-action

Flag parameter type rendered in Studio

Float

{
    "name": "Float example",
    "value": 0.1,
    "type": "float",
    "help": "An example float parameter type to show how it is rendered.",
    "param": "float-example-param"
}

--float-example-param 0.1

Float parameter type rendered in Studio

Int

{
    "name": "Int example",
    "value": 1,
    "type": "int",
    "help": "An example int parameter type to show how it is rendered.",
    "param": "int-example-param"
}

--int-example-param 1

Int parameter type rendered in Studio

Secret

Only available for AI labeling, synthetic data, and transformation blocks

{
    "name": "Secret example",
    "value": "",
    "type": "secret",
    "help": "An example secret parameter type to show how it is rendered.",
    "param": "SECRET_EXAMPLE_PARAM"
}

SECRET_EXAMPLE_PARAM

Secret parameter type rendered in Studio

Secret parameter type (hidden) rendered in Studio

Select

{
    "name": "Select example 1",
    "value": "1",
    "type": "select",
    "help": "An example select parameter type to show how it is rendered.",
    "param": "select-example-param-1",
    "valid": [ "1", "3", "10", "30", "100","1000" ]
}

--select-example-param-1 "1"

Select parameter type without labels rendered in Studio

Select parameter type valid options without labels rendered in Studio

---

{
    "name": "Select example 2",
    "value": "1",
    "type": "select",
    "help": "An example select parameter type to show how it is rendered.",
    "param": "select-example-param-2",
    "valid": [
        { "label": "One", "value": "1" },
        { "label": "Three", "value": "3" },
        { "label": "Ten", "value": "10" },
        { "label": "Thirty", "value": "30" },
        { "label": "One hundred", "value": "100" },
        { "label": "One thousand", "value": "1000"}
    ]
}

--select-example-param-2 "1"

Select parameter type with labels rendered in Studio

Select parameter type valid options with labels rendered in Studio

String

{
    "name": "String example",
    "value": "An example string",
    "type": "string",
    "help": "An example string parameter type to show how it is rendered.",
    "param": "string-example-param"
}

--string-example-param "An example string"

String parameter type rendered in Studio

Parameter groups

Only available for processing blocks

Processing block parameters can contain multiple groups to better organize the options when rendered in Studio. Each string entered as value for the group property is rendered as a header element.

"parameters": [
    {
        "group": "Example parameter group 1",
        "items": [
            {
                "name": "Boolean example",
                "value": false,
                "type": "boolean",
                "help": "An example boolean parameter type to show how it is rendered.",
                "param": "do-boolean-action"
            },
            {
                "name": "Flag example",
                "value": false,
                "type": "flag",
                "help": "An example flag parameter type to show how it is rendered.",
                "param": "do-flag-action"
            }
        ]
    },
    {
        "group": "Example parameter group 2",
        "items": [
            {
                "name": "Float example",
                "value": 1.0,
                "type": "float",
                "help": "An example float parameter type to show how it is rendered.",
                "param": "float-example-param"
            }
        ]
    }
]

Processing parameters grouped into two groups

Parameter logic

showIf

Parameters can be conditionally shown based on the value of another parameter using the showIf property.

{
    "name": "Boolean example",
    "value": false,
    "type": "boolean",
    "help": "An example boolean parameter type to show how it is rendered.",
    "param": "do-boolean-action"
},
{
    "name": "Int example",
    "value": 1,
    "type": "int",
    "help": "An example int parameter type to show how it is rendered.",
    "param": "int-example-param",
    "showIf": {
            "parameter": "do-boolean-action",
            "operator": "eq",
            "value": "true"
        }
},
{
    "name": "Float example",
    "value": 1.0,
    "type": "float",
    "help": "An example float parameter type to show how it is rendered.",
    "param": "float-example-param"
}

Parameter conditionally hidden based on another parameter

Parameter conditionally shown based on another parameter

showForImplementationVersion

Only available for processing blocks

Processing blocks can have different versions, which allows you to add new functionality to existing blocks without breaking earlier implementations. You are able to shown/hide parameters based on the implementation version set in the latestImplementationVersion property of the processing block.

A processing block set to version 4:

"info": {
    "title": "Spectral Analysis",
    ...
    "latestImplementationVersion": 4
}

A parameter shown only for implementation versions 3 and 4:

{
    "name": "Type",
    "value": "FFT",
    "help": "Type of spectral analysis to apply",
    "type": "select",
    "valid": [ "FFT", "Wavelet" ],
    "param": "analysis-type",
    "showForImplementationVersion": [ 3, 4 ]
}