{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://weshipstore.com/schemas/mailbox-directory-v1.schema.json",
  "title": "WeShip Mailbox Directory v1",
  "description": "The mailbox directory of a store: one row per holder of a mailbox, or one row for an available mailbox. The same rules apply to the CSV columns of the same names. This schema describes the shape only: the server enforces more rules than a schema can express (one primary holder per mailbox, one status for every row of a mailbox, unique mailbox numbers and external ids). Only the primary holder's email and phone are stored, or the first holder's when no row is primary.",
  "type": "object",
  "additionalProperties": false,
  "required": ["spec_version", "rows"],
  "properties": {
    "spec_version": {
      "description": "Always 1. A future incompatible change gets a new number and a new schema file.",
      "enum": [1, "1"]
    },
    "rows": {
      "type": "array",
      "minItems": 1,
      "maxItems": 20000,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["mailbox_number", "mailbox_status"],
        "properties": {
          "mailbox_number": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40,
            "description": "The number on the box. Several rows may share one number: one per holder."
          },
          "mailbox_status": {
            "type": "string",
            "enum": ["active", "past_due", "closed", "available"],
            "description": "closed is stored as terminated. Every row of one mailbox must carry the same status."
          },
          "holder_type": {
            "type": ["string", "null"],
            "enum": ["primary", "additional", "business", null],
            "description": "Required unless the mailbox is available, where it must be empty. A mailbox has at most one primary."
          },
          "first_name": { "type": ["string", "null"], "maxLength": 100, "description": "Required for primary and additional holders." },
          "last_name": { "type": ["string", "null"], "maxLength": 100, "description": "Required for primary and additional holders." },
          "company_name": { "type": ["string", "null"], "maxLength": 200, "description": "Required for business holders." },
          "email": { "type": ["string", "null"], "maxLength": 254, "description": "Contact email of the holder. Stored only for the primary (or first) holder of a mailbox." },
          "phone_e164": {
            "type": ["string", "null"],
            "pattern": "^\\+[1-9]\\d{6,14}$",
            "description": "Contact phone in E.164 form, for example +15555550100. Stored only for the primary (or first) holder of a mailbox."
          },
          "renewal_date": {
            "type": ["string", "null"],
            "description": "ISO 8601 date, for example 2027-01-31."
          },
          "size": { "type": ["string", "null"], "maxLength": 40, "description": "Free-text box size, for example Small." },
          "external_id": {
            "type": ["string", "null"],
            "maxLength": 100,
            "description": "Your own stable id for the mailbox. Lets a box keep its identity if its number changes."
          }
        }
      }
    }
  },
  "examples": [
    {
      "spec_version": 1,
      "rows": [
        {
          "mailbox_number": "101",
          "mailbox_status": "active",
          "holder_type": "primary",
          "first_name": "Ada",
          "last_name": "Example",
          "email": "ada@example.test",
          "phone_e164": "+15555550100",
          "renewal_date": "2027-01-31",
          "size": "Small",
          "external_id": "box-101"
        },
        {
          "mailbox_number": "101",
          "mailbox_status": "active",
          "holder_type": "additional",
          "first_name": "Bo",
          "last_name": "Example",
          "renewal_date": "2027-01-31",
          "external_id": "box-101"
        },
        {
          "mailbox_number": "102",
          "mailbox_status": "past_due",
          "holder_type": "business",
          "company_name": "Sample Supply Co",
          "email": "office@example.test",
          "renewal_date": "2026-11-15",
          "size": "Medium"
        },
        {
          "mailbox_number": "103",
          "mailbox_status": "available",
          "size": "Small"
        }
      ]
    }
  ]
}