{
  "openapi": "3.1.0",
  "info": {
    "title": "ValidAPI — illustrative validation contract",
    "version": "0.1.0-example",
    "description": "Fictional design reference only. There is no available ValidAPI service behind this specification. It does not perform validation or describe production coverage, pricing, authorization, or guarantees. Replace it with the actual provider contract before implementation."
  },
  "servers": [
    {
      "url": "https://api.example.invalid",
      "description": "Non-operational example host. Do not send personal information."
    }
  ],
  "paths": {
    "/v1/validate/drivers-license": {
      "post": {
        "operationId": "illustrateLicense",
        "summary": "Driver’s license fictional example",
        "description": "A correctly formatted license number does not establish document authenticity, current driving entitlement, or the identity of its holder. This route is proposed, not operational.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LicenseExampleRequest"
              },
              "example": {
                "document_type": "drivers_license",
                "issuing_country": "US",
                "issuing_region": "CA",
                "document_number": "DEMO-NOT-A-LICENSE"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Illustrative processed response. Not proof of a real-world result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleResponse"
                },
                "example": {
                  "demo": true,
                  "request_id": "sample_license_001",
                  "status": "needs_review",
                  "checks": {
                    "structure": "pass",
                    "issuer_record": "not_checked",
                    "holder_identity": "not_checked"
                  },
                  "reasons": [
                    {
                      "code": "example_only",
                      "message": "Fictional fixture; no real-world validation performed."
                    }
                  ],
                  "next_action": "review_requirements"
                }
              }
            }
          }
        }
      }
    },
    "/v1/validate/passport": {
      "post": {
        "operationId": "illustratePassport",
        "summary": "Passport fictional example",
        "description": "A matching MRZ check digit is a consistency signal—not proof that a passport is genuine or belongs to the person presenting it. This route is proposed, not operational.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PassportExampleRequest"
              },
              "example": {
                "document_type": "passport",
                "issuing_country": "GB",
                "document_number": "DEMO-PASSPORT",
                "capture_source": "fictional_fixture"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Illustrative processed response. Not proof of a real-world result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleResponse"
                },
                "example": {
                  "demo": true,
                  "request_id": "sample_passport_001",
                  "status": "needs_review",
                  "checks": {
                    "structure": "pass",
                    "authenticity": "not_checked",
                    "holder_identity": "not_checked"
                  },
                  "reasons": [
                    {
                      "code": "example_only",
                      "message": "Fictional fixture; no real-world validation performed."
                    }
                  ],
                  "next_action": "review_requirements"
                }
              }
            }
          }
        }
      }
    },
    "/v1/validate/address": {
      "post": {
        "operationId": "illustrateAddress",
        "summary": "Home address fictional example",
        "description": "Address normalization is not proof of residence. A reference match does not, by itself, establish that a particular person lives there. This route is proposed, not operational.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddressExampleRequest"
              },
              "example": {
                "country": "US",
                "line1": "123 Example Street",
                "line2": "Unit 4",
                "city": "Example City",
                "region": "CA",
                "postal_code": "00000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Illustrative processed response. Not proof of a real-world result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleResponse"
                },
                "example": {
                  "demo": true,
                  "request_id": "sample_address_001",
                  "status": "needs_review",
                  "checks": {
                    "structure": "pass",
                    "postal_reference": "not_checked",
                    "residence": "not_checked"
                  },
                  "reasons": [
                    {
                      "code": "example_only",
                      "message": "Fictional fixture; no real-world validation performed."
                    }
                  ],
                  "next_action": "review_requirements"
                }
              }
            }
          }
        }
      }
    },
    "/v1/validate/mobile": {
      "post": {
        "operationId": "illustrateMobile",
        "summary": "Mobile number fictional example",
        "description": "Formatting or numbering-plan validation does not establish reachability, possession of a number, or the legal identity of its user. This route is proposed, not operational.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MobileExampleRequest"
              },
              "example": {
                "country": "US",
                "number": "+1 202 555 0123"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Illustrative processed response. Not proof of a real-world result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleResponse"
                },
                "example": {
                  "demo": true,
                  "request_id": "sample_mobile_001",
                  "status": "needs_review",
                  "checks": {
                    "structure": "pass",
                    "reachability": "not_checked",
                    "possession": "not_checked"
                  },
                  "reasons": [
                    {
                      "code": "example_only",
                      "message": "Fictional fixture; no real-world validation performed."
                    }
                  ],
                  "next_action": "review_requirements"
                }
              }
            }
          }
        }
      }
    },
    "/v1/validate/legal-name": {
      "post": {
        "operationId": "illustrateName",
        "summary": "Legal name fictional example",
        "description": "Name parsing and similarity do not establish a legal identity. There is no universal name pattern that proves whether a person’s name is legitimate. This route is proposed, not operational.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NameExampleRequest"
              },
              "example": {
                "full_name": "Alex Example",
                "purpose": "record_consistency"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Illustrative processed response. Not proof of a real-world result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleResponse"
                },
                "example": {
                  "demo": true,
                  "request_id": "sample_name_001",
                  "status": "needs_review",
                  "checks": {
                    "structure": "pass",
                    "record_match": "not_checked",
                    "legal_identity": "not_checked"
                  },
                  "reasons": [
                    {
                      "code": "example_only",
                      "message": "Fictional fixture; no real-world validation performed."
                    }
                  ],
                  "next_action": "review_requirements"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ExampleResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "demo",
          "request_id",
          "status",
          "checks",
          "reasons",
          "next_action"
        ],
        "properties": {
          "demo": {
            "type": "boolean",
            "const": true,
            "description": "This illustrative contract only describes fictional demo responses."
          },
          "request_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pass",
              "needs_correction",
              "needs_review",
              "unsupported",
              "unavailable"
            ]
          },
          "checks": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "string",
              "enum": [
                "pass",
                "fail",
                "not_checked",
                "unknown"
              ]
            }
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "code",
                "message"
              ],
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          },
          "next_action": {
            "type": "string",
            "enum": [
              "review_requirements",
              "correct_input",
              "review",
              "retry",
              "continue",
              "use_alternative"
            ]
          }
        }
      },
      "LicenseExampleRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "document_type",
          "issuing_country",
          "issuing_region",
          "document_number"
        ],
        "properties": {
          "document_type": {
            "type": "string",
            "minLength": 1
          },
          "issuing_country": {
            "type": "string",
            "minLength": 1
          },
          "issuing_region": {
            "type": "string",
            "minLength": 1
          },
          "document_number": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "PassportExampleRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "document_type",
          "issuing_country",
          "document_number",
          "capture_source"
        ],
        "properties": {
          "document_type": {
            "type": "string",
            "minLength": 1
          },
          "issuing_country": {
            "type": "string",
            "minLength": 1
          },
          "document_number": {
            "type": "string",
            "minLength": 1
          },
          "capture_source": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "AddressExampleRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "country",
          "line1",
          "line2",
          "city",
          "region",
          "postal_code"
        ],
        "properties": {
          "country": {
            "type": "string",
            "minLength": 1
          },
          "line1": {
            "type": "string",
            "minLength": 1
          },
          "line2": {
            "type": "string",
            "minLength": 1
          },
          "city": {
            "type": "string",
            "minLength": 1
          },
          "region": {
            "type": "string",
            "minLength": 1
          },
          "postal_code": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "MobileExampleRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "country",
          "number"
        ],
        "properties": {
          "country": {
            "type": "string",
            "minLength": 1
          },
          "number": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "NameExampleRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "full_name",
          "purpose"
        ],
        "properties": {
          "full_name": {
            "type": "string",
            "minLength": 1
          },
          "purpose": {
            "type": "string",
            "minLength": 1
          }
        }
      }
    }
  }
}