{
  "openapi": "3.1.0",
  "info": {
    "title": "JobDataPool API",
    "version": "1.0.0",
    "description": "Canonical API contract for the Job Pool data infrastructure layer (RFC-0002 aligned)."
  },
  "servers": [
    {
      "url": "https://api.jobdatapool.com",
      "description": "Canonical API domain"
    },
    {
      "url": "https://jobdatapool.com",
      "description": "Docs and compatibility host"
    }
  ],
  "tags": [
    {
      "name": "Health",
      "description": "Service health and version checks"
    },
    {
      "name": "Sources",
      "description": "Source repository and dataset pointer catalog"
    },
    {
      "name": "Jobs",
      "description": "Query versioned job listings data"
    }
  ],
  "paths": {
    "/v1/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Health check",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sources": {
      "get": {
        "tags": [
          "Sources"
        ],
        "summary": "List canonical data sources and contract pointers",
        "operationId": "getSources",
        "responses": {
          "200": {
            "description": "Source catalog",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceCatalog"
                }
              }
            }
          }
        }
      }
    },
    "/v1/jobs": {
      "get": {
        "tags": [
          "Jobs"
        ],
        "summary": "List jobs",
        "operationId": "listJobs",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of rows returned (1-500).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 50
            }
          },
          {
            "name": "industries",
            "in": "query",
            "description": "Comma-separated industries filter (case-insensitive partial match).",
            "schema": {
              "type": "string",
              "example": "Software,Government"
            }
          },
          {
            "name": "country_code",
            "in": "query",
            "description": "ISO-like 2-letter country code.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2,
              "example": "US"
            }
          },
          {
            "name": "distinct_by",
            "in": "query",
            "description": "Optional dedupe key.",
            "schema": {
              "type": "string",
              "enum": [
                "job_title",
                "apply_link",
                "url",
                "company_name"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Filtered jobs response",
            "headers": {
              "X-Jobs-Count": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Jobs-Cache": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "HIT",
                    "MISS"
                  ]
                }
              },
              "X-Jobs-Source": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Jobdatapool-Version": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/JobListing"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Jobs"
        ],
        "summary": "Query jobs with JSON body",
        "operationId": "queryJobs",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JobsQueryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Filtered jobs response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/JobListing"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "JobListing": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": {
            "type": "string"
          },
          "job_title": {
            "type": "string"
          },
          "company_name": {
            "type": "string"
          },
          "job_location": {
            "type": "string"
          },
          "job_seniority_level": {
            "type": "string"
          },
          "job_employment_type": {
            "type": "string"
          },
          "job_industries": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "job_summary": {
            "type": "string"
          },
          "job_base_pay_range": {
            "type": "string"
          },
          "job_posted_date": {
            "type": "string"
          },
          "competitiveness_score": {
            "type": [
              "number",
              "string"
            ]
          },
          "skills": {
            "type": "string"
          },
          "certifications": {
            "type": "string"
          },
          "industries": {
            "type": "string"
          },
          "achievements": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "apply_link": {
            "type": "string"
          },
          "country_code": {
            "type": "string"
          },
          "ingest_utc_date": {
            "type": "string"
          },
          "ingest_utc_hour": {
            "type": [
              "string",
              "number"
            ]
          },
          "source_business_url": {
            "type": "string"
          }
        }
      },
      "JobsQueryRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500
          },
          "industries": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "country_code": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2
          },
          "distinct_by": {
            "type": "string",
            "enum": [
              "job_title",
              "apply_link",
              "url",
              "company_name"
            ]
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "status": {
            "type": "string"
          },
          "service": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "time_utc": {
            "type": "string"
          },
          "data_source": {
            "type": "string"
          },
          "endpoints": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "required": [
          "status",
          "service",
          "version",
          "time_utc",
          "endpoints"
        ]
      },
      "SourceCatalog": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "service": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceRecord"
            }
          },
          "contracts": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "endpoints": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "required": [
          "service",
          "version",
          "sources",
          "contracts",
          "endpoints"
        ]
      },
      "SourceRecord": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "repository_url": {
            "type": "string"
          },
          "data_api_url": {
            "type": "string"
          },
          "dvc_pointer_url": {
            "type": "string"
          },
          "csv_url": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "kind",
          "repository_url",
          "data_api_url",
          "dvc_pointer_url",
          "csv_url"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}