{
  "openapi": "3.0.1",
  "info": {
    "title": "UnityTrip Policy Engine API",
    "version": "prototype-v1",
    "description": "The deterministic policy engine behind UnityTrip: validates itineraries against booking, penalty, and quota rules, adjusts quotas, and exposes the operational ontology (passenger types, trip reasons). Prototype-derived reference spec: servers and authentication are intentionally omitted; the production surface is provisioned per tenant under role-based access control.",
    "contact": {
      "name": "UnityTrip",
      "url": "https://unitytrip.com"
    }
  },
  "paths": {
    "/api/rules/quota/adjust": {
      "put": {
        "tags": [
          "Quota"
        ],
        "summary": "Adjust quota for a user.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdjustQuotaRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/AdjustQuotaRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/AdjustQuotaRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated successfully"
          },
          "400": {
            "description": "Could not process the request"
          },
          "401": {
            "description": "Unauthorized request"
          },
          "500": {
            "description": "Internal error"
          }
        }
      }
    },
    "/api/settings/passengerTypes": {
      "get": {
        "tags": [
          "Settings"
        ],
        "summary": "Returns all defined passenger types.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/PassengerTypeResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PassengerTypeResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/PassengerTypeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Could not process the request"
          },
          "401": {
            "description": "Unauthorized request"
          },
          "500": {
            "description": "Internal error"
          }
        }
      }
    },
    "/api/settings/tripReasons": {
      "get": {
        "tags": [
          "Settings"
        ],
        "summary": "Returns all defined trip reasons.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/TripReasonsResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TripReasonsResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/TripReasonsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Could not process the request"
          },
          "401": {
            "description": "Unauthorized request"
          },
          "500": {
            "description": "Internal error"
          }
        }
      }
    },
    "/api/rules/result": {
      "get": {
        "tags": [
          "Policies"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/RulesEngineResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RulesEngineResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/RulesEngineResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/rules/validator/penalties": {
      "post": {
        "tags": [
          "Policies"
        ],
        "summary": "Validate the user's penalty points.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PenaltiesValidatorRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PenaltiesValidatorRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PenaltiesValidatorRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation performed successfully",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ValidatorResult"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidatorResult"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidatorResult"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request"
          },
          "404": {
            "description": "Profile not found"
          },
          "500": {
            "description": "Internal error"
          }
        }
      }
    },
    "/api/rules/segment/validate": {
      "post": {
        "tags": [
          "Policies"
        ],
        "summary": "Validate the request against segment release time.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Parameters"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/Parameters"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/Parameters"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation performed successfully",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ValidatorResult"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidatorResult"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidatorResult"
                }
              }
            }
          },
          "500": {
            "description": "Internal error"
          }
        }
      }
    },
    "/api/rules/validate": {
      "post": {
        "tags": [
          "Policies"
        ],
        "summary": "Validate against all the booking, penalty and quota rules.",
        "parameters": [
          {
            "name": "test",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "result",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/TestResponse"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Parameters"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/Parameters"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/Parameters"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation performed successfully",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/RulesEngineResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RulesEngineResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/RulesEngineResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request"
          },
          "404": {
            "description": "Profile not found"
          },
          "500": {
            "description": "Internal error"
          }
        }
      }
    },
    "/api/rules/validator/search": {
      "post": {
        "tags": [
          "Policies"
        ],
        "summary": "Basic rule validation.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateSearchParametersRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateSearchParametersRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateSearchParametersRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation performed successfully",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ValidatorResult"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidatorResult"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidatorResult"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request"
          },
          "404": {
            "description": "Profile not found"
          },
          "500": {
            "description": "Internal error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AdjustQuotaRequest": {
        "type": "object",
        "properties": {
          "employeeId": {
            "type": "string",
            "nullable": true
          },
          "tripReasonId": {
            "type": "string",
            "nullable": true
          },
          "tripReasonName": {
            "type": "string",
            "nullable": true
          },
          "passengerTypeId": {
            "type": "string",
            "nullable": true
          },
          "year": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "quotaSeats": {
            "type": "integer",
            "format": "int32"
          },
          "timeFrame": {
            "$ref": "#/components/schemas/TimeFrame"
          }
        },
        "additionalProperties": false
      },
      "BookerDetails": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "relationship": {
            "type": "string",
            "nullable": true
          },
          "employeeId": {
            "type": "string",
            "nullable": true
          },
          "policyGroupId": {
            "type": "string",
            "nullable": true
          },
          "locationId": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "BookingEvent": {
        "type": "object",
        "properties": {
          "eventType": {
            "$ref": "#/components/schemas/BookingEventType"
          },
          "minutesBeforeDeparture": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "BookingEventType": {
        "enum": [
          "Cancellation",
          "Noshow",
          "Reschedule",
          "Other"
        ],
        "type": "string"
      },
      "BookingSourceType": {
        "enum": [
          "Corporate",
          "Private",
          "Any"
        ],
        "type": "string"
      },
      "Outbound": {
        "type": "object",
        "properties": {
          "passengerPriorities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PassengerPriorities"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Parameters": {
        "type": "object",
        "properties": {
          "bookerId": {
            "type": "string",
            "nullable": true
          },
          "bookerTravelerGroup": {
            "type": "string",
            "nullable": true
          },
          "bookerDetails": {
            "$ref": "#/components/schemas/BookerDetails"
          },
          "source": {
            "type": "string",
            "nullable": true
          },
          "tripReason": {
            "type": "string",
            "nullable": true
          },
          "international": {
            "type": "boolean",
            "nullable": true
          },
          "fareGroup": {
            "type": "string",
            "nullable": true
          },
          "travelers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Traveler"
            },
            "nullable": true
          },
          "itinerary": {
            "$ref": "#/components/schemas/RuleItinerary"
          },
          "bookingEvents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BookingEvent"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "PassengerPriorities": {
        "type": "object",
        "properties": {
          "priority": {
            "type": "integer",
            "format": "int32"
          },
          "passengerTypeId": {
            "type": "string",
            "nullable": true
          },
          "ruleId": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "PassengerTypeDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "bookingSource": {
            "$ref": "#/components/schemas/BookingSourceType"
          },
          "adHoc": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "PassengerTypeResponse": {
        "type": "object",
        "properties": {
          "passengerTypes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PassengerTypeDto"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "PenaltiesValidatorRequest": {
        "required": [
          "bookerId"
        ],
        "type": "object",
        "properties": {
          "bookerId": {
            "minLength": 1,
            "type": "string"
          },
          "bookingEvents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BookingEvent"
            },
            "nullable": true
          },
          "travelers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Traveler"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Return": {
        "type": "object",
        "properties": {
          "passengerPriorities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PassengerPriorities"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "RuleItinerary": {
        "type": "object",
        "properties": {
          "outbound": {
            "$ref": "#/components/schemas/RuleTrip"
          },
          "return": {
            "$ref": "#/components/schemas/RuleTrip"
          }
        },
        "additionalProperties": false
      },
      "RuleTrip": {
        "type": "object",
        "properties": {
          "segments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Segment"
            },
            "nullable": true
          },
          "passengerTypeIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "rescheduling": {
            "type": "boolean",
            "nullable": true
          },
          "bookingReference": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "RulesEngineResponse": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "result": {
            "$ref": "#/components/schemas/RulesEngineResult"
          }
        },
        "additionalProperties": false
      },
      "RulesEngineResult": {
        "type": "object",
        "properties": {
          "passed": {
            "type": "boolean"
          },
          "failedReasons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "outbound": {
            "$ref": "#/components/schemas/Outbound"
          },
          "return": {
            "$ref": "#/components/schemas/Return"
          }
        },
        "additionalProperties": false
      },
      "Segment": {
        "type": "object",
        "properties": {
          "transportationMode": {
            "$ref": "#/components/schemas/TransportationMode"
          },
          "departureDate": {
            "type": "string",
            "nullable": true
          },
          "isPeakPeriod": {
            "type": "boolean"
          },
          "details": {
            "$ref": "#/components/schemas/TripSegmentDetails"
          }
        },
        "additionalProperties": false
      },
      "TestResponse": {
        "enum": [
          "Success",
          "Failed"
        ],
        "type": "string"
      },
      "TimeFrame": {
        "enum": [
          "PerAnnum",
          "PerWeek",
          "PerSector",
          "PerPeakSail",
          "PerOffPeakSail"
        ],
        "type": "string"
      },
      "TransportationMode": {
        "enum": [
          "Accommodation",
          "Air",
          "Boat",
          "Maritime",
          "Vehicle",
          "Road"
        ],
        "type": "string"
      },
      "TransportationType": {
        "enum": [
          0,
          1,
          2,
          3
        ],
        "type": "integer",
        "format": "int32"
      },
      "Traveler": {
        "type": "object",
        "properties": {
          "travelerguid": {
            "type": "string",
            "nullable": true
          },
          "traveleremployeeid": {
            "type": "string",
            "nullable": true
          },
          "travelertypeid": {
            "type": "string",
            "nullable": true
          },
          "locationId": {
            "type": "string",
            "nullable": true
          },
          "policyGroupId": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "TripReasonDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "international": {
            "type": "boolean"
          },
          "bookingSource": {
            "$ref": "#/components/schemas/BookingSourceType"
          }
        },
        "additionalProperties": false
      },
      "TripReasonsResponse": {
        "type": "object",
        "properties": {
          "tripReasons": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TripReasonDto"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "TripSegmentDetails": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true
          },
          "departureName": {
            "type": "string",
            "nullable": true
          },
          "departureId": {
            "type": "string",
            "format": "uuid"
          },
          "departureAt": {
            "type": "string",
            "format": "date-time"
          },
          "arrivalName": {
            "type": "string",
            "nullable": true
          },
          "arrivalId": {
            "type": "string",
            "format": "uuid"
          },
          "arrivalAt": {
            "type": "string",
            "format": "date-time"
          },
          "transportationType": {
            "$ref": "#/components/schemas/TransportationType"
          }
        },
        "additionalProperties": false
      },
      "ValidateSearchParametersRequest": {
        "required": [
          "bookerId",
          "source",
          "tripReason"
        ],
        "type": "object",
        "properties": {
          "bookerId": {
            "minLength": 1,
            "type": "string"
          },
          "source": {
            "minLength": 1,
            "type": "string"
          },
          "tripReason": {
            "minLength": 1,
            "type": "string"
          },
          "outboundPassengerTypeIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "returnPassengerTypeIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "fareGroup": {
            "type": "string",
            "nullable": true
          },
          "travelers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Traveler"
            },
            "nullable": true
          },
          "bookingEvents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BookingEvent"
            },
            "nullable": true
          },
          "rescheduling": {
            "type": "boolean",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ValidatorResult": {
        "type": "object",
        "properties": {
          "passed": {
            "type": "boolean"
          },
          "failedReasons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    }
  }
}