{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/maplespike-ca/json-schema/maplespike-ca-claim-hash-response-schema.json",
  "title": "ClaimHashResponse",
  "x-generated": "2026-11-17",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/maplespike-ca-openapi.json#/components/schemas/ClaimHashResponse",
  "allOf": [
    {
      "$ref": "#/$defs/QuillResponse"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "$ref": "#/$defs/ClaimHashData"
        }
      }
    }
  ],
  "$defs": {
    "ApiError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "message_fr": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {}
        }
      }
    },
    "CitationMeta": {
      "type": "object",
      "properties": {
        "source_name": {
          "type": "string"
        },
        "source_url": {
          "type": "string"
        },
        "retrieved_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Source acquisition time only when observed."
        },
        "data_hash": {
          "type": "string",
          "description": "For claim records, SHA-256 of canonical Quill record JSON, not upstream response bytes."
        },
        "license": {
          "type": "string",
          "description": "Publisher metadata or a notice to consult source terms; not a reuse grant."
        },
        "license_url": {
          "type": "string"
        },
        "license_basis": {
          "type": "string",
          "enum": [
            "publisher-metadata",
            "source-configuration",
            "no-publisher-declaration"
          ]
        },
        "attribution_text": {
          "type": "string"
        },
        "update_frequency": {
          "type": "string"
        },
        "original_format": {
          "type": "string"
        },
        "citation_text": {
          "type": "string"
        },
        "citation_footnote": {
          "type": "string"
        },
        "provenance_evidence": {
          "anyOf": [
            {
              "$ref": "#/$defs/ProvenanceEvidence"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "ClaimHashData": {
      "type": "object",
      "properties": {
        "verified": {
          "type": "boolean",
          "description": "True only when an optional claimed hash matches the recomputed canonical JSON hash."
        },
        "recomputed_sha256": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "matches_claimed": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "verify_command": {
          "type": "string"
        }
      }
    },
    "ProvenanceEvidence": {
      "type": "object",
      "description": "Evidence inventory only; it does not establish source identity, completeness, or reuse rights.",
      "required": [
        "schema_version",
        "record_integrity",
        "acquisition",
        "transformations",
        "publisher_terms"
      ],
      "properties": {
        "schema_version": {
          "const": "quill.provenance.v1"
        },
        "record_integrity": {
          "type": "object",
          "properties": {
            "algorithm": {
              "const": "SHA-256"
            },
            "digest": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            "scope": {
              "const": "canonical-json-record"
            },
            "canonicalization": {
              "const": "quill-canonical-json-v1"
            }
          }
        },
        "acquisition": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "captured",
                "not-captured"
              ]
            },
            "association": {
              "type": "string",
              "enum": [
                "url-matched-not-content-verified",
                "not-established",
                "none"
              ]
            },
            "artifacts": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "association": {
                    "type": "string",
                    "enum": [
                      "url-matched-not-content-verified",
                      "not-established"
                    ]
                  },
                  "evidence_source": {
                    "type": "string",
                    "enum": [
                      "explicit-record-evidence",
                      "shared-http-client-capture"
                    ]
                  },
                  "url": {
                    "type": "string"
                  },
                  "retrieved_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "sha256": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                  },
                  "hash_scope": {
                    "const": "http-client-response-body-utf8"
                  },
                  "status_code": {
                    "type": "integer"
                  },
                  "media_type": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "byte_length": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "etag": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "last_modified": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "url_redacted": {
                    "type": "boolean"
                  },
                  "body_capture": {
                    "type": "string",
                    "enum": [
                      "complete-http-client-body",
                      "empty-body-not-captured"
                    ]
                  }
                }
              }
            }
          }
        },
        "transformations": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "pipeline-reported",
                "not-recorded"
              ]
            },
            "coverage": {
              "const": "declared-steps-only"
            },
            "steps": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "stages": {
              "type": "object",
              "properties": {
                "module_code_revision": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "parser_version": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "transform_code_revision": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          }
        },
        "publisher_terms": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "publisher-metadata-observed",
                "source-configuration-only",
                "not-observed"
              ]
            },
            "label": {
              "type": [
                "string",
                "null"
              ]
            },
            "url": {
              "type": [
                "string",
                "null"
              ]
            },
            "observed_fields": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "QualityMeta": {
      "type": "object",
      "properties": {
        "freshness_seconds": {
          "type": "number"
        },
        "source_uptime_7d": {
          "type": "number"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low"
          ]
        },
        "certainty_score": {
          "type": "number"
        },
        "last_verified": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "data_completeness": {
          "type": "string"
        }
      }
    },
    "QuillResponse": {
      "type": "object",
      "description": "Common API envelope. Payload and citation fields vary by route and source.",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "data": {
          "description": "Route-specific payload; shape varies by endpoint."
        },
        "text": {
          "type": [
            "string",
            "null"
          ]
        },
        "error": {
          "anyOf": [
            {
              "$ref": "#/$defs/ApiError"
            },
            {
              "type": "null"
            }
          ]
        },
        "meta": {
          "$ref": "#/$defs/ResponseMeta"
        },
        "quality": {
          "anyOf": [
            {
              "$ref": "#/$defs/QualityMeta"
            },
            {
              "type": "null"
            }
          ]
        },
        "citation": {
          "anyOf": [
            {
              "$ref": "#/$defs/CitationMeta"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "ResponseMeta": {
      "type": "object",
      "properties": {
        "requestId": {
          "type": "string"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "API response timestamp, not source retrieval time."
        },
        "version": {
          "type": "string"
        },
        "usage": {
          "type": "object",
          "properties": {
            "periodCalls": {
              "type": "integer"
            },
            "periodLimit": {
              "type": "integer"
            },
            "tier": {
              "type": "string"
            }
          }
        },
        "agent": {
          "type": "string"
        },
        "action": {
          "type": "string"
        },
        "authMethod": {
          "type": "string"
        },
        "creditsCharged": {
          "type": "number"
        },
        "cacheStatus": {
          "type": "string",
          "enum": [
            "hit",
            "miss",
            "mock"
          ]
        },
        "durationMs": {
          "type": "number"
        }
      }
    }
  }
}