{
  "paths": {
    "/calendars": {
      "get": {
        "tags": ["Calendars"],
        "summary": "List calendars",
        "description": "Returns all calendars the user owns or has been shared with. Each calendar includes the user's role (owner, editor, or viewer). Requires `calendars:read` scope.",
        "operationId": "listCalendars",
        "responses": {
          "200": {
            "description": "List of calendars",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["items", "page"],
                  "properties": {
                    "items": { "type": "array", "items": { "$ref": "#/components/schemas/Calendar" } },
                    "page": { "$ref": "#/components/schemas/PageInfo" }
                  }
                }
              }
            }
          },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "post": {
        "tags": ["Calendars"],
        "summary": "Create a calendar",
        "description": "Creates a new calendar owned by the authenticated user. Requires `calendars:write` scope.",
        "operationId": "createCalendar",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string", "minLength": 1, "maxLength": 80, "example": "Work" },
                  "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "example": "#22C55E" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calendar created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["calendar"],
                  "properties": {
                    "calendar": { "$ref": "#/components/schemas/Calendar" }
                  }
                }
              }
            }
          },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/calendars/{id}": {
      "get": {
        "tags": ["Calendars"],
        "summary": "Get a calendar",
        "description": "Returns a single calendar by ID. User must be owner or member. Requires `calendars:read` scope.",
        "operationId": "getCalendar",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" },
            "description": "Calendar ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Calendar details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["calendar"],
                  "properties": {
                    "calendar": { "$ref": "#/components/schemas/Calendar" }
                  }
                }
              }
            }
          },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Insufficient scope or permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Calendar not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "put": {
        "tags": ["Calendars"],
        "summary": "Update a calendar",
        "description": "Updates a calendar's name, color, or public status. Only the owner can change `is_public`. Requires `calendars:write` scope.",
        "operationId": "updateCalendar",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" },
            "description": "Calendar ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "minLength": 1, "maxLength": 80, "example": "Work Calendar" },
                  "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "example": "#22C55E" },
                  "is_public": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calendar updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["calendar"],
                  "properties": {
                    "calendar": { "$ref": "#/components/schemas/Calendar" }
                  }
                }
              }
            }
          },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Insufficient scope or permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Calendar not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "delete": {
        "tags": ["Calendars"],
        "summary": "Delete a calendar",
        "description": "Soft-deletes a calendar and all its events. Only the owner can delete. Requires `calendars:write` scope.",
        "operationId": "deleteCalendar",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" },
            "description": "Calendar ID"
          }
        ],
        "responses": {
          "200": { "description": "Calendar deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Only owner can delete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Calendar not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/calendars/{id}/share": {
      "post": {
        "tags": ["Calendars"],
        "summary": "Share a calendar",
        "description": "Shares a calendar with another user by email, granting them a role (editor or viewer). Only the owner can share. Cannot share with self. Requires `calendars:write` scope.",
        "operationId": "shareCalendar",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" },
            "description": "Calendar ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["target", "role"],
                "properties": {
                  "target": {
                    "type": "object",
                    "required": ["email"],
                    "properties": {
                      "email": { "type": "string", "format": "email", "example": "other@example.com" }
                    }
                  },
                  "role": { "type": "string", "enum": ["editor", "viewer"], "example": "editor" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Calendar shared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
          "400": { "description": "Validation error (e.g. sharing with self)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Only owner can share", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Calendar or target user not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/calendars/{id}/members": {
      "get": {
        "tags": ["Calendars"],
        "summary": "List calendar members",
        "description": "Returns all members of a calendar with their roles. Requires `calendars:read` scope.",
        "operationId": "listCalendarMembers",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" },
            "description": "Calendar ID"
          }
        ],
        "responses": {
          "200": {
            "description": "List of members",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["items", "page"],
                  "properties": {
                    "items": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarMember" } },
                    "page": { "$ref": "#/components/schemas/PageInfo" }
                  }
                }
              }
            }
          },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Insufficient scope or permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Calendar not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/calendars/{id}/members/{userID}": {
      "delete": {
        "tags": ["Calendars"],
        "summary": "Remove a calendar member",
        "description": "Removes a member from a shared calendar. Only the owner can remove members. The owner cannot be removed. Requires `calendars:write` scope.",
        "operationId": "removeCalendarMember",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" },
            "description": "Calendar ID"
          },
          {
            "name": "userID",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" },
            "description": "User ID of the member to remove"
          }
        ],
        "responses": {
          "200": { "description": "Member removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
          "400": { "description": "Cannot remove owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Only owner can remove members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Calendar or member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  }
}