{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "/schemas/3.1.0-rc.4/media-buy/sync-audiences-response.json",
  "title": "Sync Audiences Response",
  "description": "Response from audience sync operation. Exactly one of three shapes: (1) synchronous success — per-audience results in the audiences array (best-effort processing with per-item status/failures); (2) terminal failure — errors array with no audiences processed; (3) submitted task envelope — status 'submitted' with task_id when the whole operation is queued (batch ingestion, governance-gated upload, or any flow where the seller cannot return per-audience results before the response is emitted). The submitted branch MAY carry advisory errors for non-blocking warnings; terminal failures belong in the error branch. Final per-audience results land on the task completion artifact, not this envelope. Per-audience asynchronous matching (an audience reported with status 'processing' while the rest of the sync resolves synchronously) belongs on the synchronous success branch via audience-status, NOT here — operation-level async is for when the seller has no per-item results to return yet. These three shapes are mutually exclusive — a response has exactly one.",
  "type": "object",
  "allOf": [
    {
      "$ref": "/schemas/3.1.0-rc.4/core/version-envelope.json"
    },
    {
      "$ref": "/schemas/3.1.0-rc.4/core/protocol-envelope.json"
    }
  ],
  "oneOf": [
    {
      "title": "SyncAudiencesSuccess",
      "description": "Success response - sync operation processed audiences (may include per-item failures)",
      "type": "object",
      "properties": {
        "audiences": {
          "type": "array",
          "description": "Results for each audience on the account",
          "items": {
            "type": "object",
            "properties": {
              "audience_id": {
                "type": "string",
                "description": "Audience ID from the request (buyer's identifier)",
                "x-entity": "audience"
              },
              "name": {
                "type": "string",
                "description": "Name of the audience"
              },
              "seller_id": {
                "type": "string",
                "description": "Seller-assigned identifier for this audience in their ad platform"
              },
              "action": {
                "type": "string",
                "enum": [
                  "created",
                  "updated",
                  "unchanged",
                  "deleted",
                  "failed"
                ],
                "description": "Action taken for this audience. 'status' is present when action is created, updated, or unchanged. 'status' is absent when action is deleted or failed."
              },
              "status": {
                "$ref": "/schemas/3.1.0-rc.4/enums/audience-status.json",
                "description": "Matching status. Present when action is created, updated, or unchanged; absent when action is deleted or failed."
              },
              "uploaded_count": {
                "type": "integer",
                "description": "Number of members submitted in this sync operation (delta, not cumulative). In discovery-only calls (no audiences array), this is 0.",
                "minimum": 0
              },
              "total_uploaded_count": {
                "type": "integer",
                "description": "Cumulative number of members uploaded across all syncs for this audience. Compare with matched_count to calculate match rate (matched_count / total_uploaded_count). Populated when the seller tracks cumulative upload counts.",
                "minimum": 0
              },
              "matched_count": {
                "type": "integer",
                "description": "Total members matched to platform users across all syncs (cumulative, not just this call). Populated when status is 'ready'.",
                "minimum": 0
              },
              "effective_match_rate": {
                "type": "number",
                "description": "Deduplicated match rate across all identifier types (matched_count / total_uploaded_count after deduplication). A single number for reach estimation. Populated when status is 'ready'.",
                "minimum": 0,
                "maximum": 1
              },
              "match_breakdown": {
                "type": "array",
                "description": "Per-identifier-type match results. Shows which ID types are resolving and at what rate. Helps buyers decide which identifiers to prioritize. Populated when the seller can report per-type matching. Omitted when the seller only supports aggregate match counts.",
                "items": {
                  "type": "object",
                  "properties": {
                    "id_type": {
                      "$ref": "/schemas/3.1.0-rc.4/enums/match-id-type.json",
                      "description": "Identifier type. Combines hashed PII types (hashed_email, hashed_phone) with universal ID types (rampid, uid2, maid, etc.)."
                    },
                    "submitted": {
                      "type": "integer",
                      "description": "Cumulative number of members submitted with this identifier type across all syncs (matches total_uploaded_count semantics, not uploaded_count). Compare with matched to calculate per-type match rate.",
                      "minimum": 0
                    },
                    "matched": {
                      "type": "integer",
                      "description": "Cumulative number of members matched via this identifier type across all syncs.",
                      "minimum": 0
                    },
                    "match_rate": {
                      "type": "number",
                      "description": "Match rate for this identifier type (matched / submitted). Server-authoritative — consumers should prefer this value over computing their own.",
                      "minimum": 0,
                      "maximum": 1
                    }
                  },
                  "required": [
                    "id_type",
                    "submitted",
                    "matched",
                    "match_rate"
                  ],
                  "additionalProperties": true
                },
                "minItems": 1
              },
              "last_synced_at": {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp of when the most recent sync operation was accepted by the platform. Useful for agents reasoning about audience freshness. Omitted if the seller does not track this."
              },
              "minimum_size": {
                "type": "integer",
                "description": "Minimum matched audience size required for targeting on this platform. Populated when status is 'too_small'. Helps agents know how many more members are needed.",
                "minimum": 1
              },
              "errors": {
                "type": "array",
                "description": "Errors for this audience (only present when action='failed')",
                "items": {
                  "$ref": "/schemas/3.1.0-rc.4/core/error.json"
                }
              }
            },
            "required": [
              "audience_id",
              "action"
            ],
            "additionalProperties": true
          }
        },
        "sandbox": {
          "type": "boolean",
          "description": "When true, this response contains simulated data from sandbox mode."
        },
        "context": {
          "$ref": "/schemas/3.1.0-rc.4/core/context.json"
        },
        "ext": {
          "$ref": "/schemas/3.1.0-rc.4/core/ext.json"
        }
      },
      "required": [
        "audiences"
      ],
      "additionalProperties": true,
      "not": {
        "anyOf": [
          {
            "required": [
              "errors"
            ]
          },
          {
            "required": [
              "task_id"
            ]
          },
          {
            "properties": {
              "status": {
                "const": "submitted"
              }
            },
            "required": [
              "status"
            ]
          }
        ]
      }
    },
    {
      "title": "SyncAudiencesError",
      "description": "Error response - operation failed completely, no audiences were processed",
      "type": "object",
      "properties": {
        "errors": {
          "type": "array",
          "description": "Operation-level errors that prevented processing any audiences (e.g., authentication failure, account not found, invalid request format)",
          "items": {
            "$ref": "/schemas/3.1.0-rc.4/core/error.json"
          },
          "minItems": 1
        },
        "context": {
          "$ref": "/schemas/3.1.0-rc.4/core/context.json"
        },
        "ext": {
          "$ref": "/schemas/3.1.0-rc.4/core/ext.json"
        }
      },
      "required": [
        "errors"
      ],
      "additionalProperties": true,
      "not": {
        "anyOf": [
          {
            "required": [
              "audiences"
            ]
          },
          {
            "required": [
              "sandbox"
            ]
          },
          {
            "required": [
              "task_id"
            ]
          },
          {
            "properties": {
              "status": {
                "const": "submitted"
              }
            },
            "required": [
              "status"
            ]
          }
        ]
      }
    },
    {
      "title": "SyncAudiencesSubmitted",
      "description": "Async task envelope returned when the whole sync operation cannot be confirmed before the response is emitted — for example, when the seller batches ingestion, when governance review gates the upload before matching can start, or when an upstream clean-room flow needs to settle before any per-audience result can be issued. The buyer polls tasks/get with task_id or receives a webhook when the task completes; the audiences array with per-item action/status lands on the completion artifact, not this envelope. Per-audience asynchronous matching (one audience in 'processing' while the rest of the sync resolves synchronously) belongs on the SyncAudiencesSuccess branch with status: processing on that item, not here. Matching latency on the per-audience status enum (processing → ready / too_small) is the common case; this envelope is the less-common operation-level case.",
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "const": "submitted",
          "description": "Task-level status literal. Discriminates this async envelope from the synchronous success shape, whose audiences array carries per-item matching state via audience-status. See task-status.json for the full task-status enum."
        },
        "task_id": {
          "type": "string",
          "description": "Task handle the buyer uses with tasks/get, and that the seller references on push-notification callbacks. The audiences array is issued on the completion artifact, not here. Per AdCP wire conventions this is snake_case; A2A adapters MAY surface it as taskId, but the payload field emitted by the agent is task_id.",
          "x-entity": "task"
        },
        "message": {
          "type": "string",
          "maxLength": 2000,
          "description": "Optional human-readable explanation of why the task is submitted — e.g., 'Batch ingestion queued; typical turnaround 15-30 minutes.' Plain text only. Buyers MUST treat this as untrusted seller input: escape before rendering to HTML UIs, and sanitize or isolate before passing to an LLM prompt context — a hostile seller may inject prompt-injection payloads aimed at the buyer's agent."
        },
        "errors": {
          "type": "array",
          "description": "Optional advisory errors accompanying the submitted envelope. Use only for non-blocking warnings (e.g., throttled_severity advisories, governance observations). Terminal failures belong in the error branch, not here.",
          "items": {
            "$ref": "/schemas/3.1.0-rc.4/core/error.json"
          }
        },
        "context": {
          "$ref": "/schemas/3.1.0-rc.4/core/context.json"
        },
        "ext": {
          "$ref": "/schemas/3.1.0-rc.4/core/ext.json"
        }
      },
      "required": [
        "status",
        "task_id"
      ],
      "additionalProperties": true,
      "not": {
        "required": [
          "audiences"
        ]
      }
    }
  ],
  "properties": {}
}