JSON structure of a Block¶
For the import and export of PROOF Blocks, a JSON structure is used to define the Block's metadata, inputs, outputs, and other configuration details. This structure allows for easy sharing and reuse of Blocks across different PROOF installations. A Block JSON file typically includes the following key components:
- Block Metadata: This section contains general information about the Block, such as its ID, label, etc.
- Inputs: This section defines the inputs that the Block accepts, including their names, types, and whether they are required or optional.
- Outputs: This section defines the outputs that the Block produces, including their names and types.
Here is as an example the JSON structure for the PROOF Block FileWriter:
{
"id": "block_file_writer",
"name": "File Writer",
"description": "Write data to a file",
"containerImage": "ghcr.io/kit-iai-proof/proof-worker-python:1.4.0",
"communicationParadigm": "STEPBASED",
"programId": "prog_file_writer",
"inputs": [
{
"name": "file name",
"type": "string",
"phase": "INIT",
"required": true,
"modelVarname": "file_name",
"communicationType": "STEPBASED_STATIC",
"metadata": {}
},
{
"name": "mode",
"type": "string",
"phase": "INIT",
"modelVarname": "mode",
"required": false,
"communicationType": "STEPBASED_STATIC",
"metadata": {}
},
{
"name": "waitForSync",
"type": "string",
"phase": "INIT",
"modelVarname": "waitForSync",
"required": false,
"communicationType": "STEPBASED_STATIC",
"metadata": {}
},
{
"name": "data",
"type": "string",
"phase": "EXECUTE",
"modelVarname": "data",
"required": false,
"communicationType": "STEPBASED",
"metadata": {}
}
],
"outputs": [],
"startParameters": {}
}
This JSON structure can be used to import the Block into a PROOF installation or export it for sharing with others. The defined inputs and outputs ensure that the Block can be correctly integrated into PROOF Workflows.
Description of the JSON Fields¶
- id: A unique identifier for the Block.
- name: The display name of the Block.
- description: A brief description of the Block's functionality.
- containerImage: The Docker container image used to run the Block.
- communicationParadigm: The communication paradigm used by the Block (e.g., STEPBASED).
- programId: The identifier of the Program associated with the Block. This is an own JSON file.
- inputs: An array of input definitions for the Block. Each input includes:
- name: The visible name of the input.
- type: The data type of the input (e.g., string, integer).
- phase: The phase during which the input is used (e.g., INIT, EXECUTE).
- required: A boolean indicating whether the input is required at startup.
- modelVarname: The variable name used in the model for this input. In most cases, it matches the name.
- communicationType: The type of communication for this input (e.g., STEPBASED_STATIC, STEPBASED).
- metadata: Additional metadata for the input (can be any structure or empty).
- outputs: An array of output definitions for the Block. Each output includes:
- name: The visible name of the output.
- type: The data type of the output (e.g., string, integer).
- phase: The phase during which the output is produced (e.g., EXECUTE).
- modelVarname: The variable name used in the model for this output. In most cases, it matches the name.
- communicationType: The type of communication for this output (e.g., STEPBASED).
- metadata: Additional metadata for the output (can be any structure or empty).
- startParameters: A section for any additional parameters needed at the start and run of the Block (can be empty).
Synchronization Strategies¶
PROOF supports multiple synchronization strategies for controlling how Blocks execute:
WAIT_FOR_SYNC Strategy (Default)¶
The WAIT_FOR_SYNC strategy triggers model execution based on communication steps: - Blocks execute when explicitly triggered by the orchestrator during a communication step - Useful for time-step based simulations where all blocks advance together
ALL_VALUES Strategy (Version 1.3.0+)¶
The ALL_VALUES strategy triggers model execution when all required input values are available: - Blocks execute as soon as all required inputs have been provided - Enables more responsive and event-driven execution patterns - Useful for workflows where blocks can process inputs independently of simulation steps e.g. writing to file - Allows asynchronous data flow between blocks
Input Configuration¶
startValue Field¶
Starting with version 1.3.0, each input can include a startValue field: - Provides the initial value for inputs that participate in feedback loops - Enables proper initialization of iterative workflows and feedback loops
defaultValue Field¶
Starting with version 1.3.0, each input can include a defaultValue field: - Specifies a fallback value when no input value arrives in the expected time period - Applicable to both static and non-static inputs - Ensures robust handling of missing or delayed input values