{
  "$id": "https://schema.nfh.global/CatalogPullCallbackAction/v2.0",
  "x-iri": "https://schema.nfh.global/CatalogPullCallbackAction/v2.0",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CatalogPullCallbackAction",
  "type": "object",
  "description": "The real-world act by which the CS (Cataloging Service) delivers the results of a previously accepted /catalog/pull request to the subscriber's (DS) /catalog/on_pull callback endpoint.\n\nThis schema appears in the Catalog Pull phase. The CS produces it as the message payload of the async callback; the subscriber (DS) consumes it to retrieve the requested catalog data.\n\nFabric context: Produced by the CS after processing the pull request. When the result is small it is returned inline in `catalogs`; when the result is too large to return inline the callback carries a `downloadManifest` for downloading the result.\n\nRelationship: Composed as the message payload of the /catalog/on_pull callback. The DS MUST use context.messageId to correlate this callback with the originating /catalog/pull request.",
  "additionalProperties": false,
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "COMPLETED",
        "FAILED"
      ],
      "description": "Status of the pull request result assigned by the CS. COMPLETED — the CS successfully assembled the catalog result; the DS MUST process either catalogs[] or downloadManifest. FAILED — the CS could not assemble the result; the DS MUST read the error field and MUST NOT attempt to process catalogs or downloadManifest."
    },
    "catalogs": {
      "type": "array",
      "description": "Requested catalogs inline. Present when status is COMPLETED.",
      "items": {
        "$ref": "https://schema.nfh.global/Catalog/v2.2/schema.json"
      }
    },
    "downloadManifest": {
      "type": "object",
      "description": "Metadata required to download, verify, and decode the catalog result payload from object storage. Present when status is COMPLETED and the result is too large to return inline in catalogs[]. Mutually exclusive with catalogs[] — exactly one MUST be present when status is COMPLETED. The CN MUST download the object at url, verify the checksum before processing, and MUST NOT process the content if verification fails.",
      "additionalProperties": false,
      "required": [
        "url",
        "format",
        "sizeBytes",
        "checksum",
        "expiresAt"
      ],
      "properties": {
        "url": {
          "type": "string",
          "description": "Pre-signed object-store URL from which the catalog payload can be downloaded. The DS MUST NOT attempt to download after expiresAt."
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp after which url is no longer valid. The DS MUST NOT attempt to download after this time; if expired, the DS MUST re-issue POST /catalog/pull."
        },
        "format": {
          "type": "string",
          "enum": [
            "json",
            "json.gz"
          ],
          "description": "Encoding format of the downloaded payload. The CN MUST decompress json.gz before parsing."
        },
        "sizeBytes": {
          "type": "integer",
          "minimum": 0,
          "description": "Size of the payload in bytes after any compression. The DS MAY use this to validate download completeness."
        },
        "checksum": {
          "type": "string",
          "description": "SHA-256 hex digest of the payload at url, prefixed with sha256:. The DS MUST verify this against the downloaded content before processing. If verification fails, the DS MUST discard the content and treat the pull as failed."
        }
      }
    },
    "pagination": {
      "$ref": "https://schema.nfh.global/Pagination/v2.0/schema.json"
    },
    "error": {
      "description": "Present when status is FAILED.",
      "$ref": "https://schema.nfh.global/Error/v2.0/schema.json"
    }
  }
}