{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/instasent/json-schema/instasent-readiness-report-schema.json",
  "title": "ReadinessReport",
  "description": "Live readiness report for a project (home) or a channel. Always\nrecomputed; never cached as \"done\".\n",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/instasent-readiness-api-openapi.yml#/components/schemas/ReadinessReport",
  "type": "object",
  "properties": {
    "scope": {
      "type": "string",
      "enum": [
        "project",
        "channel"
      ]
    },
    "projectType": {
      "type": "string",
      "enum": [
        "standard",
        "api_sms"
      ]
    },
    "channel": {
      "type": [
        "string",
        "null"
      ],
      "description": "The channel for a channel-scoped report; null for the project home."
    },
    "percent": {
      "type": "integer",
      "description": "Completion percentage (0-100); 100 when there are no steps."
    },
    "operational": {
      "type": "boolean",
      "description": "True when no incomplete blocker steps remain."
    },
    "steps": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ReadinessStep"
      }
    },
    "warnings": {
      "type": "array",
      "description": "Always empty for the project (home) scope.",
      "items": {
        "$ref": "#/$defs/ReadinessWarning"
      }
    },
    "reach": {
      "description": "Channel send reach — the countries you can send to right\nnow, with a per-sender breakdown. Present on channel-scoped\nreports; null for the project (home) scope.\n",
      "allOf": [
        {
          "$ref": "#/$defs/ReadinessReach"
        }
      ]
    },
    "computedAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the backend computed this report (UTC ISO-8601).\nThere is no cache behind it, so at the moment of the\nresponse it is always \"now\". It travels because the CLIENT\nmay hold it: anything that fetches once and reuses the\nanswer later needs to know how old what it holds is.\n"
    }
  },
  "required": [
    "scope",
    "projectType",
    "channel",
    "percent",
    "operational",
    "steps",
    "warnings",
    "reach",
    "computedAt"
  ],
  "additionalProperties": false,
  "$defs": {
    "ReadinessReach": {
      "type": "object",
      "description": "The countries the channel can send to right now (\"countries you\ncan send to\"): the union plus the per-sender breakdown. Regulation-\naware (register effective status): a country is reachable unless a\nregistration is required/pending, an enforced regulation gates it,\nor the register is rejected/revoked. SMS is default-allow over the\noperator catalog (same set as the SMS sender `acceptedCountries`);\nRCS is register-driven and may be stricter than the RCS sender\n`acceptedCountries`, which is carrier-only.\n",
      "properties": {
        "reachableCountries": {
          "type": "array",
          "description": "Union of reachable countries across the channel's active\nsenders (ISO 3166-1 alpha-2), deduplicated and sorted.\n",
          "items": {
            "type": "string"
          }
        },
        "senders": {
          "type": "object",
          "description": "Per-sender breakdown keyed by sender alias (SMS `from`,\nRCS agent name). Senders that reach no country are omitted.\n\nNormalize on read:\ntreat `[]` and `{}` as the same empty map, and never call\nmap-only or list-only operations on it unguarded.\n",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "senderCount": {
          "type": "integer",
          "description": "How many ACTIVE senders the channel has, including those\nthat reach no country. NOT the size of `senders`: an RCS\nagent with no accepted register counts here and is absent\nthere, which is exactly the case worth telling apart.\n"
        },
        "defaultSender": {
          "type": [
            "string",
            "null"
          ],
          "description": "The project default sender's alias, when it is one of the\nactive senders. It matters because a send that names no\nsender uses it, so the union above can promise more than a\nsingle send would actually reach.\n\nAlways null on `api_sms` projects even when the field is\nset: nothing there picks it, so naming it would promise\nthe reach of a sender no request uses.\n"
        }
      },
      "required": [
        "reachableCountries",
        "senders",
        "senderCount",
        "defaultSender"
      ],
      "additionalProperties": false
    },
    "ReadinessRecommendationRow": {
      "type": "object",
      "description": "A register that does NOT exist and should. Rows of\n`recommended-registrations`.\n\nThe mirror image of the register rows that moved to the attention\nendpoint: there is no\n`effectiveStatus` because there is no register. The informative\nfield is `source`, which says why the country is recommended.\nA country already covered by a non-archived register on that\nsender never appears here, whatever its status.\n",
      "properties": {
        "channel": {
          "type": "string",
          "enum": [
            "sms",
            "rcs"
          ]
        },
        "senderId": {
          "type": "string"
        },
        "senderName": {
          "type": "string"
        },
        "country": {
          "type": "string",
          "description": "ISO 3166-1 alpha-2 country code."
        },
        "source": {
          "type": "string",
          "enum": [
            "regulation",
            "audience",
            "org"
          ],
          "description": "Why it is recommended. `regulation` rows are emitted per\nactive sender (regulators register senders, not projects);\n`audience` and `org` rows are emitted once, against the\nsender a send would actually use.\n"
        },
        "urgency": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "urgent",
            "upcoming",
            "far",
            null
          ],
          "description": "How close the regulator's deadline is. Null unless `source` is `regulation`."
        },
        "audienceCount": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Reachable contacts in that country. Null unless `source` is `audience`."
        },
        "audienceShare": {
          "type": [
            "number",
            "null"
          ],
          "format": "float",
          "minimum": 0,
          "maximum": 1,
          "description": "`audienceCount` over the project's contacts with a mobile phone,\nbetween 0 and 1 and unrounded. The same base the audience\nthreshold is measured against. Null unless `source` is `audience`.\n"
        },
        "reason": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "sender-substituted",
            null
          ],
          "description": "`sender-substituted` when the country IS reachable for this\nsender, but only with a sender substituted on delivery, so the\nrecipient may see a different sender. The row stays, and stays\nurgent: that delivery is a last resort, to be fixed by\nregistering. Null otherwise.\n"
        }
      },
      "required": [
        "channel",
        "senderId",
        "senderName",
        "country",
        "source",
        "urgency",
        "audienceCount",
        "audienceShare",
        "reason"
      ],
      "additionalProperties": false
    },
    "ReadinessRecommendationWarning": {
      "type": "object",
      "description": "Countries a sender should be registered for and is not. The only\nwarning the user can act on directly, so it comes first in the\narray.\n\nAudience-sourced rows are omitted when the audience's country\ndistribution is unavailable: the project has no audience, or it\ncould not be obtained at that moment. The distribution is refreshed\nat most every six hours, so a recent import can take that long to\nshow here. Regulation and org rows are always present when they\napply, so an empty audience contribution is silent, never an error.\n",
      "properties": {
        "key": {
          "type": "string",
          "enum": [
            "recommended-registrations"
          ]
        },
        "severity": {
          "type": "string",
          "enum": [
            "error"
          ]
        },
        "count": {
          "type": "integer",
          "description": "Total recommendations. May exceed `rows` length, which is capped at 8."
        },
        "rows": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ReadinessRecommendationRow"
          }
        }
      },
      "required": [
        "key",
        "severity",
        "count",
        "rows"
      ],
      "additionalProperties": false
    },
    "ReadinessStep": {
      "type": "object",
      "description": "A single onboarding milestone (\"what's left\").",
      "properties": {
        "key": {
          "type": "string",
          "description": "Stable identifier of the step (no copy; the client owns i18n)."
        },
        "completed": {
          "type": "boolean"
        },
        "isBlocker": {
          "type": "boolean",
          "description": "When true, the project/channel cannot operate until this step is completed."
        },
        "disabled": {
          "type": "boolean",
          "description": "When true, a prerequisite is not yet met, so the user cannot act on it yet."
        },
        "skipped": {
          "type": "boolean",
          "description": "Whether the user hid this step from the dashboard checklist.\nA PREFERENCE, not a fact: the backend reports it and honors\nnone of it, so `completed`, `isBlocker`, `disabled`, `percent`\nand `operational` are all computed as if it were false. Each\nclient decides what to do with it.\n"
        },
        "skippable": {
          "type": "boolean",
          "description": "Whether a user may hide this step at all. True for every step\ntoday; it exists so the day one becomes mandatory, the decision is\ndeclared once here and every surface obeys it.\n\n⚠ It outranks a stored skip: on a step that is not skippable,\n`skipped` is always false even if a preference was saved before it\nstopped being skippable. Nothing ever says \"you hid this\" about\nsomething that can no longer be hidden, and nobody has to clean up\nthe old attributes.\n"
        }
      },
      "required": [
        "key",
        "completed",
        "isBlocker",
        "disabled",
        "skipped",
        "skippable"
      ],
      "additionalProperties": false
    },
    "ReadinessWarning": {
      "description": "A signal the user cannot simply complete. ONE warning exists:\n`recommended-registrations`.\n\n`pending-review` and `rejected-registration` used to be the other\ntwo and MOVED to `GET /project/{project}/attention` on 2026-09-05,\nkeeping their key names: a carrier or regulator acting on a\nregister that was submitted is an event, not a configuration gap.\n\nIt stays a union discriminated by `key`, with one member. Narrow\non the key and `rows` narrows with it; the next warning to arrive\ninherits that instead of adding nullable fields to this one.\n",
      "oneOf": [
        {
          "$ref": "#/$defs/ReadinessRecommendationWarning"
        }
      ]
    }
  }
}