{
  "version": "1.0",
  "modules": [
    {
      "name": "BMI Management",
      "prefix": "/bmi-management",
      "endpoints": [
        {
          "method": "POST",
          "path": "/bmi-categories",
          "summary": "Create BMI Category",
          "description": "Creates a new BMI category reference record with classification range. Returns 400 if validation fails.",
          "request_body": {
            "schema_name": "BmicategoryCreate",
            "fields": [
              {
                "name": "name",
                "type": "str",
                "required": true
              },
              {
                "name": "min_bmi",
                "type": "float",
                "required": true
              },
              {
                "name": "max_bmi",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "description",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "color_code",
                "type": "str",
                "required": false,
                "nullable": true
              }
            ]
          },
          "response": {
            "schema_name": "BmicategoryResponse",
            "fields": [
              {
                "name": "name",
                "type": "str",
                "required": true
              },
              {
                "name": "min_bmi",
                "type": "float",
                "required": true
              },
              {
                "name": "max_bmi",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "description",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "color_code",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 201
        },
        {
          "method": "GET",
          "path": "/bmi-categories/{category_id}",
          "summary": "Get BMI Category",
          "description": "Retrieves a single BMI category by ID. Returns 404 if the category does not exist.",
          "path_params": [
            {
              "name": "category_id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "BmicategoryResponse",
            "fields": [
              {
                "name": "name",
                "type": "str",
                "required": true
              },
              {
                "name": "min_bmi",
                "type": "float",
                "required": true
              },
              {
                "name": "max_bmi",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "description",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "color_code",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "GET",
          "path": "/bmi-categories",
          "summary": "List BMI Categories",
          "description": "Returns a paginated list of all BMI categories ordered by minimum BMI value. Used to display classification ranges.",
          "query_params": [
            {
              "name": "limit",
              "type": "int",
              "required": false,
              "default": 20
            },
            {
              "name": "offset",
              "type": "int",
              "required": false,
              "default": 0
            }
          ],
          "response": {
            "schema_name": "BmicategoryResponse",
            "fields": [
              {
                "name": "name",
                "type": "str",
                "required": true
              },
              {
                "name": "min_bmi",
                "type": "float",
                "required": true
              },
              {
                "name": "max_bmi",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "description",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "color_code",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": true
          },
          "status_code": 200
        },
        {
          "method": "PUT",
          "path": "/bmi-categories/{category_id}",
          "summary": "Update BMI Category",
          "description": "Updates an existing BMI category. Returns 404 if the category does not exist, 400 if validation fails.",
          "path_params": [
            {
              "name": "category_id",
              "type": "str"
            }
          ],
          "request_body": {
            "schema_name": "BmicategoryUpdate",
            "fields": [
              {
                "name": "name",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "min_bmi",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "max_bmi",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "description",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "color_code",
                "type": "str",
                "required": false,
                "nullable": true
              }
            ]
          },
          "response": {
            "schema_name": "BmicategoryResponse",
            "fields": [
              {
                "name": "name",
                "type": "str",
                "required": true
              },
              {
                "name": "min_bmi",
                "type": "float",
                "required": true
              },
              {
                "name": "max_bmi",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "description",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "color_code",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "DELETE",
          "path": "/bmi-categories/{category_id}",
          "summary": "Delete BMI Category",
          "description": "Deletes a BMI category. Returns 404 if the category does not exist, 409 if calculations reference it.",
          "path_params": [
            {
              "name": "category_id",
              "type": "str"
            }
          ],
          "status_code": 200
        },
        {
          "method": "POST",
          "path": "/calculations",
          "summary": "Create Calculation",
          "description": "Creates a new BMI calculation record. Validates inputs and assigns BMI category. Returns 404 if category does not exist.",
          "request_body": {
            "schema_name": "CalculationCreate",
            "fields": [
              {
                "name": "height",
                "type": "float",
                "required": true
              },
              {
                "name": "weight",
                "type": "float",
                "required": true
              },
              {
                "name": "height_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "weight_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "bmi_value",
                "type": "float",
                "required": true
              },
              {
                "name": "bmi_category_id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "timestamp",
                "type": "datetime",
                "required": true
              }
            ]
          },
          "response": {
            "schema_name": "CalculationResponse",
            "fields": [
              {
                "name": "height",
                "type": "float",
                "required": true
              },
              {
                "name": "weight",
                "type": "float",
                "required": true
              },
              {
                "name": "height_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "weight_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "bmi_value",
                "type": "float",
                "required": true
              },
              {
                "name": "bmi_category_id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "timestamp",
                "type": "datetime",
                "required": true
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 201
        },
        {
          "method": "GET",
          "path": "/calculations/{calculation_id}",
          "summary": "Get Calculation",
          "description": "Retrieves a single calculation by ID. Returns 404 if the calculation does not exist.",
          "path_params": [
            {
              "name": "calculation_id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "CalculationResponse",
            "fields": [
              {
                "name": "height",
                "type": "float",
                "required": true
              },
              {
                "name": "weight",
                "type": "float",
                "required": true
              },
              {
                "name": "height_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "weight_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "bmi_value",
                "type": "float",
                "required": true
              },
              {
                "name": "bmi_category_id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "timestamp",
                "type": "datetime",
                "required": true
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "GET",
          "path": "/calculations",
          "summary": "List Calculations With Category",
          "description": "Returns a paginated list of calculations with BMI category details. Supports optional session_id filter. Ordered by timestamp descending.",
          "query_params": [
            {
              "name": "limit",
              "type": "int",
              "required": false,
              "default": 20
            },
            {
              "name": "offset",
              "type": "int",
              "required": false,
              "default": 0
            },
            {
              "name": "session_id",
              "type": "str",
              "required": false
            }
          ],
          "response": {
            "schema_name": "CalculationDetailResponse",
            "fields": [
              {
                "name": "height",
                "type": "float",
                "required": true
              },
              {
                "name": "weight",
                "type": "float",
                "required": true
              },
              {
                "name": "height_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "weight_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "bmi_value",
                "type": "float",
                "required": true
              },
              {
                "name": "bmi_category_id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "timestamp",
                "type": "datetime",
                "required": true
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "bmi_category",
                "type": "BmicategoryResponse",
                "required": true,
                "fields": [
                  {
                    "name": "name",
                    "type": "str",
                    "required": true
                  },
                  {
                    "name": "min_bmi",
                    "type": "float",
                    "required": true
                  },
                  {
                    "name": "max_bmi",
                    "type": "float",
                    "required": false,
                    "nullable": true
                  },
                  {
                    "name": "description",
                    "type": "str",
                    "required": false,
                    "nullable": true
                  },
                  {
                    "name": "color_code",
                    "type": "str",
                    "required": false,
                    "nullable": true
                  },
                  {
                    "name": "id",
                    "type": "str",
                    "required": true
                  },
                  {
                    "name": "created_at",
                    "type": "datetime",
                    "required": true
                  },
                  {
                    "name": "updated_at",
                    "type": "datetime",
                    "required": true
                  }
                ]
              }
            ],
            "is_list": true
          },
          "status_code": 200
        },
        {
          "method": "PUT",
          "path": "/calculations/{calculation_id}",
          "summary": "Update Calculation",
          "description": "Updates an existing calculation record. Returns 404 if the calculation or referenced category does not exist.",
          "path_params": [
            {
              "name": "calculation_id",
              "type": "str"
            }
          ],
          "request_body": {
            "schema_name": "CalculationUpdate",
            "fields": [
              {
                "name": "height",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "weight",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "height_unit",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "weight_unit",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "bmi_value",
                "type": "float",
                "required": false,
                "nullable": true
              },
              {
                "name": "bmi_category_id",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "timestamp",
                "type": "datetime",
                "required": false,
                "nullable": true
              }
            ]
          },
          "response": {
            "schema_name": "CalculationResponse",
            "fields": [
              {
                "name": "height",
                "type": "float",
                "required": true
              },
              {
                "name": "weight",
                "type": "float",
                "required": true
              },
              {
                "name": "height_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "weight_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "bmi_value",
                "type": "float",
                "required": true
              },
              {
                "name": "bmi_category_id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "timestamp",
                "type": "datetime",
                "required": true
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "DELETE",
          "path": "/calculations/{calculation_id}",
          "summary": "Delete Calculation",
          "description": "Deletes a calculation record. Returns 404 if the calculation does not exist.",
          "path_params": [
            {
              "name": "calculation_id",
              "type": "str"
            }
          ],
          "status_code": 200
        },
        {
          "method": "GET",
          "path": "/calculations/{calculation_id}/details",
          "summary": "Get Calculation Details",
          "description": "Retrieves a calculation with full BMI category details including name, description, color code, and range. Returns 404 if not found.",
          "path_params": [
            {
              "name": "calculation_id",
              "type": "str"
            }
          ],
          "response": {
            "schema_name": "CalculationDetailResponse",
            "fields": [
              {
                "name": "height",
                "type": "float",
                "required": true
              },
              {
                "name": "weight",
                "type": "float",
                "required": true
              },
              {
                "name": "height_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "weight_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "bmi_value",
                "type": "float",
                "required": true
              },
              {
                "name": "bmi_category_id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "timestamp",
                "type": "datetime",
                "required": true
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "bmi_category",
                "type": "BmicategoryResponse",
                "required": true,
                "fields": [
                  {
                    "name": "name",
                    "type": "str",
                    "required": true
                  },
                  {
                    "name": "min_bmi",
                    "type": "float",
                    "required": true
                  },
                  {
                    "name": "max_bmi",
                    "type": "float",
                    "required": false,
                    "nullable": true
                  },
                  {
                    "name": "description",
                    "type": "str",
                    "required": false,
                    "nullable": true
                  },
                  {
                    "name": "color_code",
                    "type": "str",
                    "required": false,
                    "nullable": true
                  },
                  {
                    "name": "id",
                    "type": "str",
                    "required": true
                  },
                  {
                    "name": "created_at",
                    "type": "datetime",
                    "required": true
                  },
                  {
                    "name": "updated_at",
                    "type": "datetime",
                    "required": true
                  }
                ]
              }
            ],
            "is_list": false
          },
          "status_code": 200
        },
        {
          "method": "POST",
          "path": "/calculations/calculate",
          "summary": "Calculate BMI",
          "description": "Calculates BMI from height and weight inputs, converts to metric units, determines category based on BMI value, stores calculation record, and returns result with category details. Enforces 50 calculation limit per session.",
          "request_body": {
            "schema_name": "CalculateRequest",
            "fields": [
              {
                "name": "height",
                "type": "float",
                "required": true
              },
              {
                "name": "weight",
                "type": "float",
                "required": true
              },
              {
                "name": "height_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "weight_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": false,
                "nullable": true
              }
            ]
          },
          "response": {
            "schema_name": "CalculationDetailResponse",
            "fields": [
              {
                "name": "height",
                "type": "float",
                "required": true
              },
              {
                "name": "weight",
                "type": "float",
                "required": true
              },
              {
                "name": "height_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "weight_unit",
                "type": "str",
                "required": true
              },
              {
                "name": "bmi_value",
                "type": "float",
                "required": true
              },
              {
                "name": "bmi_category_id",
                "type": "str",
                "required": true
              },
              {
                "name": "session_id",
                "type": "str",
                "required": false,
                "nullable": true
              },
              {
                "name": "timestamp",
                "type": "datetime",
                "required": true
              },
              {
                "name": "id",
                "type": "str",
                "required": true
              },
              {
                "name": "created_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "updated_at",
                "type": "datetime",
                "required": true
              },
              {
                "name": "bmi_category",
                "type": "BmicategoryResponse",
                "required": true,
                "fields": [
                  {
                    "name": "name",
                    "type": "str",
                    "required": true
                  },
                  {
                    "name": "min_bmi",
                    "type": "float",
                    "required": true
                  },
                  {
                    "name": "max_bmi",
                    "type": "float",
                    "required": false,
                    "nullable": true
                  },
                  {
                    "name": "description",
                    "type": "str",
                    "required": false,
                    "nullable": true
                  },
                  {
                    "name": "color_code",
                    "type": "str",
                    "required": false,
                    "nullable": true
                  },
                  {
                    "name": "id",
                    "type": "str",
                    "required": true
                  },
                  {
                    "name": "created_at",
                    "type": "datetime",
                    "required": true
                  },
                  {
                    "name": "updated_at",
                    "type": "datetime",
                    "required": true
                  }
                ]
              }
            ],
            "is_list": false
          },
          "status_code": 201
        },
        {
          "method": "DELETE",
          "path": "/calculations/session/{session_id}",
          "summary": "Clear Session History",
          "description": "Deletes all calculation records for a given session. Returns count of deleted records.",
          "path_params": [
            {
              "name": "session_id",
              "type": "str"
            }
          ],
          "status_code": 200
        }
      ]
    }
  ],
  "enums": {
    "HeightUnit": [
      "CM",
      "METERS",
      "FEET",
      "INCHES",
      "FEET_INCHES"
    ],
    "WeightUnit": [
      "KG",
      "LBS"
    ],
    "BMICategoryName": [
      "UNDERWEIGHT",
      "NORMAL_WEIGHT",
      "OVERWEIGHT",
      "OBESE"
    ]
  }
}