{
  "openapi": "3.1.0",
  "info": {
    "title": "RDAP Explorer API",
    "description": "Query, validate, and enrich RDAP (Registration Data Access Protocol) responses per RFC 9083. Supports multiple RIRs, abuse contact extraction, threat intelligence, ownership validation, and legal context.",
    "version": "1.0.0",
    "contact": {
      "name": "BTOVEN Network",
      "url": "https://btoven.net"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://www.gnu.org/licenses/agpl-3.0.html"
    }
  },
  "servers": [
    {
      "url": "https://rdap.btoven.net",
      "description": "Production"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "Web UI",
        "description": "Returns the RDAP Explorer web interface with smart query form",
        "responses": {
          "200": {
            "description": "HTML page",
            "content": { "text/html": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/query": {
      "get": {
        "summary": "Query RDAP",
        "description": "Query RDAP data for a domain, IP address, ASN, CIDR range, nameserver, or entity. Returns HTML by default, or JSON when format=json is specified. The system automatically detects the query type from the input.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "The query value. Supports domain names (example.com), IPv4/IPv6 addresses (8.8.8.8, 2001:db8::1), CIDR ranges (192.168.1.0/24), AS numbers (AS15169 or 15169), nameservers (ns1.example.com), and entity handles.",
            "schema": { "type": "string", "maxLength": 253 },
            "examples": {
              "domain": { "value": "example.com", "summary": "Domain name lookup" },
              "ipv4": { "value": "8.8.8.8", "summary": "IPv4 address lookup" },
              "asn": { "value": "AS15169", "summary": "Autonomous system lookup" },
              "cidr": { "value": "192.168.1.0/24", "summary": "CIDR range lookup" }
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Response format. Omit for HTML, use 'json' for JSON API.",
            "schema": { "type": "string", "enum": ["json"] }
          }
        ],
        "responses": {
          "200": {
            "description": "RDAP query result",
            "content": {
              "text/html": { "schema": { "type": "string" } },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RdapTestResult" }
              }
            }
          },
          "400": { "description": "Invalid query parameter" },
          "429": { "description": "Rate limit exceeded" }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Health check",
        "description": "Returns the health status of the service",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "version": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "summary": "OpenAPI specification",
        "description": "Returns this OpenAPI 3.1 specification",
        "responses": {
          "200": {
            "description": "OpenAPI JSON specification",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RdapTestResult": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "The queried input" },
          "query_type": { "type": "string", "enum": ["domain", "ip", "autnum", "nameserver", "entity", "help"], "description": "Detected query type" },
          "rdap_server_url": { "type": "string", "description": "RDAP server URL that was queried" },
          "timestamp": { "type": "string", "format": "date-time", "description": "When the query was performed" },
          "errors": { "type": "array", "items": { "type": "string" }, "description": "Error messages" },
          "successes": { "type": "array", "items": { "type": "string" }, "description": "Success messages" },
          "validation_errors": { "type": "array", "items": { "type": "string" }, "description": "RFC 9083 compliance issues" },
          "validation_successes": { "type": "array", "items": { "type": "string" }, "description": "Passed validations" },
          "raw_content": { "type": "string", "description": "Raw JSON response from RDAP server" },
          "parsed": { "$ref": "#/components/schemas/RdapParsedResponse" },
          "enrichment": { "$ref": "#/components/schemas/EnrichmentResult" }
        },
        "required": ["query", "query_type", "rdap_server_url", "timestamp", "errors", "successes", "validation_errors", "validation_successes"]
      },
      "RdapParsedResponse": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "type": { "type": "string", "const": "Domain" },
              "data": { "$ref": "#/components/schemas/RdapDomain" }
            }
          },
          {
            "type": "object",
            "properties": {
              "type": { "type": "string", "const": "Raw" },
              "data": { "$ref": "#/components/schemas/RdapRawResponse" }
            }
          }
        ]
      },
      "RdapDomain": {
        "type": "object",
        "properties": {
          "objectClassName": { "type": "string" },
          "ldhName": { "type": "string" },
          "unicodeName": { "type": "string" },
          "status": { "type": "array", "items": { "type": "string" } },
          "events": { "type": "array", "items": { "$ref": "#/components/schemas/RdapEvent" } },
          "nameservers": { "type": "array", "items": { "type": "object" } },
          "entities": { "type": "array", "items": { "type": "object" } },
          "secureDNS": { "type": "object" },
          "links": { "type": "array", "items": { "type": "object" } },
          "notices": { "type": "array", "items": { "type": "object" } },
          "remarks": { "type": "array", "items": { "type": "object" } }
        }
      },
      "RdapRawResponse": {
        "type": "object",
        "properties": {
          "rdapConformance": { "type": "array", "items": { "type": "string" } },
          "objectClassName": { "type": "string" },
          "errorCode": { "type": "integer" },
          "title": { "type": "string" },
          "description": { "type": "array", "items": { "type": "string" } }
        }
      },
      "RdapEvent": {
        "type": "object",
        "properties": {
          "eventAction": { "type": "string" },
          "eventDate": { "type": "string" },
          "eventActor": { "type": "string" }
        }
      },
      "EnrichmentResult": {
        "type": "object",
        "properties": {
          "abuse_contacts": { "type": "array", "items": { "$ref": "#/components/schemas/AbuseContact" } },
          "rir_info": { "$ref": "#/components/schemas/RirInfo" },
          "threat_context": { "$ref": "#/components/schemas/ThreatContext" },
          "ownership_validation": { "$ref": "#/components/schemas/OwnershipValidation" },
          "legal_context": { "$ref": "#/components/schemas/LegalContext" },
          "entity_contacts": { "type": "array", "items": { "type": "object" } }
        }
      },
      "AbuseContact": {
        "type": "object",
        "properties": {
          "email": { "type": "string" },
          "phone": { "type": "string" },
          "handle": { "type": "string" },
          "name": { "type": "string" },
          "organization": { "type": "string" },
          "roles": { "type": "array", "items": { "type": "string" } }
        }
      },
      "RirInfo": {
        "type": "object",
        "properties": {
          "rir": { "type": "string", "enum": ["arin", "ripncc", "apnic", "lacnic", "afrinic", "iana", "unknown"] },
          "name": { "type": "string", "example": "ARIN" },
          "region": { "type": "string", "example": "North America" },
          "rdap_url": { "type": "string", "example": "https://rdap.arin.net/registry" },
          "website": { "type": "string", "example": "https://www.arin.net" },
          "whois_server": { "type": "string", "example": "whois.arin.net" },
          "abuse_contact": { "type": "string", "example": "info@arin.net" }
        }
      },
      "ThreatContext": {
        "type": "object",
        "properties": {
          "status_flags": { "type": "array", "items": { "type": "string" } },
          "suspicious_indicators": { "type": "array", "items": { "$ref": "#/components/schemas/SuspiciousIndicator" } },
          "dnssec_status": { "type": "string", "enum": ["Secure", "Insecure", "UnsignedDelegation", "Unknown"] },
          "reputation_notes": { "type": "array", "items": { "type": "string" } },
          "siem_metadata": { "$ref": "#/components/schemas/SiemMetadata" }
        }
      },
      "SuspiciousIndicator": {
        "type": "object",
        "properties": {
          "indicator_type": { "type": "string" },
          "description": { "type": "string" },
          "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] }
        }
      },
      "SiemMetadata": {
        "type": "object",
        "properties": {
          "log_severity": { "type": "string", "enum": ["informational", "low", "medium", "high", "critical"] },
          "event_category": { "type": "string" },
          "tags": { "type": "array", "items": { "type": "string" } },
          "recommended_actions": { "type": "array", "items": { "type": "string" } }
        }
      },
      "OwnershipValidation": {
        "type": "object",
        "properties": {
          "registrant_available": { "type": "boolean" },
          "registrar_available": { "type": "boolean" },
          "registrant_name": { "type": "string" },
          "registrant_organization": { "type": "string" },
          "registrar_name": { "type": "string" },
          "creation_date": { "type": "string" },
          "expiration_date": { "type": "string" },
          "last_changed": { "type": "string" },
          "entity_roles_found": { "type": "array", "items": { "type": "string" } },
          "validation_notes": { "type": "array", "items": { "type": "string" } },
          "ownership_strength": { "type": "string", "enum": ["Strong", "Partial", "Weak", "None"] }
        }
      },
      "LegalContext": {
        "type": "object",
        "properties": {
          "registrar_contact": { "type": "object" },
          "registrant_contact": { "type": "object" },
          "abuse_contacts": { "type": "array", "items": { "$ref": "#/components/schemas/AbuseContact" } },
          "rir_info": { "$ref": "#/components/schemas/RirInfo" },
          "legal_framework": { "type": "array", "items": { "$ref": "#/components/schemas/LegalFramework" } },
          "recommended_actions": { "type": "array", "items": { "type": "string" } },
          "data_retention_notes": { "type": "array", "items": { "type": "string" } }
        }
      },
      "LegalFramework": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "relevance": { "type": "string" }
        }
      }
    }
  }
}