extend type Query {
  """
  Get a list of errors and suggested properly formatted addresses for an address. If no address
  validation service is active for the shop, this will return as if the address is valid even
  though no check actually occurred.
  """
  addressValidation(
    "Address to validate"
    address: AddressInput!,

    "Shop to use for determining what validation service to use"
    shopId: ID!
  ): AddressValidationResults!

  "Get a full list of all registered address validation services"
  addressValidationServices: [AddressValidationService]!
}

"A single registered address validation service"
type AddressValidationService {
  "Human-readable name to show operators"
  displayName: String!

  "Unique name to serve as a key identifying this service"
  name: String!

  "An optional list of all country codes that this address service supports. Null means all countries."
  supportedCountryCodes: [String]
}

"Details about an error that was the result of validating an address that is invalid"
type AddressValidationError {
  "A longer, detailed error message suitable for showing in the user interface"
  details: String

  "An identifier of the source of this error. These are not currently standardized. As long as your client understands it, any string is fine."
  source: String

  "A short error message suitable for showing in the user interface"
  summary: String!

  "The error type. These are not currently standardized. As long as your client understands it, any string is fine."
  type: String!
}

"An address suggestion returned from an address validation service"
type SuggestedAddress {
  "The street address / first line"
  address1: String!

  "Optional second line"
  address2: String

  "City"
  city: String!

  "Country"
  country: String!

  "Postal code"
  postal: String!

  "Region. For example, a U.S. state"
  region: String!
}

"The response from `Query.addressValidation`"
type AddressValidationResults {
  """
  A list of suggested addresses. If the address is valid as is OR the address input is invalid OR
  the shop is not configured to validate addresses, then this will be empty.
  """
  suggestedAddresses: [SuggestedAddress]!

  """
  This may have information about the ways in which the provided address input is incomplete or invalid.
  Show these errors in the address review user interface.
  """
  validationErrors: [AddressValidationError]!
}
