Design Patterns

A collection of design patterns to be used when working with the Field Systems data services.

Job Object Structure

Before using the patterns, it’s important to understand the structure of a Job object. It is composed of two main categories of data:

1. Core Properties The top-level fields in the JSON object are the Core Properties. These represent the fundamental, system-managed metadata for the job record.

Their structure is strict, read-only, and consistent across all jobTypes.

2. Custom Attributes (The jobType Schema) The attributes object contains the dynamic, business-specific data for the job.

Its structure is not fixed; it is defined by the JSON Schema registered for the root jobType (e.g., “Survey”, “fieldlinkScan”, “siteWorks”). This schema defines the specific fields, types, and validation rules for that jobType’s data.

You can retrieve the schema for a given job type using the GET /schema/jobType endpoint.

Custom Attributes & Schema

The custom attributes for a job are stored in the attributes object of an individual job record.

These attributes follow the schema registered for each jobType and can be retrieved using the GET /schema/{jobType} API end point. This schema definition is managed by the jobType owner. To request any changes or updates, a change request must be submitted to the Cortex team.

In addition to the normal JSON Schema type information, you can enhance this schema to add additional metadata for jobType attributes.

For instance, you might want to include SI storage units or fields that are only visible to administrators.

For this example we will add SI storage units to some attributes. Imagine we have the following schema types that need SI units.

"attributes": {
  "type": "object",
  "properties": {
    "area": {
      "type": "number"
    },
    "altitude": {
      "type": "number",
      "default": 0
    }
  }
}

The type information can be added like this.

Caution

Be careful not to use a type name already specified by JSON Schema.

"attributes": {
  "type": "object",
  "properties": {
    "area": {
      "si_units" : "sq_m",
      "type": "number"
    },
    "altitude": {
      "si_units" : "m",
      "type": "number",
      "default": 0
    }
  }
}

To request any changes or updates, a change request must be submitted to the Cortex team. Once published, applications will be able to GET the schema and use this new attribute metadata.

Tagging Attachments

Purpose

This pattern explains how we define the purpose or use of attachments, such as distinguishing a report from a design file.

When a file is attached to a job, its purpose is specified using the tags array on the attachment object.

These tags are not arbitrary strings; they are formally defined in the jobType schema to ensure consistency. The tags are defined in the schema’s $defs / attachmentTags section.
If your application uses the Field Data Service, don’t forget to include RootDataFile.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  ...

  "$defs": {
    "attachmentTags" : {
        "type" : "string",
        "description": "Possible tags are."
        "enum" : ["RootDataFile","Background","Design","Report","FieldData"]
    }
  }
}

When uploading a file via the PUT/POST /projects/{projectTrn}/jobs/{jobsId}/attachments endpoints, your application should use one or more of the predefined tags from this list.

Note: The enum of tags is specific to the jobType. For instance, RootDataFile is a common requirement indicating the main job file - eg .job, .spj etc.