How to export schema.json from a programmatic IDS

The ts-ids export-schema command takes a Python module name plus an optional programmatically-defined IDS and converts it to jsonschema format. To execute it, run the following from the parent of the my_ids_package folder.

PYTHONPATH=$PWD \
    ts-ids export-schema \
        -i my_ids_package.my_ids_module.MyIdsSchema \
        -o path/to/output/schema.json

The repo root, which contains my_ids_package, must be added to the PYTHONPATH in order to let export-schema import my_ids_package.my_ids_module. For further documentation, run

ts-ids export-schema --help

Example

Suppose you have pip install-ed ts-ids-core as a dependency in your Python repo whose folder structure is

my-ids-repo
└── my_ids_repo
    ├── __init__.py
    └── data_model.py

and the contents of data_model.py is

from typing import ClassVar, List, Literal

from ts_ids_core.annotations import Required
from ts_ids_core.base.ids_element import SchemaExtraMetadataType
from ts_ids_core.base.ids_field import IdsField
from ts_ids_core.schema import DataCube, IdsSchema, Sample, System

class MyIdsSchema(IdsSchema):
    """An example IDS"""

    schema_extra_metadata: ClassVar[SchemaExtraMetadataType] = {
        "$id": "https://ids.tetrascience.com/common/my-instrument/v0.1.0/schema.json",
        "$schema": "http://json-schema.org/draft-07/schema#",
    }

    ids_type: Required[Literal["my-instrument"]] = IdsField(
        default="my-instrument", alias="@idsType"
    )
    ids_version: Required[Literal["v0.1.0"]] = IdsField(
        default="v0.1.0", alias="@idsVersion"
    )
    ids_namespace: Required[Literal["common"]] = IdsField(
        default="common", alias="@idsNamespace"
    )

    samples: List[Sample]
    systems: List[System]
    datacubes: List[DataCube]

To export MyIdsSchema to jsonschema format and print it in the command line, execute the following from the my-ids-repo directory

PYTHONPATH=$PWD \
    ts-ids export-schema -i my_ids_repo.data_model.MyIdsSchema

This will print the following the command line:

Expand to show output

{
  "$id": "https://ids.tetrascience.com/common/my-instrument/v0.1.0/schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "description": "An example IDS",
  "properties": {
    "@idsType": {
      "const": "my-instrument",
      "type": "string"
    },
    "@idsVersion": {
      "const": "v0.1.0",
      "type": "string"
    },
    "@idsNamespace": {
      "const": "common",
      "type": "string"
    },
    "samples": {
      "items": {
        "$ref": "#/definitions/Sample"
      },
      "type": "array"
    },
    "systems": {
      "items": {
        "$ref": "#/definitions/System"
      },
      "type": "array"
    },
    "datacubes": {
      "items": {
        "$ref": "#/definitions/DataCube"
      },
      "type": "array"
    }
  },
  "required": [
    "@idsType",
    "@idsVersion",
    "@idsNamespace"
  ],
  "type": "object",
  "definitions": {
    "Batch": {
      "additionalProperties": false,
      "description": "A Batch is the result of a single manufacturing run for a drug product that is made as specified groups or amounts,  within a specific time frame from the same raw materials that is intended to have uniform character and quality, within specified limits.",
      "properties": {
        "id": {
          "description": "Unique identifier assigned to a batch.",
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "description": "Batch name",
          "type": [
            "string",
            "null"
          ]
        },
        "barcode": {
          "description": "Barcode assigned to a batch",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "Compound": {
      "additionalProperties": false,
      "description": "A Compound is a specific chemical or biochemical structure or substance that is being investigated. A Compound may be any drug substance, drug product intermediate, or drug product across small molecules, and cell and gene therapy (CGT).",
      "properties": {
        "id": {
          "description": "Unique identifier assigned to a compound.",
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "description": "Compound name.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "DataCube": {
      "additionalProperties": false,
      "description": "TetraScience designed model for multi-dimensional data.",
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "measures": {
          "items": {
            "$ref": "#/definitions/Measure"
          },
          "maxItems": 1,
          "minItems": 1,
          "type": "array"
        },
        "dimensions": {
          "items": {
            "$ref": "#/definitions/Dimension"
          },
          "maxItems": 2,
          "minItems": 2,
          "type": "array"
        }
      },
      "required": [
        "name",
        "measures",
        "dimensions"
      ],
      "type": "object"
    },
    "Dimension": {
      "additionalProperties": false,
      "description": "A dimension of a DataCube",
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "unit": {
          "type": [
            "string",
            "null"
          ]
        },
        "scale": {
          "items": {
            "type": [
              "number",
              "null"
            ]
          },
          "type": "array"
        }
      },
      "required": [
        "name",
        "unit",
        "scale"
      ],
      "type": "object"
    },
    "Holder": {
      "additionalProperties": false,
      "description": "A sample container such as a microplate or a vial.",
      "properties": {
        "name": {
          "description": "Holder name.",
          "type": [
            "string",
            "null"
          ]
        },
        "type": {
          "description": "Holder type.",
          "type": [
            "string",
            "null"
          ]
        },
        "barcode": {
          "description": "Barcode assigned to a holder.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "Label": {
      "additionalProperties": false,
      "description": "A Label associated with a sample, along with metadata about the label including\nthe source of the label and times associated with the label such as when it was\ncreated or looked up.",
      "properties": {
        "source": {
          "$ref": "#/definitions/Source",
          "description": "Sample label data source information."
        },
        "name": {
          "description": "Sample label name.",
          "type": "string"
        },
        "value": {
          "description": "Sample label value.",
          "type": "string"
        },
        "time": {
          "$ref": "#/definitions/SampleTime",
          "description": "Time associated with the sample label."
        }
      },
      "required": [
        "source",
        "name",
        "value",
        "time"
      ],
      "type": "object"
    },
    "Location": {
      "additionalProperties": false,
      "description": "The Location of the sample within the holder, such as the location of a well in a microplate.",
      "properties": {
        "position": {
          "description": "Raw position string.",
          "type": [
            "string",
            "null"
          ]
        },
        "row": {
          "description": "Row index of sample location in a plate or holder.",
          "type": [
            "number",
            "null"
          ]
        },
        "column": {
          "description": "Column index of sample location in a plate or holder.",
          "type": [
            "number",
            "null"
          ]
        },
        "index": {
          "description": "Index of sample location flattened to a single dimension.",
          "type": [
            "number",
            "null"
          ]
        },
        "holder": {
          "$ref": "#/definitions/Holder",
          "description": "Sample holder information"
        }
      },
      "type": "object"
    },
    "Measure": {
      "additionalProperties": false,
      "description": "A measure of a DataCube",
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "unit": {
          "type": [
            "string",
            "null"
          ]
        },
        "value": {
          "items": {
            "items": {
              "type": [
                "number",
                "null"
              ]
            },
            "type": "array"
          },
          "type": "array"
        }
      },
      "required": [
        "name",
        "unit",
        "value"
      ],
      "type": "object"
    },
    "Property": {
      "additionalProperties": false,
      "description": "A property has a name and a value of any type, with metadata about the\nproperty including the source of the property and times associated with it\nsuch as when the property was created or looked up.",
      "properties": {
        "source": {
          "$ref": "#/definitions/Source",
          "description": "Sample property data source information."
        },
        "name": {
          "description": "Sample Property name.",
          "type": "string"
        },
        "value": {
          "description": "The original string value of the property.",
          "type": "string"
        },
        "value_data_type": {
          "$ref": "#/definitions/ValueDataType",
          "description": "This is the type of the original value."
        },
        "string_value": {
          "description": "If string_value has a value, then numerical_value, numerical_value_unit, and boolean_value all have to be null.",
          "type": [
            "string",
            "null"
          ]
        },
        "numerical_value": {
          "description": "If numerical_value has a value, then string_value and boolean_value both have to be null.",
          "type": [
            "number",
            "null"
          ]
        },
        "numerical_value_unit": {
          "description": "Unit for the numerical value.",
          "type": [
            "string",
            "null"
          ]
        },
        "boolean_value": {
          "description": "If boolean_value has a value, then numerical_value, numerical_value_unit, and string_value all have to be null.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "time": {
          "$ref": "#/definitions/SampleTime",
          "description": "Time associated with the sample property."
        }
      },
      "required": [
        "source",
        "name",
        "value",
        "value_data_type",
        "string_value",
        "numerical_value",
        "numerical_value_unit",
        "boolean_value",
        "time"
      ],
      "type": "object"
    },
    "RawSampleTime": {
      "additionalProperties": false,
      "description": "The base model for time associated with a specific sample.",
      "properties": {
        "start": {
          "description": "Process/experiment/task start time.",
          "type": [
            "string",
            "null"
          ]
        },
        "created": {
          "description": "Data created time.",
          "type": [
            "string",
            "null"
          ]
        },
        "stop": {
          "description": "Process/experiment/task stop/finish time.",
          "type": [
            "string",
            "null"
          ]
        },
        "duration": {
          "description": "Process/experiment/task duration.",
          "type": [
            "string",
            "null"
          ]
        },
        "last_updated": {
          "description": "Data last updated time of a file/method.",
          "type": [
            "string",
            "null"
          ]
        },
        "acquired": {
          "description": "Data acquired/exported/captured time.",
          "type": [
            "string",
            "null"
          ]
        },
        "modified": {
          "description": "Data last modified/edited time.",
          "type": [
            "string",
            "null"
          ]
        },
        "lookup": {
          "description": "Raw sample data lookup time.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "lookup"
      ],
      "type": "object"
    },
    "Sample": {
      "additionalProperties": false,
      "description": "A Sample is a discrete entity being observed in an experiment. For example, Samples may be characterized for product quality and stability, or be measured for research purposes.",
      "properties": {
        "id": {
          "description": "Unique identifier assigned to a sample.",
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "description": "Sample name.",
          "type": [
            "string",
            "null"
          ]
        },
        "barcode": {
          "description": "Barcode assigned to a sample.",
          "type": [
            "string",
            "null"
          ]
        },
        "batch": {
          "$ref": "#/definitions/Batch"
        },
        "set": {
          "$ref": "#/definitions/Set",
          "description": "Sample set."
        },
        "location": {
          "$ref": "#/definitions/Location",
          "description": "Sample location information."
        },
        "compound": {
          "$ref": "#/definitions/Compound",
          "description": "Sample compound information."
        },
        "properties": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Property"
          },
          "description": "Sample properties."
        },
        "labels": {
          "description": "Sample labels.",
          "items": {
            "$ref": "#/definitions/Label"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "SampleTime": {
      "additionalProperties": false,
      "description": "A model for experiment sample datetime values converted to a standard ISO format\nand their respective raw datetime values in the primary data.",
      "properties": {
        "start": {
          "description": "Process/experiment/task start time.",
          "type": [
            "string",
            "null"
          ]
        },
        "created": {
          "description": "Data created time.",
          "type": [
            "string",
            "null"
          ]
        },
        "stop": {
          "description": "Process/experiment/task stop/finish time.",
          "type": [
            "string",
            "null"
          ]
        },
        "duration": {
          "description": "Process/experiment/task duration.",
          "type": [
            "string",
            "null"
          ]
        },
        "last_updated": {
          "description": "Data last updated time of a file/method.",
          "type": [
            "string",
            "null"
          ]
        },
        "acquired": {
          "description": "Data acquired/exported/captured time.",
          "type": [
            "string",
            "null"
          ]
        },
        "modified": {
          "description": "Data last modified/edited time.",
          "type": [
            "string",
            "null"
          ]
        },
        "lookup": {
          "description": "Raw sample data lookup time.",
          "type": [
            "string",
            "null"
          ]
        },
        "raw": {
          "$ref": "#/definitions/RawSampleTime",
          "description": "Raw sample time values from primary data."
        }
      },
      "required": [
        "lookup"
      ],
      "type": "object"
    },
    "Set": {
      "additionalProperties": false,
      "description": "A group of Samples.",
      "properties": {
        "id": {
          "description": "Unique identifier assigned to a set.",
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "description": "Set name.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "Source": {
      "additionalProperties": false,
      "description": "The Source of information, such as a data file or a sample database.",
      "properties": {
        "name": {
          "description": "Source name.",
          "type": [
            "string",
            "null"
          ]
        },
        "type": {
          "description": "Source type.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "name",
        "type"
      ],
      "type": "object"
    },
    "System": {
      "additionalProperties": false,
      "description": "Metadata regarding the equipment, software, and firmware used in a run of an\ninstrument or experiment.",
      "properties": {
        "vendor": {
          "description": "The instrument vendor or manufacturer, like 'PerkinElmer' or 'Agilent'.",
          "type": [
            "string",
            "null"
          ]
        },
        "model": {
          "description": "A specific model instrument type from a vendor.",
          "type": [
            "string",
            "null"
          ]
        },
        "type": {
          "description": "Indicates the type of instrument that's generating data.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "vendor",
        "model",
        "type"
      ],
      "type": "object"
    },
    "ValueDataType": {
      "description": "Allowed data type values.",
      "enum": [
        "string",
        "number",
        "boolean"
      ],
      "type": "string"
    }
  }
}