action namsor_diaspora {
  label: "[USES 20 UNITS PER NAME] Infer the likely ethnicity/diaspora of a personal name, given a country of residence ISO2 code (ex. US, CA, AU, NZ etc.)"
  provider: namsor
  method: GET
  path: "/api2/json/diaspora/{countryIso2}/{firstName}/{lastName}"
  encoding: json
  input: {
    type: "object"
    properties: {
      countryIso2: {
        type: "string"
      }
      firstName: {
        type: "string"
      }
      lastName: {
        type: "string"
      }
    }
    required: ["countryIso2", "firstName", "lastName"]
    additionalProperties: false
  }
  output: {
    type: "object"
    description: "Represents the output of inferring the LIKELY ethnicity from a personal name, given an country of residence."
    properties: {
      countryIso2: {
        type: "string"
        description: "From input data, the countryIso2 of geographic context (US,CA etc.)"
      }
      ethnicitiesTop: {
        type: "array"
        description: "List most likely ethnicities (top 10)"
        items: {
          type: "string"
          description: "List most likely ethnicities (top 10)"
        }
      }
      ethnicity: {
        type: "string"
        description: "The most likely ethnicity"
      }
      ethnicityAlt: {
        type: "string"
        description: "The second best alternative ethnicity"
      }
      firstName: {
        type: "string"
        description: "The first name (also known as given name)"
      }
      id: {
        type: "string"
      }
      lastName: {
        type: "string"
        description: "The last name (also known as family name, or surname)"
      }
      lifted: {
        type: "boolean"
        description: "Indicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule. Let us know if you believe ethnicity is incorrect on a specific case where lifted is true."
      }
      probabilityAltCalibrated: {
        type: "number"
        format: "double"
        description: "The calibrated probability for ethnicity OR ethnicityAlt to have been guessed correctly. -1 = still calibrating. "
      }
      probabilityCalibrated: {
        type: "number"
        format: "double"
        description: "The calibrated probability for ethnicity to have been guessed correctly. -1 = still calibrating. "
      }
      score: {
        type: "number"
        format: "double"
        description: "Compatibility to NamSor_v1 Diaspora score value. Higher score is better, but score is not normalized. Use calibratedProbability if available. "
      }
      script: {
        type: "string"
      }
    }
  }
}