Overview
Scale uses Projects to organize Tasks, the unit of work. Each type of Task (Image Annotation, Text Collection, Lidar Annotation) has many customizable input parameters that can be used when creating tasks to guide exactly how the tasks are formed and what the response will look like.
Task definitions can be stored on the Task level, the Project level, or a hybrid approach.
Refresher: What should a Project be?
If you're wondering how Projects, Tasks, and Batches all come together, we cover this in our Scale 101 sections.
Task vs. Project Level Parameters
Task Only
All Task parameters (definitions) are set when making the API call to create a Task. The Project has no parameters and is instead simply used just to collect and organize similar sets of tasks. The Task-specific endpoints and parameters documented in our docs would result in a "Task Only" approach.
Project Only
In a Project only approach, all task definitions are stored in a versioned set of project parameters. When creating a task, you only need to specify the attachment and other per-task fields, and the task will inherit all the parameters and task definitions from the project version.
Hybrid Approach
In the Hybrid approach, some task-level parameters are specified on the Project level, while others are defined on a per-task basis. This could be useful to take advantage of the project versioning while allowing flexibility for certain parameters that could change on a per-task basis.
Project-level Parameter Features
Versioning
Scale maintains a queryable list of all past project versions. You can quickly see what was in a given project version of the past. All Tasks will have a project_param_version field pointing to which version of the project parameters were used in that task. When creating tasks, you can specify which version of project parameters should be used.
Separation of Concerns
As you get more sophisticated, it's recommended to separate the taxonomy management from the task submission pipeline. The task submission should be fairly "dumb" in that it doesn't need to know all of the details about how a task should be labeled, it just knows that it needs to add a new attachment to a project for labeling - and that the project will dictate how this task will be labeled.
The project params can then be updated independently of the task submission process.
Default Values
Project-level Parameters are automatically passed down and combined with the task parameters when creating tasks within that project. In this way, you can set default values that you want to ensure are specified regardless of how tasks are submitted to the project. A common use-case might be the instructions - but you can specify any default you'd like.
How do I start using Project-level Parameters?
At the Project Level:
We will be leveraging the Update Parameters endpoint to set and create project parameter versions.
When Retrieving or Listing projects, information about the project parameters will be available in the paramHistory field.
At the Task Level:
Tasks will automatically use the latest version of project parameters. The parameters specified at the project level are automatically merged in with the task-level parameters. Parameters specified at the task level do override any default parameters that would be inherited by the project, with the exception of the instruction field, which works by concatenating the task level and project level instructions together.
You are able to specify previous versions of the project to use when creating tasks by specifying a project_param_version.
Examples
Check out some of our code examples of using this workflow to find out what it all looks like.