API DocumentationProduct Documentation

IDS Conventions - Schema Templates

Suggest Edits

❗️

Location Changed

The content of this page has been moved to TetraScience Confluence and it's not public-facing anymore. We will revise this page once self-service IDS is available.

Table of Content

Background

To ensure IDS schema consistency across multiple IDSs, use the supplied schema templates provided below.

Commonly Used Definitions

Add the schema template to the definitions section of your IDS, and reference the property in other parts of your IDS using "$ref": "#/definitions/<property>"

Nullable String

{
  "nullable_string": {
    "type": [
      "string",
      "null"
    ]
  }
}

Nullable Number

{
  "nullable_number": {
    "type": [
      "number",
      "null"
    ]
  }
}

Nullable Boolean

{
  "nullable_boolean": {
    "type": [
      "boolean",
      "null"
    ]
  }
}

Key Value Object

{
  "key_value_object": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "key",
      "value"
    ],
    "properties": {
      "key": {
        "$ref": "#/definitions/nullable_string"
      },
      "value": {
        "$ref": "#/definitions/nullable_string"
      }
    }
  }
}

Key Value Unit Object

{
  "key_value_unit_object": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "key",
      "value",
      "unit"
    ],
    "properties": {
      "key": {
        "$ref": "#/definitions/nullable_string"
      },
      "value": {
        "$ref": "#/definitions/nullable_number"
      },
      "unit": {
        "$ref": "#/definitions/nullable_string"
      }
    }
  }
}

Value Unit Object

{
  "value_unit_object": {
    "type": "object",
    "required": [
      "value",
      "unit"
    ],
    "additionalProperties": false,
    "properties": {
      "value": {
        "$ref": "#/definitions/nullable_number"
      },
      "unit": {
        "$ref": "#/definitions/nullable_string"
      }
    }
  }
}

Firmware

GSF. Not required. Extendable. You need to use the schema below as the base template. You can't remove fields from the base template and you can't reduce the required list.

{
  "firmware": {
    "type": "array",
    "items": {
      "type": "object",
      "required": [
        "name",
        "version"
      ],
      "properties": {
        "name": {
          "$ref": "#/definitions/nullable_string"
        },
        "version": {
          "$ref": "#/definitions/nullable_string"
        }
      }
    }
  }
}

Software

GSF. Not required. Extendable. You need to use the schema below as the base template. You can't remove fields from the base template and you can't reduce the required list.

{
  "software": {
    "type": "array",
    "items": {
      "type": "object",
      "required": [
        "name",
        "version"
      ],
      "properties": {
        "name": {
          "$ref": "#/definitions/nullable_string"
        },
        "version": {
          "$ref": "#/definitions/nullable_string"
        }
      }
    }
  }
}

GSFs

Systems

GSF. Not required. Extendable. You need to use the schema below as the base template. You can't remove fields from the base template and you can't reduce the required list.

{
  "systems": {
    "type": "array",
    "items": {
      "type": "object",
      "required": [
        "vendor",
        "model",
        "type"
      ],
      "additionalProperties": false,
      "properties": {
        "vendor": {
          "$ref": "#/definitions/nullable_string"
        },
        "model": {
          "$ref": "#/definitions/nullable_string"
        },
        "type": {
          "$ref": "#/definitions/nullable_string"
        }
      }
    }
  }
}

GSFs you can choose to use in systems are in the schema below. If you choose to use firmware or software, please use the schemas defined in the definitions section.

{
        "id": {
          "$ref": "#/definitions/nullable_string"
        },
        "name": {
          "$ref": "#/definitions/nullable_string"
        },
        "serial_number": {
          "$ref": "#/definitions/nullable_string"
        },
        "firmware": {
          "$ref": "#/definitions/firmware"
        },
        "software": {
          "$ref": "#/definitions/software"
        }
}

Users

GSF. Not required. Extendable.

The exact schema needs to be copied to every schema.json even if the raw data doesn’t have user info.

You should determine if certain fields are required based on the instrument you are working with and put into required field.

"users": {
  "type": "array",
  "items": {
    "type": "object",
    "required": [],
    "additionalProperties": false,
    "properties": {
      "id": {
        "$ref": "#/definitions/nullable_string",
        "description": "User ID"
      },
      "name": {
        "$ref": "#/definitions/nullable_string",
        "description": "Username"
      },
      "type": {
        "$ref": "#/definitions/nullable_string",
        "description": "User type or role"
      }
    }
  }
}

Samples

GSF. Not required. Non-Extendable.

The exact schema needs to be copied to every schema.json even if the raw data doesn’t have sample info.

You should determine if certain fields are required based on the instrument you are working with and put into required field.

"samples": {
  "type": "array",
  "items": {
    "type": "object",
    "required": [],
    "additionalProperties": false,
    "properties": {
      "id": {
        "$ref": "#/definitions/nullable_string"
      },
      "barcode": {
        "$ref": "#/definitions/nullable_string"
      },
      "name": {
        "$ref": "#/definitions/nullable_string"
      },
      "batch": {
        "type": "object",
        "required": [],
        "additionalProperties": false,
        "properties": {
          "id": {
            "$ref": "#/definitions/nullable_string"
          },
          "name": {
            "$ref": "#/definitions/nullable_string"
          },
          "barcode": {
            "$ref": "#/definitions/nullable_string"
          }
        }
      },
      "set": {
        "type": "object",
        "required": [],
        "additionalProperties": false,
        "properties": {
          "id": {
            "$ref": "#/definitions/nullable_string"
          },
          "name": {
            "$ref": "#/definitions/nullable_string"
          }
        }
      },
      "lot": {
        "type": "object",
        "required": [],
        "additionalProperties": false,
        "properties": {
          "id": {
            "$ref": "#/definitions/nullable_string"
          },
          "name": {
            "$ref": "#/definitions/nullable_string"
          }
        }
      },
      "location": {
        "type": "object",
        "required": [],
        "additionalProperties": false,
        "properties": {
          "position": {
            "$ref": "#/definitions/nullable_string"
          },
          "row": {
            "$ref": "#/definitions/nullable_number"
          },
          "column": {
            "$ref": "#/definitions/nullable_number"
          },
          "holder": {
            "type": "object",
            "required": [],
            "additionalProperties": false,
            "properties": {
              "name": {
                "$ref": "#/definitions/nullable_string"
              },
              "type": {
                "$ref": "#/definitions/nullable_string"
              },
              "barcode": {
                "$ref": "#/definitions/nullable_string"
              }
            }
          }
        }
      },
      "properties": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "source",
            "name",
            "value",
            "value_data_type",
            "string_value",
            "numerical_value",
            "numerical_value_unit",
            "boolean_value",
            "time"
          ],
          "additionalProperties": false,
          "properties": {
            "source": {
              "type": "object",
              "required": [
                "name",
                "type"
              ],
              "additionalProperties": false,
              "properties": {
                "name": {
                  "$ref": "#/definitions/nullable_string"
                },
                "type": {
                  "$ref": "#/definitions/nullable_string"
                }
              }
            },
            "name": {
              "type": "string",
              "description": "This is the property name"
            },
            "value": {
              "type": "string",
              "description": "The original string value of the parameter"
            },
            "value_data_type": {
              "type": "string",
              "enum": [
                "string",
                "number",
                "boolean"
              ],
              "description": "This is the type of the original value"
            },
            "string_value": {
              "$ref": "#/definitions/nullable_string",
              "description": "If string_value has a value, then numerical_value, numerical_value_unit, and boolean_value all have to be null"
            },
            "numerical_value": {
              "$ref": "#/definitions/nullable_number",
              "description": "If numerical_value has a value, then string_value and boolean_value both have to be null"
            },
            "numerical_value_unit": {
              "$ref": "#/definitions/nullable_string"
            },
            "boolean_value": {
              "$ref": "#/definitions/nullable_boolean",
              "description": "If boolean_value has a value, then numerical_value, numerical_value_unit, and string_value all have to be null"
            },
            "time": {
              "type": "object",
              "required": [
                "lookup"
              ],
              "additionalProperties": false,
              "properties": {
                "lookup": {
                  "$ref": "#/definitions/nullable_string"
                }
              }
            }
          }
        }
      },
      "labels": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "source",
            "name",
            "value",
            "time"
          ],
          "additionalProperties": false,
          "properties": {
            "source": {
              "type": "object",
              "required": [
                "name",
                "type"
              ],
              "additionalProperties": false,
              "properties": {
                "name": {
                  "type": "string"
                },
                "type": {
                  "$ref": "#/definitions/nullable_string"
                }
              }
            },
            "name": {
              "type": "string"
            },
            "value": {
              "type": "string"
            },
            "time": {
              "type": "object",
              "required": [
                "lookup"
              ],
              "additionalProperties": false,
              "properties": {
                "lookup": {
                  "$ref": "#/definitions/nullable_string"
                }
              }
            }
          }
        }
      }
    }
  }
}

Related Files

GSF. Not required. Non-Extendable.

If you use this related_files field, you have to use the exact schema defined below. Non-extendable.

"related_files": {
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "pointer"
    ],
    "additionalProperties": false,
    "properties": {
      "name": {
        "$ref": "#/definitions/nullable_string"
      },
      "path": {
        "$ref": "#/definitions/nullable_string"
      },
      "size": {
        "$ref": "#/definitions/value_unit_object"
      },
      "checksum": {
        "type": "object",
        "required": [
          "value",
          "algorithm"
        ],
        "additionalProperties": false,
        "properties": {
          "value": {
            "type": "string"
          },
          "algorithm": {
            "$ref": "#/definitions/nullable_string"
          }
        }
      },
      "pointer": {
        "type": "object",
        "required": [
          "fileKey",
          "version",
          "bucket",
          "type",
          "fileId"
        ],
        "additionalProperties": false,
        "properties": {
          "fileKey": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "bucket": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "fileId": {
            "type": "string"
          }
        }
      }
    }
  }
}

Patterns

datacubes Pattern

GSF. Not required. Extendable.

If you use this field, you have to build your schema on top of the schema below

"datacubes": {
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "name",
      "measures",
      "dimensions"
    ],
    "additionalProperties": false,
    "properties": {
      "name": {
        "$ref": "#/definitions/nullable_string"
      },
      "measures": {
        "type": "array",
        "minItems": 1,
        "maxItems": 1,
        "items": {
          "type": "object",
          "required": [
            "name",
            "unit",
            "value"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "$ref": "#/definitions/nullable_string"
            },
            "unit": {
              "$ref": "#/definitions/nullable_string",
            },
            "value": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/nullable_number"
              }
            }
          }
        }
      },
      "dimensions": {
        "type": "array",
        "minItems": 1,
        "maxItems": 1,
        "items": {
          "type": "object",
          "required": [
            "name",
            "unit",
            "scale"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "$ref": "#/definitions/nullable_string"
            },
            "unit": {
              "$ref": "#/definitions/nullable_string",
            },
            "scale": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/nullable_number"
              }
            }
          }
        }
      }
    }
  }
}

Parameter Pattern

"<your field name>": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "key": {
        "type": "string",
        "description": "this is the property name"
      },
      "value": {
        "type": "string",
        "description": "the original string value of the parameter from the raw file"
      },
      "value_data_type": {
        "type": "string",
        "enum": ["string", "number", "boolean"],
        "description": "this is the true type of the original value"
      },
      "string_value": {
        "type": ["string", "null"],
        "description": "if string_value has a value, then numerical_value, numerical_value_unit and boolean_value have to be null"
      },
      "numerical_value": {
        "type": ["number", "null"],
        "description": "if numerical_value has a value, then string_value and boolean_value have to be null"
      },
      "numerical_value_unit": {
        "type": ["string", "null"]
      },
      "boolean_value": {
        "type": ["string", "null"],
        "description": "if boolean_value has a value, then numerical_value, numerical_value_unit and string_value have to be null"
      }
    }
  }
}

Updated 5 months ago