openapi.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Flux API",
    "version": "1.0.0",
    "description": "Flux - Simple, quick and easy organisation management",
    "contact": {
      "email": "hello@mashsoftware.com",
      "name": "Mash Software",
      "url": "https://www.mashsoftware.com/"
    },
    "license": {
      "name": "MIT License",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "externalDocs": {
    "url": "https://github.com/MashSoftware/flux-api",
    "description": "GitHub"
  },
  "servers": [
    {
      "url": "http://localhost:{port}/{version}",
      "description": "Local development",
      "variables": {
        "port": {
          "default": "3000"
        },
        "version": {
          "default": "v1"
        }
      }
    },
    {
      "url": "https://mash-flux-api.herokuapp.com/{version}",
      "description": "Production",
      "variables": {
        "version": {
          "default": "v1"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Organisation",
      "description": "Operations on the Organisation resource"
    },
    {
      "name": "Programme",
      "description": "Operations on the Programme resource"
    },
    {
      "name": "Project",
      "description": "Operations on the Project resource"
    },
    {
      "name": "Team",
      "description": "Operations on the Team resource"
    },
    {
      "name": "Grade",
      "description": "Operations on the Grade resource"
    },
    {
      "name": "Practice",
      "description": "Operations on the Practice resource"
    },
    {
      "name": "Role",
      "description": "Operations on the Role resource"
    },
    {
      "name": "Person",
      "description": "Operations on the Person resource"
    }
  ],
  "paths": {
    "/organisations": {
      "get": {
        "description": "Get a list of organisations",
        "operationId": "get_organisations",
        "tags": ["Organisation"],
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "description": "Name to filter by",
            "required": false,
            "example": "Mash Software",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An array of organisations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/OrganisationItem"
                  }
                }
              }
            }
          },
          "204": {
            "description": "No organisations found"
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "description": "Create a new organisation",
        "operationId": "create_organisation",
        "tags": ["Organisation"],
        "requestBody": {
          "description": "New organisation data to create",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrganisationRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Newly created organisation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organisation"
                }
              }
            },
            "headers": {
              "Location": {
                "description": "URL of the newly created organisation",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/organisations/{organisation_id}": {
      "get": {
        "description": "Get a specific organisation",
        "operationId": "get_organisation",
        "tags": ["Organisation"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation to retrieve",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Organisation response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organisation"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "description": "Update a specific organisation",
        "operationId": "update_organisation",
        "tags": ["Organisation"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation to update",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "Organisation data to update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrganisationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Organisation response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organisation"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "description": "Delete a specific organisation",
        "operationId": "delete_organisation",
        "tags": ["Organisation"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation to delete",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Organisation deleted"
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/organisations/{organisation_id}/programmes": {
      "get": {
        "description": "Get a list of programmes in an organisation",
        "operationId": "list_programmes",
        "tags": ["Programme"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "name",
            "in": "query",
            "description": "Name to filter by",
            "required": false,
            "example": "Digital Transformation",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An array of programmes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ProgrammeItem"
                  }
                }
              }
            }
          },
          "204": {
            "description": "No programmes found"
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "description": "Create a new programme in an organisation",
        "operationId": "create_programme",
        "tags": ["Programme"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "New programme data to create",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProgrammeRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Newly created programme",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Programme"
                }
              }
            },
            "headers": {
              "Location": {
                "description": "URL of the newly created programme",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/organisations/{organisation_id}/programmes/{programme_id}": {
      "get": {
        "description": "Get a specific programme in an organisation",
        "operationId": "get_programme",
        "tags": ["Programme"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "programme_id",
            "in": "path",
            "description": "ID of the programme to retrieve",
            "required": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Programme response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Programme"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "description": "Update a specific programme in an organisation",
        "operationId": "update_programme",
        "tags": ["Programme"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "programme_id",
            "in": "path",
            "description": "ID of the programme to update",
            "required": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "Programme data to update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProgrammeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Programme response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Programme"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "description": "Delete a specific programme in an organisation",
        "operationId": "delete_programme",
        "tags": ["Programme"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "programme_id",
            "in": "path",
            "description": "ID of the programme to delete",
            "required": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "programme deleted"
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/organisations/{organisation_id}/grades": {
      "get": {
        "description": "Get a list of grades in an organisation",
        "operationId": "list_grades",
        "tags": ["Grade"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "name",
            "in": "query",
            "description": "Name to filter by",
            "required": false,
            "example": "SEO",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An array of grades",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/GradeItem"
                  }
                }
              }
            }
          },
          "204": {
            "description": "No grades found"
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "description": "Create a new grade in an organisation",
        "operationId": "create_grade",
        "tags": ["Grade"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "New grade data to create",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GradeRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Newly created grade",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Grade"
                }
              }
            },
            "headers": {
              "Location": {
                "description": "URL of the newly created grade",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/organisations/{organisation_id}/grades/{grade_id}": {
      "get": {
        "description": "Get a specific grade in an organisation",
        "operationId": "get_grade",
        "tags": ["Grade"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "grade_id",
            "in": "path",
            "description": "ID of the grade to retrieve",
            "required": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Grade response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Grade"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "description": "Update a specific grade in an organisation",
        "operationId": "update_grade",
        "tags": ["Grade"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "grade_id",
            "in": "path",
            "description": "ID of the grade to update",
            "required": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "Grade data to update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GradeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Grade response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Grade"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "description": "Delete a specific grade in an organisation",
        "operationId": "delete_grade",
        "tags": ["Grade"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "grade_id",
            "in": "path",
            "description": "ID of the grade to delete",
            "required": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Grade deleted"
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/organisations/{organisation_id}/practices": {
      "get": {
        "description": "Get a list of practices in an organisation",
        "operationId": "list_practices",
        "tags": ["Practice"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "name",
            "in": "query",
            "description": "Name to filter by",
            "required": false,
            "example": "Software Development",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An array of practices",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PracticeItem"
                  }
                }
              }
            }
          },
          "204": {
            "description": "No practices found"
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "description": "Create a new practice in an organisation",
        "operationId": "create_practice",
        "tags": ["Practice"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "New practice data to create",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PracticeRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Newly created practice",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Practice"
                }
              }
            },
            "headers": {
              "Location": {
                "description": "URL of the newly created practice",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/organisations/{organisation_id}/practices/{practice_id}": {
      "get": {
        "description": "Get a specific practice in an organisation",
        "operationId": "get_practice",
        "tags": ["Practice"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "practice_id",
            "in": "path",
            "description": "ID of the practice to retrieve",
            "required": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Practice response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Practice"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "description": "Update a specific practice in an organisation",
        "operationId": "update_practice",
        "tags": ["Practice"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "practice_id",
            "in": "path",
            "description": "ID of the practice to update",
            "required": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "Practice data to update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PracticeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Practice response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Practice"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "description": "Delete a specific practice in an organisation",
        "operationId": "delete_practice",
        "tags": ["Practice"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "practice_id",
            "in": "path",
            "description": "ID of the practice to delete",
            "required": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Practice deleted"
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/organisations/{organisation_id}/roles": {
      "get": {
        "description": "Get a list of roles in an organisation",
        "operationId": "list_roles",
        "tags": ["Role"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "title",
            "in": "query",
            "description": "Title to filter by",
            "required": false,
            "example": "Software Developer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An array of roles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/RoleItem"
                  }
                }
              }
            }
          },
          "204": {
            "description": "No roles found"
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "description": "Create a new role in an organisation",
        "operationId": "create_role",
        "tags": ["Role"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "New role data to create",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoleRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Newly created role",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Role"
                }
              }
            },
            "headers": {
              "Location": {
                "description": "URL of the newly created role",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/organisations/{organisation_id}/roles/{role_id}": {
      "get": {
        "description": "Get a specific role in an organisation",
        "operationId": "get_role",
        "tags": ["Role"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "role_id",
            "in": "path",
            "description": "ID of the role to retrieve",
            "required": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Role response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Role"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "description": "Update a specific role in an organisation",
        "operationId": "update_role",
        "tags": ["Role"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "role_id",
            "in": "path",
            "description": "ID of the role to update",
            "required": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "Role data to update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoleRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Role response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Role"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "description": "Delete a specific role in an organisation",
        "operationId": "delete_role",
        "tags": ["Role"],
        "parameters": [
          {
            "name": "organisation_id",
            "in": "path",
            "description": "ID of the organisation",
            "required": true,
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "role_id",
            "in": "path",
            "description": "ID of the role to delete",
            "required": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Role deleted"
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "OrganisationRequest": {
        "type": "object",
        "required": ["name", "domain"],
        "properties": {
          "name": {
            "type": "string",
            "example": "Mash Software"
          },
          "domain": {
            "type": "string",
            "format": "hostname",
            "example": "mashsoftware.com"
          }
        }
      },
      "Organisation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9"
          },
          "name": {
            "type": "string",
            "example": "Mash Software"
          },
          "domain": {
            "type": "string",
            "format": "hostname",
            "example": "mashsoftware.com"
          },
          "programmes": {
            "type": "integer",
            "format": "int32",
            "example": 2
          },
          "grades": {
            "type": "integer",
            "format": "int32",
            "example": 7
          },
          "practices": {
            "type": "integer",
            "format": "int32",
            "example": 5
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-04-20T22:04:51.583801+01:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2021-04-20T22:16:57.492478+01:00"
          }
        }
      },
      "OrganisationItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "d9ecd6ee-3ab8-473b-9585-bc653024bed9"
          },
          "name": {
            "type": "string",
            "example": "Mash Software"
          },
          "domain": {
            "type": "string",
            "format": "hostname",
            "example": "mashsoftware.com"
          }
        }
      },
      "ProgrammeRequest": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": {
            "type": "string",
            "example": "Digital Transformation"
          },
          "manager_id": {
            "type": ["string", "null"],
            "format": "uuid",
            "nullable": true,
            "example": "2d23f327-f308-4003-a9be-1ac7b9a8c01c",
            "description": "ID of a Person"
          }
        }
      },
      "Programme": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f"
          },
          "name": {
            "type": "string",
            "example": "Digital Transformation"
          },
          "manager": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PersonItem"
              },
              {
                "nullable": true
              }
            ]
          },
          "organisation": {
            "$ref": "#/components/schemas/OrganisationItem"
          },
          "projects": {
            "type": "integer",
            "format": "int32",
            "example": 2
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-04-20T22:04:51.583801+01:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2021-04-20T22:16:57.492478+01:00"
          }
        }
      },
      "ProgrammeItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f"
          },
          "name": {
            "type": "string",
            "example": "Digital Transformation"
          },
          "manager": {
            "$ref": "#/components/schemas/PersonItem"
          }
        }
      },
      "ProjectRequest": {
        "type": "object",
        "required": ["name", "programme_id", "status"],
        "properties": {
          "name": {
            "type": "string",
            "example": "Skunkworks"
          },
          "manager_id": {
            "type": ["string", "null"],
            "format": "uuid",
            "nullable": true,
            "example": "2d23f327-f308-4003-a9be-1ac7b9a8c01c",
            "description": "ID of a Person"
          },
          "programme_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "example": "f6d1cd4f-9756-499b-b0cc-603aa4935c6f"
          },
          "status": {
            "type": "string",
            "enum": ["active", "paused", "closed"]
          }
        }
      },
      "Project": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "a9b72117-5e6e-441f-bdb1-bb1c89ebfc21"
          },
          "name": {
            "type": "string",
            "example": "Skunkworks"
          },
          "manager": {
            "$ref": "#/components/schemas/PersonItem"
          },
          "teams": {
            "type": "integer",
            "format": "int32",
            "example": 2
          },
          "programme": {
            "$ref": "#/components/schemas/ProgrammeItem"
          },
          "status": {
            "type": "string",
            "enum": ["active", "paused", "closed"]
          },
          "organisation": {
            "$ref": "#/components/schemas/OrganisationItem"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-04-20T22:04:51.583801+01:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2021-04-20T22:16:57.492478+01:00"
          }
        }
      },
      "ProjectItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "a9b72117-5e6e-441f-bdb1-bb1c89ebfc21"
          },
          "name": {
            "type": "string",
            "example": "Skunkworks"
          },
          "manager": {
            "$ref": "#/components/schemas/PersonItem"
          },
          "programme": {
            "$ref": "#/components/schemas/ProgrammeItem"
          },
          "status": {
            "type": "string",
            "enum": ["active", "paused", "closed"]
          }
        }
      },
      "TeamRequest": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": {
            "type": "string",
            "example": "Awesome Sauce"
          },
          "project_id": {
            "type": "string",
            "format": "uuid",
            "example": "a9b72117-5e6e-441f-bdb1-bb1c89ebfc21"
          }
        }
      },
      "Team": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "ba62ebd5-72e0-4d8a-8b5a-8cce1233edbb"
          },
          "name": {
            "type": "string",
            "example": "Awesome Sauce"
          },
          "people": {
            "type": "integer",
            "format": "int32",
            "example": 7
          },
          "project": {
            "$ref": "#/components/schemas/ProjectItem"
          },
          "organisation": {
            "$ref": "#/components/schemas/OrganisationItem"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-04-20T22:04:51.583801+01:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2021-04-20T22:16:57.492478+01:00"
          }
        }
      },
      "TeamItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "ba62ebd5-72e0-4d8a-8b5a-8cce1233edbb"
          },
          "name": {
            "type": "string",
            "example": "Awesome Sauce"
          }
        }
      },
      "PersonRequest": {
        "type": "object",
        "required": [
          "name",
          "email_address",
          "location_id",
          "employment",
          "full_time_equivalent",
          "role_id"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Mickey Mouse"
          },
          "email_address": {
            "type": "string",
            "format": "email",
            "example": "mickey.mouse@example.com"
          },
          "role_id": {
            "type": "string",
            "format": "uuid",
            "example": "cbc0568d-86d2-4a59-82b2-affb05988628"
          },
          "employment": {
            "type": "string",
            "enum": ["permanent", "contract"]
          },
          "full_time_equivalent": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 1,
            "example": 0.8
          },
          "location_id": {
            "type": "string",
            "format": "uuid",
            "example": "cbc0568d-86d2-4a59-82b2-affb05988628"
          }
        }
      },
      "Person": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "2d23f327-f308-4003-a9be-1ac7b9a8c01c"
          },
          "name": {
            "type": "string",
            "example": "Mickey Mouse"
          },
          "email_address": {
            "type": "string",
            "format": "email",
            "example": "mickey.mouse@example.com"
          },
          "role": {
            "$ref": "#/components/schemas/RoleItem"
          },
          "organisation": {
            "$ref": "#/components/schemas/OrganisationItem"
          },
          "employment": {
            "type": "string",
            "enum": ["permanent", "contract"]
          },
          "full_time_equivalent": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 1,
            "example": 0.8
          },
          "location": {
            "$ref": "#/components/schemas/LocationItem"
          },
          "teams": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/TeamItem"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-04-20T22:04:51.583801+01:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2021-04-20T22:16:57.492478+01:00"
          }
        }
      },
      "PersonItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "2d23f327-f308-4003-a9be-1ac7b9a8c01c"
          },
          "name": {
            "type": "string",
            "example": "Mickey Mouse"
          },
          "role": {
            "$ref": "#/components/schemas/RoleItem"
          },
          "location": {
            "$ref": "#/components/schemas/LocationItem"
          }
        }
      },
      "RoleRequest": {
        "type": "object",
        "required": ["title", "grade_id"],
        "properties": {
          "title": {
            "type": "string",
            "example": "Software Developer"
          },
          "grade_id": {
            "type": "string",
            "format": "uuid",
            "example": "fac79045-d2f9-489f-acdb-510acbd239c3"
          },
          "practice_id": {
            "type": ["string", "null"],
            "format": "uuid",
            "nullable": true,
            "example": "2d23f327-f308-4003-a9be-1ac7b9a8c01c"
          }
        }
      },
      "Role": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "2d23f327-f308-4003-a9be-1ac7b9a8c01c"
          },
          "title": {
            "type": "string",
            "example": "Software Developer"
          },
          "grade": {
            "$ref": "#/components/schemas/GradeItem"
          },
          "practice": {
            "$ref": "#/components/schemas/PracticeItem"
          },
          "organisation": {
            "$ref": "#/components/schemas/OrganisationItem"
          },
          "people": {
            "type": "integer",
            "format": "int32",
            "example": 7
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-04-20T22:04:51.583801+01:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2021-04-20T22:16:57.492478+01:00"
          }
        }
      },
      "RoleItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "2d23f327-f308-4003-a9be-1ac7b9a8c01c"
          },
          "title": {
            "type": "string",
            "example": "Software Developer"
          },
          "grade": {
            "$ref": "#/components/schemas/GradeItem"
          },
          "practice": {
            "$ref": "#/components/schemas/PracticeItem"
          }
        }
      },
      "PracticeRequest": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": {
            "type": "string",
            "example": "Software Development"
          },
          "head_id": {
            "type": ["string", "null"],
            "format": "uuid",
            "nullable": true,
            "example": "2d23f327-f308-4003-a9be-1ac7b9a8c01c",
            "description": "ID of a Person"
          }
        }
      },
      "Practice": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "2d23f327-f308-4003-a9be-1ac7b9a8c01c"
          },
          "name": {
            "type": "string",
            "example": "Software Development"
          },
          "head": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PersonItem"
              },
              {
                "nullable": true
              }
            ]
          },
          "organisation": {
            "$ref": "#/components/schemas/OrganisationItem"
          },
          "roles": {
            "type": "integer",
            "format": "int32",
            "example": 7
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-04-20T22:04:51.583801+01:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2021-04-20T22:16:57.492478+01:00"
          }
        }
      },
      "PracticeItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "2d23f327-f308-4003-a9be-1ac7b9a8c01c"
          },
          "name": {
            "type": "string",
            "example": "Software Development"
          },
          "head": {
            "$ref": "#/components/schemas/PersonItem"
          }
        }
      },
      "GradeRequest": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": {
            "type": "string",
            "example": "Senior Executive Officer"
          }
        }
      },
      "Grade": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "fac79045-d2f9-489f-acdb-510acbd239c3"
          },
          "name": {
            "type": "string",
            "example": "SEO"
          },
          "organisation": {
            "$ref": "#/components/schemas/OrganisationItem"
          },
          "roles": {
            "type": "integer",
            "format": "int32",
            "example": 7
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-04-20T22:04:51.583801+01:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2021-04-20T22:16:57.492478+01:00"
          }
        }
      },
      "GradeItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "fac79045-d2f9-489f-acdb-510acbd239c3"
          },
          "name": {
            "type": "string",
            "example": "SEO"
          }
        }
      },
      "LocationRequest": {
        "type": "object",
        "required": ["name", "address"],
        "properties": {
          "name": {
            "type": "string",
            "example": "Wigan"
          },
          "address": {
            "type": "string",
            "example": "62 West Wallaby Street, Wigan, Lancashire"
          }
        }
      },
      "Location": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "fac79045-d2f9-489f-acdb-510acbd239c3"
          },
          "name": {
            "type": "string",
            "example": "Wigan"
          },
          "address": {
            "type": "string",
            "example": "62 West Wallaby Street, Wigan, Lancashire"
          },
          "organisation": {
            "$ref": "#/components/schemas/OrganisationItem"
          },
          "people": {
            "type": "integer",
            "format": "int32",
            "example": 567
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-04-20T22:04:51.583801+01:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "example": "2021-04-20T22:16:57.492478+01:00"
          }
        }
      },
      "LocationItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "fac79045-d2f9-489f-acdb-510acbd239c3"
          },
          "name": {
            "type": "string",
            "example": "Wigan"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "format": "int32",
            "example": 404
          },
          "name": {
            "type": "string",
            "example": "Not Found"
          },
          "description": {
            "type": "string",
            "example": "The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again."
          }
        }
      }
    }
  }
}