Skip to main content

Anatomy of an Operation JSON Object​

Understanding the structure of the JSON object that defines an operation is crucial for effectively creating and managing operations within Stage2. This section provides a detailed breakdown of each component of the JSON object, explaining its purpose and how it integrates with other aspects of an operation. By referencing previously discussed sections, this guide ensures you have a comprehensive understanding of how to structure your operation definitions.

Overview​

An operation in Stage2 is represented by a JSON object that encapsulates all the necessary metadata, configurations, and connections required for its execution within a workflow. This JSON object serves as the blueprint for the operation, informing Stage2 how to:

  • Instantiate the operation.
  • Configure its parameters, inputs, and outputs.
  • Integrate it seamlessly into larger workflows.
{
  name: "Operation Name",
  family: "operation_family",
  category: "operation_category",
  thumbnail: "thumbnail.png",
  parameters: {
    "Parameter Name": {
      type: "parameter_type",
      description: "Parameter description.",
      default_value: default_value,
      nullable: boolean,
      min: minimum_value,
      max: maximum_value,
    },
    // Additional parameters...
  },
  inputs: {
    "Input Name": {
      description: "Input description.",
      multiplicity: { min: minimum_connections, max: maximum_connections },
    },
    // Additional inputs...
  },
  output: {},
}

Detailed Breakdown​

Name (name)​

  • Type: string
  • Description: The human-readable name of the operation. This name is displayed within the Stage2 interface and should clearly convey the operation's purpose.
  • Example: "ParaView Shape Transform"

Family (family)​

  • Type: string
  • Description: Categorizes the operation into one of the primary families—source, compute, or sink. This classification determines the operation's role within workflows.
  • Possible Values: "source", "compute", "sink"
  • Example: "compute"
  • Reference: Operation Families

Category (category)​

  • Type: string
  • Description: Further classifies the operation within its family, often indicating the specific domain or functionality it pertains to.
  • Example: "processing"

Currently category has no supported functionality in Stage2. Included or otherwise, it will have no effect

Thumbnail (thumbnail)​

  • Type: string
  • Description: Path to an image file that visually represents the operation within the Stage2 webclient. Enhances user experience by providing visual cues.
  • Example: "thumbnail.png"

Parameters (parameters)​

Parameters in the Operation JSON object define the configurable settings for an operation. These settings allow users to customize the behavior of the operation and its interaction with the containerized tool.

Each parameter is defined by its type, additional constraints (such as nullable and choices), and optional metadata fields like description, defaultValue, or min/max values.

Note on choices While you are welcome to define parameter restrictions like min/max in addition to choices defintions, they will have no effect on the users selection of the final parameter value, since, if choices are defined the user will be restricted to one of the choices.

Parameter Types​

The following parameter types are currently supported in Stage2:

Integer​

Definition: Represents whole numbers (e.g., 1, 42).

Attributes:

  • nullable: If true, allows the value to be null.

  • defaultValue: Specifies the default integer value.

  • description (optional) : Description of the parameter

  • min/max (optional): Restricts the acceptable range of values.

  • choices (optional): Limits the value to a predefined set of integers.

    Example:

    "Integer Param Name": {
        "type": "integer",
        "description": "This is a description",
        "nullable": false,
        "defaultValue": 1,
        "min": 1
    }

Number​

Definition: Represents numeric values, including decimals (e.g., 1.25, 3.14159).

Attributes:

  • nullable: If true, allows the value to be null.
  • defaultValue: Specifies the default number value.
  • description (optional) : Description of the parameter
  • min/max (optional): Restricts the acceptable range of values.
  • choices (optional): Limits the value to a predefined set of numbers.

Example:

"Number Param Name": {
    "type": "number",
    "description": "This is a description",
    "nullable": false,
    "defaultValue": 1.5,
    "choices": [1.5, 2.6]
}

String​

Definition: Represents text values (e.g., "hello", "filename.txt").

Attributes:

  • nullable: If true, allows the value to be null.
  • description (optional) : Description of the parameter
  • defaultValue: Specifies the default string value.
  • choices (optional): Limits the value to a predefined set of strings.

Example:

"String Param Name": {
  "type": "string",
  "description": "This is a description",
  "nullable": false,
  "defaultValue": "This is choice 2",
  "choices": ["Choice 1", "Choices #3", "This is choice 2"]
}

Boolean​

Definition: Represents a true/false value.

Attributes:

  • nullable: If true, allows the value to be null.
  • defaultValue: Specifies the default boolean value (true, false or null if nullable:true).
  • description (optional) : Description of the parameter

Example:

"Boolean Param Name": {
    "type": "boolean",
    "description": "This is a description",
    "nullable": false,
    "defaultValue": false
}

Nested Parameters​

Array​

Definition: Represents a collection of parameters of the same type.

Attributes:

  • nullable: If true, allows the value to be null.
  • defaultValue: Specifies the default array value.
  • elementType: Describes the type and constraints of the array's elements.
  • description (optional) : Description of the parameter
  • minSize/maxSize (optional): Restricts the size of the array.
  • choices (optional): Limits the array elements to predefined sets of values.

Example:

    "Array Param Name": {
    "type": "array",
    "description": "This is a description",
    "nullable": false,
    "defaultValue": ["array 1 choice 1", "array 1 choice 2"],
    "choices": [
      ["array 1 choice 1", "array 1 choice 2"],
      ["array 2 choice 1", "array 2 choice 2"]
    ],
    "elementType": {
      "type": "string",
      "description": "This is a description",
      "nullable": false,
      "defaultValue": ""
    },
    "minSize": 1,
    "maxSize": 5
  }

Group​

Definition: Represents a collection of parameters that can be of different types.

Attributes:

  • parameters: Defines the nested parameters within the group, each with its own type and constraints.

Example:

"Group Param Name": {
    "type": "group",
    "parameters": {
        "Boolean Param Name": {
            "type": "boolean",
            "nullable": false,
            "defaultValue": true
        },
        "Integer Param Name": {
            "type": "integer",
            "nullable": false,
            "defaultValue": 0
        },
        "String Param Name": {
            "type": "string",
            "nullable": false,
            "defaultValue": ""
        }
    }
}

Deeper Nesting​

There is no limit to how deeply nested parameters can be (though, things can get confusing). Following the JSON structure conventions, you are free to nest arrays or groups within other arrays or groups.

Example

// Array of Array of Strings
"Array of Aray Param Name" : {
  "type": "array",
  "description": "This is a description",
  "nullable": false,
  "defaultValue": [],
  "elementType": {
    "type": "array",
    "nullable": false,
    "defaultValue": [],
    "elementType": {
      "type": "string",
      "nullable": false,
      "defaultValue": ""
    }
  }
}

Holistic Example​

Below is a comprehensive example of an operation with varying types of parameters, inputs and attributes for a Data Transform Operation:

```json
{
    "name": "Data Transformer",
    "family": "compute",
    "category": "data_processing",
    "thumbnail": "data_transformer.png",
    "parameters": {
        "Transformation Type": {
            "type": "string",
            "description": "Type of transformation to apply to the dataset.",
            "nullable": false,
            "defaultValue": "filter",
            "choices": ["filter", "aggregate", "normalize"]
        },
        "Threshold": {
            "type": "number",
            "description": "Threshold value for filtering data.",
            "nullable": false,
            "defaultValue": 0.75,
            "min": 0.0,
            "max": 1.0
        },
        "Enable Logging": {
            "type": "boolean",
            "description": "Flag to enable or disable detailed logging of the transformation process.",
            "nullable": false,
            "defaultValue": true
        },
        "Batch Sizes": {
            "type": "array",
            "description": "List of batch sizes to process data in chunks.",
            "nullable": false,
            "defaultValue": [100, 200, 300],
            "elementType": {
                "type": "integer",
                "nullable": false,
                "defaultValue": 100
            },
            "minSize": 1,
            "maxSize": 5
        },
        "Nested Array Example": {
            "type": "array",
            "description": "This is a description for a nested array parameter.",
            "nullable": false,
            "defaultValue": [
                ["option1", "option2"],
                ["option3", "option4"]
            ],
            "elementType": {
                "type": "array",
                "nullable": false,
                "defaultValue": [],
                "elementType": {
                    "type": "string",
                    "nullable": false,
                    "defaultValue": ""
                }
            },
            "minSize": 1,
            "maxSize": 3
        },
        "Advanced Settings": {
            "type": "group",
            "description": "Group of advanced settings for fine-tuning the transformation.",
            "parameters": {
                "Use GPU Acceleration": {
                    "type": "boolean",
                    "description": "Enable GPU acceleration for faster processing.",
                    "nullable": false,
                    "defaultValue": false
                },
                "Max Retries": {
                    "type": "integer",
                    "description": "Maximum number of retry attempts for failed operations.",
                    "nullable": false,
                    "defaultValue": 3,
                    "min": 0,
                    "max": 10
                },
                "Output Format": {
                    "type": "string",
                    "description": "Desired format for the output data.",
                    "nullable": false,
                    "defaultValue": "JSON",
                    "choices": ["JSON", "CSV", "XML"]
                }
            }
        }
    },
    "inputs": {
        "Input Dataset": {
            "description": "Primary dataset to be transformed.",
            "multiplicity": {
                "min": 1,
                "max": 1
            }
        },
        "Supplementary Data": {
            "description": "Additional data to enhance the transformation process.",
            "multiplicity": {
                "min": 0,
                "max": null //signals infinite
            }
        }
    },
    "output": {}
}