{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://clouatre.ca/.well-known/resume-eval-response-schema.json",
  "title": "Resume evaluation response (premium /v1 resume-eval)",
  "description": "Machine-readable contract for the premium resume evaluation endpoint: v1 heuristic scores, optional v2 judge-scored findings, additive structured warnings, and the x402 402 payment challenge returned when payment is required.",
  "oneOf": [
    {
      "$ref": "#/$defs/ResumeEvalReport"
    },
    {
      "$ref": "#/$defs/PaymentChallenge"
    }
  ],
  "$defs": {
    "ResumeEvalReport": {
      "type": "object",
      "required": ["scores", "total", "findings"],
      "properties": {
        "scores": {
          "type": "object",
          "required": [
            "impact_quantified",
            "ats_parseable",
            "executive_framing",
            "contact_complete"
          ],
          "additionalProperties": false,
          "properties": {
            "impact_quantified": {
              "$ref": "#/$defs/BinaryScore"
            },
            "ats_parseable": {
              "$ref": "#/$defs/BinaryScore"
            },
            "executive_framing": {
              "$ref": "#/$defs/BinaryScore"
            },
            "contact_complete": {
              "$ref": "#/$defs/BinaryScore"
            }
          }
        },
        "total": {
          "type": "integer",
          "minimum": 0,
          "maximum": 4,
          "description": "Sum of the four scores (0-4). Equal to Object.values(scores) sum; degraded checks are explicit 0s."
        },
        "findings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Finding"
          }
        },
        "warnings": {
          "type": "array",
          "description": "Present only when a non-fatal degradation occurred. A failed check never appears as a boolean pass; it is either omitted from findings (jd_aligned) or scored as an explicit 0 (linguistic checks) with a warning here.",
          "items": {
            "$ref": "#/$defs/Warning"
          }
        },
        "technical_depth": {
          "type": "object",
          "description": "Additive judge-scored hands-on engineering depth (0-5; fractional raw score, rounded level, judge confidence). Present only when the judge scored it successfully; never contributes to total. Omitted on failure, with a structured warning.",
          "required": ["score", "level", "confidence"],
          "additionalProperties": false,
          "properties": {
            "score": {
              "type": "number",
              "minimum": 0,
              "maximum": 5,
              "description": "Raw judge score; not a calibrated probability."
            },
            "level": {
              "type": "integer",
              "minimum": 0,
              "maximum": 5,
              "description": "Math.round(score) ordinal bucket."
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "description": "Judge confidence."
            }
          }
        }
      }
    },
    "BinaryScore": {
      "type": "integer",
      "enum": [0, 1]
    },
    "Finding": {
      "type": "object",
      "required": ["check", "pass", "detail"],
      "properties": {
        "check": {
          "type": "string",
          "description": "One of impact_quantified, executive_framing, ats_parseable, contact_complete, jd_aligned.",
          "enum": [
            "impact_quantified",
            "executive_framing",
            "ats_parseable",
            "contact_complete",
            "jd_aligned"
          ]
        },
        "pass": {
          "type": "boolean"
        },
        "detail": {
          "type": "string"
        },
        "gap": {
          "type": "string",
          "minLength": 1,
          "description": "Optional; concrete deficiency in the resume cited by the judge for a failing finding. Present on failing judge-scored findings; omitted when the judge does not provide one. Never empty."
        },
        "action": {
          "type": "string",
          "minLength": 1,
          "description": "Optional; exactly one suggested revision or strengthening action. Omitted when not provided. Never empty."
        }
      }
    },
    "Warning": {
      "type": "object",
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "CONFIG_UNAVAILABLE",
            "UPSTREAM_TIMEOUT",
            "UPSTREAM_UNAVAILABLE",
            "UPSTREAM_INVALID_OUTPUT"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable reason the check was not evaluated."
        }
      }
    },
    "PaymentChallenge": {
      "type": "object",
      "description": "HTTP 402 response body per the x402 protocol when payment is required.",
      "required": ["x402Version", "accepts"],
      "properties": {
        "x402Version": {
          "type": "integer"
        },
        "error": {
          "type": "string"
        },
        "accepts": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "scheme",
              "network",
              "maxAmountRequired",
              "resource",
              "description",
              "mimeType",
              "payTo",
              "asset",
              "extra"
            ],
            "properties": {
              "scheme": {
                "type": "string",
                "const": "exact"
              },
              "network": {
                "type": "string"
              },
              "maxAmountRequired": {
                "type": "string"
              },
              "resource": {
                "type": "string",
                "format": "uri"
              },
              "description": {
                "type": "string"
              },
              "mimeType": {
                "type": "string"
              },
              "payTo": {
                "type": "string",
                "description": "EVM address"
              },
              "asset": {
                "type": "string",
                "description": "ERC-20 contract address"
              },
              "maxTimeoutSeconds": {
                "type": "integer"
              },
              "extra": {
                "type": "object"
              }
            }
          }
        },
        "facilitatorUrl": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}