{
  "openapi": "3.1.0",
  "info": {
    "title": "Demo Services Authority API (MOCK)",
    "version": "0.1.0",
    "description": "JSON API of a fictional UAE government entity, for demonstrations and MCP servers. Nothing here is a real government service; applications are mock records. The catalogue is public; applications need a bearer token from the portal's OAuth server (see /.well-known/oauth-authorization-server) and belong to the person who signed in."
  },
  "paths": {
    "/api/entity": {
      "get": {
        "operationId": "getEntity",
        "summary": "The entity: name, contact and news",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ar"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The entity",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "Service categories",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ar"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Category"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/services": {
      "get": {
        "operationId": "searchServices",
        "summary": "List or search services",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Words to search for, in English or Arabic",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "licences",
                "certificates",
                "business",
                "community",
                "support"
              ]
            }
          },
          {
            "name": "audience",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "individuals",
                "businesses"
              ]
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ar"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching services, best first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "demo": {
                      "type": "boolean"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "services": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ServiceSummary"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/services/{id}": {
      "get": {
        "operationId": "getService",
        "summary": "One service, with eligibility, documents, steps, fees and its application form",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Service id or code, e.g. event-permit or DSA-LIC-003",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ar"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The service",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Service"
                }
              }
            }
          },
          "404": {
            "description": "No such service",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/applications": {
      "post": {
        "operationId": "submitApplication",
        "summary": "Submit a mock application as the signed-in person",
        "security": [
          {
            "portal": [
              "applications"
            ]
          }
        ],
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ar"
              ],
              "default": "en"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApplicationInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The new application",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Application"
                }
              }
            }
          },
          "401": {
            "description": "Not signed in",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such service",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Fields that need correcting",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "const": "invalid_application"
                    },
                    "fields": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listApplications",
        "summary": "The signed-in person's applications, newest first",
        "security": [
          {
            "portal": [
              "applications"
            ]
          }
        ],
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ar"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Applications",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "applications": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Application"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/applications/{reference}": {
      "get": {
        "operationId": "getApplication",
        "summary": "Track one of your applications by its reference number",
        "security": [
          {
            "portal": [
              "applications"
            ]
          }
        ],
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "DEMO-2026-123456"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ar"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The application",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Application"
                }
              }
            }
          },
          "404": {
            "description": "No such application",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/applications/{reference}/advance": {
      "post": {
        "operationId": "advanceApplication",
        "summary": "Move one of your applications to its next status now (demo stand-in for a staff decision)",
        "security": [
          {
            "portal": [
              "applications"
            ]
          }
        ],
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "DEMO-2026-123456"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ar"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The application",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Application"
                }
              }
            }
          },
          "404": {
            "description": "No such application",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "portal": {
        "type": "oauth2",
        "description": "Sign in through the portal (UAE PASS when configured, else the demo sign-in). Clients register themselves at /oauth/register and use PKCE.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "/oauth/authorize",
            "tokenUrl": "/oauth/token",
            "refreshUrl": "/oauth/token",
            "scopes": {
              "applications": "Apply and follow applications in your name"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          }
        }
      },
      "ServiceSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "audience": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "fee": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "number"
              },
              "currency": {
                "type": "string"
              }
            }
          },
          "durationDays": {
            "type": "integer",
            "description": "Working days; 0 means instant"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "Field": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "text",
              "email",
              "tel",
              "number",
              "date",
              "select",
              "textarea"
            ]
          },
          "required": {
            "type": "boolean"
          },
          "label": {
            "type": "string"
          },
          "options": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                }
              }
            }
          },
          "min": {
            "type": "number"
          },
          "max": {
            "type": "number"
          },
          "pattern": {
            "type": "string"
          }
        }
      },
      "Service": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ServiceSummary"
          },
          {
            "type": "object",
            "properties": {
              "description": {
                "type": "string"
              },
              "eligibility": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "documents": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "steps": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "channels": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "form": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Field"
                },
                "description": "Goes in ApplicationInput.answers"
              },
              "applicantFields": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Field"
                },
                "description": "Goes in ApplicationInput.applicant"
              },
              "faqs": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "q": {
                      "type": "string"
                    },
                    "a": {
                      "type": "string"
                    }
                  }
                }
              },
              "related": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        ]
      },
      "ApplicationInput": {
        "type": "object",
        "required": [
          "serviceId",
          "answers"
        ],
        "properties": {
          "serviceId": {
            "type": "string"
          },
          "mobile": {
            "type": "string",
            "pattern": "^(\\+971|0)5[0-9]{8}$",
            "description": "Only when the signed-in profile has no mobile; name and email come from the profile"
          },
          "answers": {
            "type": "object",
            "description": "One value per field in the service's form",
            "additionalProperties": true
          }
        }
      },
      "Application": {
        "type": "object",
        "properties": {
          "reference": {
            "type": "string"
          },
          "demo": {
            "const": true
          },
          "serviceId": {
            "type": "string"
          },
          "serviceTitle": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "submitted",
              "in_review",
              "approved",
              "closed"
            ]
          },
          "statusLabel": {
            "type": "string"
          },
          "lifecycle": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "applicant": {
            "type": "object"
          },
          "answers": {
            "type": "object"
          },
          "history": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string"
                },
                "at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "url": {
            "type": "string"
          }
        }
      }
    }
  }
}