openapi.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Example UK Livestock Veterinary Medicines book API",
    "version": "0.0.1"
  },
  "paths": {
    "/auth": {
      "post": {
        "summary": "Get Authentiation Token",
        "operationId": "auth",
        "tags": [
          "Authenticate"
        ],
        "requestBody": {
          "required": true,
          "description": "A JSON object containing the auth id and auth key",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful authentication",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthToken"
                }
              }
            },
            "headers": {
              "Set-Cookie": {
                "schema": {
                  "type": "string",
                  "example": "JSESSIONID=abcde12345; Path=/; HttpOnly"
                }
              }
            }
          },
          "400": {
            "description": "Bad request."
          },
          "401": {
            "description": "Authorization information is missing or invalid."
          },
          "404": {
            "description": "An account with the specified ID was not found."
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/administer": {
      "post": {
        "summary": "Submit animinstered course",
        "operationId": "submitCourse",
        "tags": [
          "Submit administered course"
        ],
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "requestBody": {
          "description": "biospiMedicineAdministrationCourseResource JSON object",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/biospiMedicineAdministrationCourseResource"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Null response"
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/acquire": {
      "post": {
        "summary": "Submit record of acquired medicine",
        "operationId": "submitAquisition",
        "tags": [
          "Submit acquired medicine"
        ],
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "requestBody": {
          "description": "biospiMedicineAquisitionResource JSON object",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/biospiMedicineAquisitionResource"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Null response"
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/dispose": {
      "post": {
        "summary": "Submit record of disposed medicine",
        "operationId": "submitDisposal",
        "tags": [
          "Submit disposed medicine"
        ],
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "requestBody": {
          "description": "biospiMedicineDisposalResource JSON object",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/biospiMedicineDisposalResource"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Null response"
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "cookieAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "JSESSIONID"
      }
    },
    "schemas": {
      "AuthRequest": {
        "type": "object",
        "properties": {
          "auth-id": {
            "type": "string",
            "description": "Identifier of the authenticating account"
          },
          "auth-key": {
            "type": "string",
            "description": "Access key for account"
          }
        }
      },
      "AuthToken": {
        "type": "object",
        "properties": {
          "tokenData": {
            "type": "string",
            "description": "data contents of authentication token"
          },
          "expiry": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/exampleErrorResource"
          }
        }
      },
      "exampleErrorResource": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "A unique identifier for this particular occurrence of the problem"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code applicable to this problem, expressed as a string value",
            "format": "int32"
          },
          "code": {
            "type": "string",
            "description": "An application-specific error code, expressed as a string value."
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization."
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized."
          },
          "meta": {
            "type": "object",
            "properties": {}
          }
        },
        "description": "A human-readable error message describing what went wrong."
      },
      "courseDetail": {
        "type": "object",
        "required": [
          "doses"
        ],
        "properties": {
          "doses": {
            "description": "Array of doses adminstered in course",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/biospiMedicineAdministrationDoseResource"
            }
          }
        }
      },
      "courseSummary": {
        "$ref": "#/components/schemas/biospiMedicineAdministrationCourseSummaryResource"
      },
      "icarDateTimeType": {
        "type": "string",
        "description": "udt:DateTimeType | A particular point in the progression of time together with relevant supplementary information.",
        "format": "date-time"
      },
      "icarAnimalIdentifierType": {
        "allOf": [
          {
            "$ref": "#/components/schemas/icarIdentifierType"
          },
          {
            "description": "Identifies an animal using a scheme and ID."
          }
        ]
      },
      "icarLocationIdentifierType": {
        "allOf": [
          {
            "$ref": "#/components/schemas/icarIdentifierType"
          },
          {
            "description": "Location identifier based on a scheme and ID."
          }
        ]
      },
      "icarMetaDataResource": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "description": "Source where data is retrieved from. URI that identified the source system"
          },
          "modified": {
            "$ref": "#/components/schemas/icarDateTimeType"
          },
          "created": {
            "$ref": "#/components/schemas/icarDateTimeType"
          },
          "creator": {
            "type": "string",
            "description": "Person or organisation who created the object"
          },
          "validFrom": {
            "$ref": "#/components/schemas/icarDateTimeType"
          },
          "validTo": {
            "$ref": "#/components/schemas/icarDateTimeType"
          }
        },
        "description": "Generic meta data on this event",
        "required": [
          "source",
          "modified"
        ]
      },
      "icarEventCoreResource": {
        "required": [
          "id",
          "animal",
          "eventDateTime"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier in the source system for this event."
          },
          "animal": {
            "allOf": [
              {
                "$ref": "#/components/schemas/icarAnimalIdentifierType"
              },
              {
                "description": "Unique animal scheme and identifier combination."
              }
            ]
          },
          "eventDateTime": {
            "allOf": [
              {
                "$ref": "#/components/schemas/icarDateTimeType"
              },
              {
                "description": "ISO8601 date and time. MUST contain time zone. UTC recommended."
              }
            ]
          },
          "location": {
            "allOf": [
              {
                "$ref": "#/components/schemas/icarLocationIdentifierType"
              },
              {
                "description": "Unique location scheme and identifier combination."
              }
            ]
          },
          "meta": {
            "allOf": [
              {
                "$ref": "#/components/schemas/icarMetaDataResource"
              },
              {
                "description": "Optional meta-data for the event."
              }
            ]
          }
        }
      },
      "icarIdentifierType": {
        "required": [
          "id",
          "scheme"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "A unique identification for the resource issued under the auspices of the scheme."
          },
          "scheme": {
            "type": "string",
            "description": "The identifier (in reverse domain format) of an official scheme that manages unique identifiers."
          }
        },
        "description": "Identifies a resource."
      },
      "ukLocationSchemeCPH": {
        "allOf": [
          {
            "$ref": "#/components/schemas/icarIdentifierType"
          },
          {
            "description": "CPH Number",
            "properties": {
              "scheme": {
                "type": "string",
                "enum": [
                  "uk.apha.cph"
                ]
              },
              "id": {
                "type": "string",
                "pattern": "\\d{2}/\\d{3}/\\d{4}"
              }
            }
          }
        ]
      },
      "ukLocationSchemeCPHH": {
        "allOf": [
          {
            "$ref": "#/components/schemas/icarIdentifierType"
          },
          {
            "description": "CPHH Number",
            "properties": {
              "scheme": {
                "type": "string",
                "enum": [
                  "uk.apha.cphh"
                ]
              },
              "id": {
                "type": "string",
                "pattern": "\\d{2}/\\d{3}/\\d{4}/\\d{2}"
              }
            }
          }
        ]
      },
      "ukLocationSchemeCTSID": {
        "allOf": [
          {
            "$ref": "#/components/schemas/icarIdentifierType"
          },
          {
            "description": "CTSID",
            "properties": {
              "scheme": {
                "type": "string",
                "enum": [
                  "uk.bcms.ctsid"
                ]
              },
              "id": {
                "type": "string",
                "pattern": "\\d{6}"
              }
            }
          }
        ]
      },
      "ukLocationSchemeCattleHerdMark": {
        "allOf": [
          {
            "$ref": "#/components/schemas/icarIdentifierType"
          },
          {
            "description": "APHA Cattle Herd Mark",
            "properties": {
              "scheme": {
                "type": "string",
                "enum": [
                  "uk.apha.herd.cattle"
                ]
              },
              "id": {
                "type": "string",
                "pattern": "\\d{6}"
              }
            }
          }
        ]
      },
      "ukLocationSchemeFlockMark": {
        "allOf": [
          {
            "$ref": "#/components/schemas/icarIdentifierType"
          },
          {
            "description": "APHA Flock Mark",
            "properties": {
              "scheme": {
                "type": "string",
                "enum": [
                  "uk.apha.herd.cattle"
                ]
              },
              "id": {
                "type": "string",
                "pattern": "\\d{6}"
              }
            }
          }
        ]
      },
      "ukLocationSchemePigHerdMark": {
        "allOf": [
          {
            "$ref": "#/components/schemas/icarIdentifierType"
          },
          {
            "description": "APHA Pig Herd Mark",
            "properties": {
              "scheme": {
                "type": "string",
                "enum": [
                  "uk.apha.herd.pig"
                ]
              },
              "id": {
                "type": "string",
                "pattern": "[a-zA-Z]{1,2}\\d{4}"
              }
            }
          }
        ]
      },
      "biospiUKHoldingIdentifierType": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/ukLocationSchemeCPH"
          },
          {
            "$ref": "#/components/schemas/ukLocationSchemeCPHH"
          },
          {
            "$ref": "#/components/schemas/ukLocationSchemeCTSID"
          },
          {
            "$ref": "#/components/schemas/ukLocationSchemeCattleHerdMark"
          },
          {
            "$ref": "#/components/schemas/ukLocationSchemeFlockMark"
          },
          {
            "$ref": "#/components/schemas/ukLocationSchemePigHerdMark"
          }
        ]
      },
      "biospiMedicineQuantityType": {
        "required": [
          "amount",
          "unit"
        ],
        "type": "object",
        "properties": {
          "amount": {
            "type": "number"
          },
          "unit": {
            "type": "string",
            "enum": [
              "ml",
              "l",
              "g",
              "mg",
              "tube",
              "unit"
            ]
          }
        }
      },
      "biospiMedicineDisposalResource": {
        "required": [
          "id",
          "medicine",
          "eventDateTime",
          "location",
          "method",
          "quantity"
        ],
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/icarEventCoreResource"
          },
          {
            "properties": {
              "location": {
                "$ref": "#/components/schemas/biospiUKHoldingIdentifierType"
              },
              "medicine": {
                "$ref": "#/components/schemas/biospiMedicineResource"
              },
              "quantity": {
                "$ref": "#/components/schemas/biospiMedicineQuantityType"
              },
              "method": {
                "type": "string"
              }
            }
          }
        ]
      },
      "biospiMedicineAquisitionResource": {
        "required": [
          "id",
          "medicine",
          "eventDateTime",
          "batch",
          "expiry",
          "location",
          "supplier",
          "quantity"
        ],
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/icarEventCoreResource"
          },
          {
            "properties": {
              "location": {
                "$ref": "#/components/schemas/biospiUKHoldingIdentifierType"
              },
              "medicine": {
                "$ref": "#/components/schemas/biospiMedicineResource"
              },
              "quantity": {
                "$ref": "#/components/schemas/biospiMedicineQuantityType"
              },
              "batch": {
                "type": "string",
                "description": "Batch number of acquired medicine"
              },
              "expiry": {
                "allOf": [
                  {
                    "description": "Expiry date of acquired medicine"
                  },
                  {
                    "$ref": "#/components/schemas/icarDateTimeType"
                  }
                ]
              },
              "supplier": {
                "description": "Name and address of medicine supplier",
                "type": "string"
              }
            }
          }
        ]
      },
      "biospiMedicineAdministrationCourseSummaryResource": {
        "description": "summary course information where individual dose data is unavailable",
        "type": "object",
        "required": [
          "totalQuantity",
          "startDate",
          "endDate",
          "batches",
          "operators",
          "withdrawalDates"
        ],
        "properties": {
          "totalQuantity": {
            "allOf": [
              {
                "description": "Total quantity of medicine administered in course"
              },
              {
                "$ref": "#/components/schemas/biospiMedicineQuantityType"
              }
            ]
          },
          "startDate": {
            "allOf": [
              {
                "description": "Date first treatment of course administered"
              },
              {
                "$ref": "#/components/schemas/icarDateTimeType"
              }
            ]
          },
          "endDate": {
            "allOf": [
              {
                "description": "Date last treatment of course administered"
              },
              {
                "$ref": "#/components/schemas/icarDateTimeType"
              }
            ]
          },
          "withdrawalDates": {
            "type": "array",
            "description": "Withdrawal dates applicable to this administered dose",
            "items": {
              "type": "object",
              "properties": {
                "withdrawalType": {
                  "type": "string",
                  "description": "Type of withdrawal date (meat/milk/egg/honey)",
                  "enum": [
                    "meat",
                    "milk",
                    "egg",
                    "honey"
                  ]
                },
                "withdrawalDate": {
                  "allOf": [
                    {
                      "description": "Withdrawal date"
                    },
                    {
                      "$ref": "#/components/schemas/icarDateTimeType"
                    }
                  ]
                }
              }
            }
          },
          "batches": {
            "type": "array",
            "description": "Batch number(s) of administered medicines",
            "items": {
              "type": "string"
            }
          },
          "expiry": {
            "description": "Expiry date(s) of medicine used in dose",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/icarDateTimeType"
            }
          },
          "operators": {
            "type": "array",
            "description": "Person(s) who administered medicines",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "biospiMedicineAdministrationDoseResource": {
        "type": "object",
        "description": "Single administration of a medicine to an animal",
        "required": [
          "id",
          "eventDateTime",
          "quantity",
          "operator",
          "batchesAndExpiryDates",
          "withdrawalDates"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/icarEventCoreResource"
          },
          {
            "properties": {
              "location": {
                "$ref": "#/components/schemas/biospiUKHoldingIdentifierType"
              },
              "quantity": {
                "$ref": "#/components/schemas/biospiMedicineQuantityType"
              },
              "operator": {
                "type": "string",
                "description": "Person who administered medicines"
              },
              "batchesAndExpiryDates": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "batch": {
                      "type": "string",
                      "description": "Batch number of administered medicines"
                    },
                    "expiry": {
                      "allOf": [
                        {
                          "description": "Expiry date of acquired medicine"
                        },
                        {
                          "$ref": "#/components/schemas/icarDateTimeType"
                        }
                      ]
                    }
                  }
                }
              },
              "withdrawalDates": {
                "type": "array",
                "description": "Withdrawal dates applicable to this administered dose",
                "items": {
                  "type": "object",
                  "properties": {
                    "withdrawalType": {
                      "type": "string",
                      "description": "Type of withdrawal date (meat/milk/egg/honey)",
                      "enum": [
                        "meat",
                        "milk",
                        "egg",
                        "honey"
                      ]
                    },
                    "withdrawalDate": {
                      "allOf": [
                        {
                          "description": "Withdrawal date"
                        },
                        {
                          "$ref": "#/components/schemas/icarDateTimeType"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "biospiMedicineAdministrationCourseResource": {
        "required": [
          "id",
          "medicine",
          "eventDateTime",
          "animal",
          "location",
          "treatment"
        ],
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/icarEventCoreResource"
          },
          {
            "properties": {
              "location": {
                "$ref": "#/components/schemas/biospiUKHoldingIdentifierType"
              },
              "medicine": {
                "$ref": "#/components/schemas/biospiMedicineResource"
              },
              "reasonForTreatment": {
                "type": "string",
                "description": "Reason for administration of course of medicine"
              },
              "treatment": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/courseDetail"
                  },
                  {
                    "$ref": "#/components/schemas/courseSummary"
                  }
                ]
              }
            }
          }
        ]
      },
      "biospiMedicineResource": {
        "required": [
          "identifier"
        ],
        "type": "object",
        "description": "Standardised representation of licensed veterinary medicine",
        "properties": {
          "identifier": {
            "allOf": [
              {
                "$ref": "#/components/schemas/biospiMedicineIdentifierType"
              },
              {
                "description": "Unique medicine identification scheme and identifier combination"
              }
            ]
          },
          "name": {
            "allOf": [
              {
                "type": "string"
              },
              {
                "description": "Official medicine name."
              }
            ]
          },
          "GTIN": {
            "allOf": [
              {
                "$ref": "#/components/schemas/biospiGTINType"
              },
              {
                "description": "GTIN in GTIN-12 or GTIN-13 format"
              }
            ]
          },
          "SKU": {
            "type": "string",
            "description": "Stock Keeping Unit indentifier from source system"
          }
        }
      },
      "biospiMedicineIdentifierType": {
        "allOf": [
          {
            "$ref": "#/components/schemas/icarIdentifierType"
          },
          {
            "description": "Identifies a medicine using a VMD scheme and ID (VmNo).",
            "properties": {
              "scheme": {
                "type": "string",
                "enum": [
                  "uk.gov.vmd"
                ]
              }
            }
          }
        ]
      },
      "biospiGTINType": {
        "type": "object",
        "description": "Global Trade Identification Number in 12-digit or 13-digit format",
        "properties": {
          "gtin-12": {
            "type": "string",
            "maxLength": 12,
            "minLength": 12,
            "pattern": "\\d{12}"
          },
          "gtin-13": {
            "type": "string",
            "maxLength": 13,
            "minLength": 13,
            "pattern": "\\d{13}"
          }
        }
      }
    }
  }
}