Availability

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cheapest-domains/json-schema/cheapest-domains-availability-schema.json",
  "title": "Availability",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cheapest-domains-openapi.json#/components/schemas/Availability",
  "type": "object",
  "required": [
    "domain",
    "status",
    "reason",
    "message",
    "provider",
    "checkedAt",
    "expiresAt",
    "service",
    "apiVersion"
  ],
  "properties": {
    "availability": {
      "enum": [
        "available",
        "unavailable",
        "unknown"
      ],
      "description": "Registration status; independent of premium classification."
    },
    "premium": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Null means not confirmed, never standard tier."
    },
    "registrar": {
      "type": "string"
    },
    "attempts": {
      "type": "array",
      "maxItems": 5,
      "items": {
        "$ref": "#/$defs/AvailabilityAttempt"
      }
    },
    "fallback": {
      "type": "object",
      "required": [
        "registrar",
        "state",
        "reason"
      ],
      "properties": {
        "registrar": {
          "type": "string"
        },
        "state": {
          "enum": [
            "used",
            "unavailable"
          ]
        },
        "reason": {
          "type": "string"
        }
      }
    },
    "domain": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "available",
        "unavailable",
        "premium",
        "unsupported",
        "unknown"
      ]
    },
    "reason": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "provider": {
      "type": "object",
      "required": [
        "id",
        "name",
        "documentation"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "documentation": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "checkedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Successful provider response time; null when no reliable result was obtained."
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Recheck after this time; never a reservation or guarantee until expiry."
    },
    "listEnrichmentComplete": {
      "type": "boolean",
      "description": "Batch results: true when availability is known or every configured fallback stage has answered for this name. False means a later explicit request may add facts; it never means taken."
    },
    "service": {
      "$ref": "#/$defs/ServiceInformation"
    },
    "apiVersion": {
      "type": "string"
    }
  },
  "$defs": {
    "AvailabilityAttempt": {
      "type": "object",
      "required": [
        "provider",
        "availability",
        "premium",
        "reason",
        "checkedAt",
        "expiresAt"
      ],
      "properties": {
        "provider": {
          "type": "object",
          "required": [
            "id",
            "name",
            "documentation"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "documentation": {
              "type": "string",
              "format": "uri"
            }
          }
        },
        "availability": {
          "enum": [
            "available",
            "unavailable",
            "unknown"
          ]
        },
        "premium": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "reason": {
          "type": "string"
        },
        "checkedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "expiresAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "outcome": {
          "enum": [
            "answered",
            "failed",
            "pending"
          ],
          "description": "Whether this stage returned an answer, failed before confirming evidence, or is still in progress. Optional for older responses."
        },
        "retryAfterSeconds": {
          "type": "number",
          "minimum": 0,
          "description": "Suggested wait after a failed stage; never an evidence lifetime."
        }
      }
    },
    "ServiceInformation": {
      "type": "object",
      "required": [
        "name",
        "url",
        "setupUrl",
        "pluginUrl"
      ],
      "description": "Cheapest Domains identity and optional setup links, separate from upstream evidence. Does not establish client installation or provider health.",
      "properties": {
        "name": {
          "const": "Cheapest Domains"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "setupUrl": {
          "type": "string",
          "format": "uri"
        },
        "pluginUrl": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}