Change of Address Subscription Event

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-coa-notification-event-schema.json",
  "title": "Change of Address Subscription Event",
  "description": "Change of Address Notification Event",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-subscriptions-ncoa-openapi.yml#/components/schemas/CoaNotificationEvent",
  "type": "object",
  "required": [
    "subscriptionId",
    "subscriptionType",
    "timestamp",
    "payload"
  ],
  "properties": {
    "subscriptionId": {
      "type": "string",
      "description": "Unique identifier created for this Subscription.",
      "pattern": "^[A-Za-z0-9\\-]+$"
    },
    "subscriptionType": {
      "type": "string",
      "description": "The name of the topic related to this event.",
      "pattern": "^[A-Za-z0-9\\s]+$"
    },
    "timestamp": {
      "type": "string",
      "description": "Timestamp message was generated, in ISO-8601 format.",
      "format": "date-time"
    },
    "payload": {
      "type": "string",
      "description": "Change of Address subscription details converted into a JSON formatted string.",
      "pattern": "^[\\s\\S]*$"
    },
    "payloadDetails": {
      "$ref": "#/$defs/ChangeOfAddressSubscriptionNotification"
    },
    "links": {
      "title": "Hypermedia Links",
      "type": "array",
      "description": "Hypermedia links to related resources.",
      "minItems": 0,
      "maxItems": 20,
      "items": {
        "required": [
          "href",
          "rel"
        ],
        "type": "object",
        "properties": {
          "rel": {
            "type": "array",
            "description": "The short name(s) of the relationship corresponding to the link.",
            "minItems": 0,
            "maxItems": 20,
            "items": {
              "type": "string"
            }
          },
          "title": {
            "type": "string",
            "description": "A human-readable description of the link relationship.",
            "pattern": "^[A-Za-z\\-]+$"
          },
          "href": {
            "type": "string",
            "description": "The URL to a related resource.",
            "format": "uri"
          },
          "method": {
            "type": "string",
            "description": "The HTTP method to use to access this link.",
            "enum": [
              "GET",
              "POST",
              "PUT",
              "DELETE"
            ]
          },
          "submissionMediaType": {
            "type": "string",
            "description": "The media type of the resource request.",
            "minLength": 0,
            "maxLength": 50,
            "pattern": "^[A-Za-z0-9\\-]+$"
          },
          "targetMediaType": {
            "type": "string",
            "description": "The media type of the resource response.",
            "minLength": 0,
            "maxLength": 50,
            "pattern": "^[A-Za-z0-9\\-]+$"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": true,
  "$defs": {
    "Address": {
      "title": "Address",
      "type": "object",
      "properties": {
        "streetAddress": {
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "pattern": "^\\s*[A-Za-z0-9,.][A-Za-z0-9\\s,.]*$",
          "description": "The number of a building along with the name of the road or street on which it is located."
        },
        "streetAddressAbbreviation": {
          "maxLength": 50,
          "minLength": 0,
          "type": "string",
          "pattern": "^[A-Za-z0-9\\s,.]+$",
          "description": "This is the abbreviation of the primary street address line for the address.",
          "readOnly": true
        },
        "secondaryAddress": {
          "maxLength": 50,
          "type": "string",
          "pattern": "^[A-Za-z0-9\\s,.]+$",
          "description": "The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.  For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm)."
        }
      },
      "additionalProperties": true,
      "description": "Address fields standard to all locations."
    },
    "ChangeOfAddressSubscriptionNotification": {
      "title": "Change Of Address Subscription Event Information",
      "type": "object",
      "additionalProperties": true,
      "description": "Change Of Address Subscription Event Information",
      "allOf": [
        {
          "$ref": "#/$defs/LastBusinessName"
        },
        {
          "type": "object",
          "properties": {
            "originalAddress": {
              "$ref": "#/$defs/OriginalAddress"
            }
          }
        },
        {
          "type": "object",
          "properties": {
            "newAddress": {
              "$ref": "#/$defs/NewAddress"
            }
          }
        }
      ]
    },
    "DomesticAddress": {
      "title": "Domestic Address",
      "additionalProperties": true,
      "description": "Address fields for US locations",
      "required": [
        "fullName",
        "city",
        "state",
        "ZIPCode",
        "streetAddress"
      ],
      "allOf": [
        {
          "type": "object",
          "properties": {
            "fullName": {
              "maxLength": 66,
              "type": "string",
              "description": "The full name of the addressee.  This can be a person or a business.  If the subscription is for a person, the full name should include the first name, middle initial (if applicable), and last name.  If the subscription is for a business, the full name should be the business name.  The full name should not include any part of the address such as street or city.  It should only include the name of the person or business associated with the address.",
              "pattern": "^\\s*[A-Za-z0-9#./&()+-][A-Za-z0-9\\s#./&()+-]*$"
            },
            "city": {
              "maxLength": 28,
              "minLength": 1,
              "type": "string",
              "pattern": "^\\s*[A-Za-z][A-Za-z\\s]*$",
              "description": "This is the city name of the address."
            },
            "state": {
              "$ref": "#/$defs/State"
            },
            "ZIPCode": {
              "pattern": "\\d{5}",
              "type": "string",
              "description": "This is the 5-digit ZIP code."
            },
            "urbanization": {
              "maxLength": 96,
              "type": "string",
              "pattern": "^[A-Za-z\\s]+$",
              "description": "An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico)."
            }
          },
          "additionalProperties": true
        },
        {
          "$ref": "#/$defs/Address"
        }
      ]
    },
    "LastBusinessName": {
      "title": "Person or Business Name",
      "type": "object",
      "properties": {
        "firstName": {
          "type": "string",
          "description": "First Name.",
          "minLength": 0,
          "maxLength": 40,
          "pattern": "^[A-Za-z\\\\s]+$"
        },
        "middleInital": {
          "type": "string",
          "description": "Middle Initial.",
          "minLength": 0,
          "maxLength": 1,
          "pattern": "^[A-Za-z\\\\s]+$"
        },
        "lastName": {
          "type": "string",
          "description": "Last Name.",
          "minLength": 0,
          "maxLength": 40,
          "pattern": "^[A-Za-z\\\\s]+$"
        },
        "businessName": {
          "type": "string",
          "description": "Business Name.",
          "minLength": 0,
          "maxLength": 66,
          "pattern": "^[\\s\\S]*$"
        }
      },
      "additionalProperties": false,
      "description": "Name or Business Name pertaining to address."
    },
    "NewAddress": {
      "$ref": "#/$defs/DomesticAddress"
    },
    "OriginalAddress": {
      "$ref": "#/$defs/DomesticAddress"
    },
    "State": {
      "title": "State",
      "maxLength": 2,
      "minLength": 2,
      "pattern": "^(AA|AE|AL|AK|AP|AS|AZ|AR|CA|CO|CT|DE|DC|FM|FL|GA|GU|HI|ID|IL|IN|IA|KS|KY|LA|ME|MH|MD|MA|MI|MN|MS|MO|MP|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PW|PA|PR|RI|SC|SD|TN|TX|UT|VT|VI|VA|WA|WV|WI|WY)$",
      "type": "string",
      "description": "The two-character state code."
    }
  }
}