{
  "openapi": "3.1.0",
  "info": {
    "title": "iGov Municipal Digital Service API Blueprint",
    "version": "0.1.0",
    "description": "Reference contract for designing a municipal digital public service. This blueprint is not connected to a municipality and does not expose production or personal data. Each implementation must be adapted, secured and approved for the selected service."
  },
  "servers": [
    {
      "url": "https://api.example-municipality.ro",
      "description": "Placeholder; replaced by the municipality's approved API host"
    }
  ],
  "tags": [
    { "name": "Applications", "description": "Citizen applications and their visible status" },
    { "name": "Documents", "description": "Document references and signatures" },
    { "name": "Events", "description": "Auditable state changes from institutional systems" },
    { "name": "Metrics", "description": "Public-safe aggregate service indicators" }
  ],
  "paths": {
    "/v1/services/{serviceId}/applications": {
      "post": {
        "tags": ["Applications"],
        "summary": "Submit an application",
        "operationId": "submitApplication",
        "security": [{ "citizenOidc": ["service.write"] }],
        "parameters": [{ "$ref": "#/components/parameters/ServiceId" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationInput" } } }
        },
        "responses": {
          "201": { "description": "Application accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } },
          "400": { "$ref": "#/components/responses/Problem" },
          "401": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/applications/{applicationId}": {
      "get": {
        "tags": ["Applications"],
        "summary": "Read the citizen-visible status and deadline",
        "operationId": "getApplication",
        "security": [{ "citizenOidc": ["service.read"] }],
        "parameters": [{ "$ref": "#/components/parameters/ApplicationId" }],
        "responses": {
          "200": { "description": "Current application state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } },
          "404": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/applications/{applicationId}/documents": {
      "post": {
        "tags": ["Documents"],
        "summary": "Attach a securely uploaded document to an application",
        "operationId": "attachDocument",
        "security": [{ "citizenOidc": ["service.write"] }],
        "parameters": [{ "$ref": "#/components/parameters/ApplicationId" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentReference" } } }
        },
        "responses": {
          "202": { "description": "Document reference accepted for validation" },
          "400": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/applications/{applicationId}/events": {
      "post": {
        "tags": ["Events"],
        "summary": "Record an auditable state change",
        "operationId": "recordApplicationEvent",
        "security": [{ "institutionOAuth": ["events.write"] }],
        "parameters": [{ "$ref": "#/components/parameters/ApplicationId" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventInput" } } }
        },
        "responses": {
          "202": { "description": "Event accepted" },
          "400": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/v1/services/{serviceId}/metrics": {
      "get": {
        "tags": ["Metrics"],
        "summary": "Read aggregate, public-safe service indicators",
        "operationId": "getServiceMetrics",
        "security": [],
        "parameters": [
          { "$ref": "#/components/parameters/ServiceId" },
          { "name": "period", "in": "query", "schema": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" }, "description": "Calendar month, YYYY-MM" }
        ],
        "responses": {
          "200": { "description": "Aggregate indicators without personal records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicMetrics" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "citizenOidc": {
        "type": "openIdConnect",
        "openIdConnectUrl": "https://identity.example-municipality.ro/.well-known/openid-configuration"
      },
      "institutionOAuth": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://identity.example-municipality.ro/oauth2/token",
            "scopes": { "events.write": "Record institutional workflow events" }
          }
        }
      }
    },
    "parameters": {
      "ServiceId": { "name": "serviceId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{3,80}$" } },
      "ApplicationId": { "name": "applicationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
    },
    "schemas": {
      "ApplicationInput": {
        "type": "object",
        "additionalProperties": false,
        "required": ["formVersion", "answers", "privacyNoticeAccepted"],
        "properties": {
          "formVersion": { "type": "string" },
          "answers": { "type": "object", "additionalProperties": true },
          "privacyNoticeAccepted": { "type": "boolean", "const": true }
        }
      },
      "Application": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "serviceId", "status", "submittedAt", "updatedAt"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "serviceId": { "type": "string" },
          "status": { "type": "string", "enum": ["submitted", "validation", "needs_information", "in_review", "approved", "rejected", "completed"] },
          "submittedAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "estimatedResolutionAt": { "type": ["string", "null"], "format": "date-time" },
          "nextCitizenAction": { "type": ["string", "null"] }
        }
      },
      "DocumentReference": {
        "type": "object",
        "additionalProperties": false,
        "required": ["uploadToken", "documentType", "sha256"],
        "properties": {
          "uploadToken": { "type": "string", "description": "Short-lived token returned by the approved secure upload service" },
          "documentType": { "type": "string" },
          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
        }
      },
      "EventInput": {
        "type": "object",
        "additionalProperties": false,
        "required": ["eventId", "type", "occurredAt", "sourceSystem"],
        "properties": {
          "eventId": { "type": "string", "format": "uuid" },
          "type": { "type": "string" },
          "occurredAt": { "type": "string", "format": "date-time" },
          "sourceSystem": { "type": "string" },
          "publicMessage": { "type": ["string", "null"], "maxLength": 500 }
        }
      },
      "PublicMetrics": {
        "type": "object",
        "additionalProperties": false,
        "required": ["serviceId", "period", "submitted", "completed", "medianResolutionHours", "completionRate"],
        "properties": {
          "serviceId": { "type": "string" },
          "period": { "type": "string" },
          "submitted": { "type": "integer", "minimum": 0 },
          "completed": { "type": "integer", "minimum": 0 },
          "medianResolutionHours": { "type": ["number", "null"], "minimum": 0 },
          "completionRate": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
          "suppressionThreshold": { "type": "integer", "minimum": 1, "description": "Small groups below this threshold are not published" }
        }
      },
      "Problem": {
        "type": "object",
        "required": ["type", "title", "status"],
        "properties": {
          "type": { "type": "string", "format": "uri-reference" },
          "title": { "type": "string" },
          "status": { "type": "integer" },
          "detail": { "type": "string" },
          "traceId": { "type": "string" }
        }
      }
    },
    "responses": {
      "Problem": {
        "description": "Problem details",
        "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }
      }
    }
  }
}