swagger: '2.0'
info:
  description: >-

    <img height="100" width="100"
    src="/archetypes/v1/img/logo-commonalaxy.png.png" alt="OpenAPI 2.0
    Business Archetypes">

    The `Party` archetype represents an identifiable, addressable entity that
    may have a legal status and that normally has autonomous control over (at
    least some of) its actions.


    ## Standards compliance

    <table>
      <thead>
        <tr><th>Standard</th><th>Contents</th></tr>
      </thead>
      <tfoot>
      </tfoot>
      <tbody>
        <tr>
          <td><a href="http://www.omg.org/spec/PARTY/1.0/PDF">OMG Party Management Facility Specification</a></td>
          <td>A standard that supports party management.</td>
        </tr>
        <tr>
          <td><a href="https://www.iso.org/iso-3166-country-codes.html">ISO 3166</a></td>
          <td>Two- and three-letter country codes and country names.</td>
        </tr>
        <tr>
          <td><a href="https://www.iso.org/standard/36266.html">ISO/IEC 5218:2004</a></td>
          <td>Codes for the representation of human sexes.</td>
        </tr>
        <tr>
          <td><a href="http://www.itu.int/rec/T-REC-E.164/en">ITU-T Recommendations</a></td>
          <td>Telecommunication numbering plan.</td>
        </tr>
      </tbody>
    </table>


    ## Resources


    <table>
      <thead>
        <tr><th>Proposal</th><th>Contents</th></tr>
      </thead>
      <tfoot>
      </tfoot>
      <tbody>
        <tr>
          <td><a href="https://apath.org/63-genders/">63 Genders</a></td>
          <td>A proposal for describing Gender as a combination of Physical, Personality and Preferential groups.</td>
        </tr>
      </tbody>
    </table>


    ---



    ## Business archetypes defined

    "A business archetype is a primordial thing that occurs consistently and
    universally in business domains and business software systems." (Arlow &
    Neustadt, [_Enterprise patterns and MDA: building better software with
    archetype patterns and
    UML_](https://www.amazon.com/Enterprise-Patterns-MDA-Building-Archetype/dp/032111230X),
    2006, p. 5)


    ## Explore other business archetype patterns

    [Open a Swagger-UI](http://api.swindle.net/swagger-ui/#/) instance, then
    copy and paste the following Swagger specification URLs into the "Explore"
    text field and select the "Explore" button for additional APIs.

    1. `Locale`:
    http://api.swindle.net/archetypes/v1/schemas/locales/locales.yaml

    2. `Money`: http://api.swindle.net/archetypes/v1/schemas/money/money.yaml

    3. `Party`:
    http://api.swindle.net/archetypes/v1/schemas/parties/parties.yaml

    4. `Quantity`:
    http://api.swindle.net/archetypes/v1/schemas/quantities/quantities.yaml


    ---

    ## About
  version: 1.0.0
  title: Party
  contact:
    name: Greg Swindle
    url: 'https://github.com/commonality'
  license:
    name: Licensed under the Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: api.swindle.net
basePath: /archetypes/v1/parties
tags:
  - name: Party
    description: 'An identifiable, addressable entity.'
  - name: Person
    description: Represents a human being.
  - name: Preference
    description: >-
      A choice of (or liking for) something, often from a set of possible or
      offered options.
  - name: Organization
    description: An administrative and functional structure.
schemes:
  - http
  - https
externalDocs:
  description: >-
    Enterprise patterns and MDA: building better software with archetype
    patterns and UML
  url: >-
    https://www.amazon.com/Enterprise-Patterns-MDA-Building-Archetype/dp/032111230X
paths:
  /:
    get:
      tags:
        - Party
      summary: Retrieve all Parties.
      description: Retrieve all Parties.
      produces:
        - application/json
      operationId: getParties
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/Party'
  '/{party-identifier}':
    get:
      tags:
        - Party
      summary: Retrieve a specific Party entity.
      description: Retrieve a Party by its unique identifier.
      produces:
        - application/json
      operationId: getPartyByPartyIdentifier
      parameters:
        - in: path
          name: party-identifier
          description: The unique identifier of the Party.
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Party'
  /people/:
    get:
      tags:
        - Person
      summary: Retrieve all People.
      description: Retrieve all People.
      produces:
        - application/json
      operationId: getPeople
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/Person'
  '/people/{party-identifier}':
    get:
      tags:
        - Person
      summary: Retrieve a specific Person entity.
      description: Retrieve a Person by their unique identifier.
      produces:
        - application/json
      operationId: getPersonByPartyIdentifier
      parameters:
        - in: path
          name: party-identifier
          description: The unique identifier associated with a Person.
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Person'
  /preferences/:
    get:
      tags:
        - Preference
      summary: Retrieve all Preferences.
      description: Retrieve all Preferences.
      produces:
        - application/json
      operationId: getPreferences
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/Preference'
  '/preferences/{unique-identifier}':
    get:
      tags:
        - Preference
      summary: Retrieve a specific Preference.
      description: Retrieve a Preference by its unique identifier.
      produces:
        - application/json
      operationId: getPreferenceByUniqueIdentifier
      parameters:
        - in: path
          name: unique-identifier
          description: The unique identifier associated with a Preference.
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Preference'
  /organizations/:
    get:
      tags:
        - Organization
      summary: Retrieve all Organizations.
      description: Retrieve all Organizations.
      produces:
        - application/json
      operationId: getOrganizations
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/Organization'
  '/organizations/{party-identifier}':
    get:
      tags:
        - Organization
      summary: Retrieve a specific Organization.
      description: Retrieve a Organization by its unique identifier.
      produces:
        - application/json
      operationId: getOrganizationByPartyIdentifier
      parameters:
        - in: path
          name: party-identifier
          description: The unique identifier associated with an Organization.
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Organization'
definitions:
  Nominative:
    $ref: 'http://api.swindle.net/archetypes/v1/schemas/parties/nominative.yaml'
  EffectiveDates:
    allOf:
      - $ref: >-
          http://api.swindle.net/archetypes/v1/schemas/date-times/effective-dates.yaml
      - description: >-
          Represents a range of two dates:

          1. The date on which something is considered to take effect, which may
          be a past, present or future date.

          2. The date on which something is considered to expire, which may be a
          past, present or future date.


          EffectiveDates may be different from the dates upon which the event
          occurs or is recorded.


          The validFrom date-times value must be less than or equal to the
          validTo date-times value.
  UniqueIdentifier:
    allOf:
      - title: UniqueIdentifier
      - $ref: >-
          http://api.swindle.net/archetypes/v1/schemas/parties/unique-identifier.yaml
  IsoCountryCode:
    $ref: >-
      http://api.swindle.net/archetypes/v1/schemas/locales/iso-country-code.yaml
  Address:
    allOf:
      - properties:
          addressType:
            default: 'null'
            description: The Address sub-type.
            type: string
            enum:
              - EMAIL_ADDRESS
              - GEOGRAPHIC_ADDRESS
              - TELECOM_ADDRESS
              - URL_ADDRESS
          formatted:
            default: 'null'
            description: The full address formatted for display.
            type: string
          type:
            default: 'null'
            description: 'A string indicating what type of field this is, e.g., "work".'
            type: string
      - $ref: '#/definitions/EffectiveDates'
      - required:
          - addressType
          - formatted
      - description: Represents a location or medium whereby a `Party` can be contacted.
      - title: Address
  AddressProperties:
    description: >-
      Specifies information about an `Address` assigned to a specific `Party`.
      Each time an `Address` is associated with a `Party`, an associated
      `AddressProperties` object MUST be constructed. This object SHOULD at
      least specify the `use` of the `Address` (i.e., limit the context in which
      the the `Address` is applicable). Example `use` values might be "work",
      "home", "emergency contact", etc. `AddressProperties` can also be used to
      designate a preferred address for a `Party`. Other properties can be added
      to `AddressProperties` according to your business requirements.
    type: object
    properties:
      addresses:
        type: array
        items:
          $ref: '#/definitions/Address'
      parties:
        type: array
        items:
          $ref: '#/definitions/Party'
      uses:
        description: Limits the context in which the Address is applicable.
        type: array
        items:
          type: string
          example: []
  EmailAddress:
    allOf:
      - $ref: '#/definitions/Address'
      - title: EmailAddress
      - properties:
          addressType:
            enum:
              - EMAIL_ADDRESS
  GeographicAddress:
    allOf:
      - $ref: '#/definitions/Address'
      - description: Represents a geographic location at which a Party may be contacted.
      - properties:
          addressType:
            enum:
              - GEOGRAPHIC_ADDRESS
          addressLines:
            description: >-
              One or more lines that physically identify a location. The first
              line of an address is often a building name, a building number and
              street, or postal box number; the other address lines are for
              location information that further localizes the physical point of
              contact, e.g., suite or apartment number.
            type: array
            items:
              type: string
          city:
            description: 'The name of a city, town, or locality.'
            type: string
          country:
            $ref: '#/definitions/IsoCountryCode'
          regionOrState:
            description: >-
              The name of a geographical region within a country--in the USA,
              the would be a state; in England, a county; and in Switzerland, a
              canton.
            type: string
          zipOrPostalCode:
            description: A code used to identify a geographic area.
            type: string
      - required:
          - addressLines
          - city
          - regionOrState
          - zipOrPostalCode
      - title: GeographicAddress
  TelecomAddress:
    allOf:
      - $ref: '#/definitions/Address'
      - description: >-
          Represents a number that can contact a telephone, mobile phone, fax,
          pager, or other telephonic device.
      - properties:
          addressType:
            enum:
              - TELECOM_ADDRESS
          areaCode:
            description: The code for an area or city.
            type: string
          countryCode:
            description: The number required to directly dial a particular country.
            type: string
          extension:
            description: An extension accessible via the number.
            type: string
          nationalDirectDialingPrefix:
            description: >-
              The prefix required to make a call within a country between two
              different cities, localities, or areas--generally dropped when
              dialing from outside the country (with some exceptions).
            type: string
          number:
            description: >-
              The "telephone" number, which may be (arbitrarily) formatted into
              one or mnemonic sequences of digits depending on local standards.
            type: string
          physicalType:
            description: The type of device accessed by the TelecomAddress.
            type: string
            enum:
              - phone
              - fax
              - mobile
              - pager
              - sms
      - title: TelecomAddress
  UrlAddress:
    allOf:
      - $ref: '#/definitions/Address'
      - properties:
          addressType:
            enum:
              - URL_ADDRESS
      - description: >-
          The unqiue address of a resource, e.g., Web page, on a computer network.
      - title: UrlAddress
  PreferenceOption:
    allOf:
      - $ref: '#/definitions/Nominative'
      - required:
          - name
      - properties:
          name:
            description: Specifies the name of a possible option and its description.
          description:
            description: >-
              A statement that explains the characteristics of the `PreferenceOption`.
      - title: PreferenceOption
  PreferenceType:
    allOf:
      - $ref: '#/definitions/Nominative'
      - description: >-
          Specifies the name, a description, and a range of PreferenceOptions
          for a Preference.
      - properties:
          description:
            description: >-
              Specifies the name, a description, and a range of
              `PreferenceOptions` for a `Preference`.
            type: string
          name:
            description: The classification name of the Perference range.
            type: string
          options:
            description: A collection of one or more PreferenceOptions.
            type: array
            items:
              $ref: '#/definitions/PreferenceOption'
      - title: PreferenceType
  Preference:
    description: >-
      Represents a Party's expressed choice of (or liking for) something, often
      from a set of possible or offered options.
    type: object
    properties:
      option:
        $ref: '#/definitions/PreferenceOption'
      preferenceWeight:
        type: integer
      type:
        $ref: '#/definitions/PreferenceType'
  RegisteredIdentifier:
    allOf:
      - title: RegisteredIdentifier
      - properties:
          identifier:
            type: string
            description: >-
              A string that signifies a Party. The identifier's value is unique
              in the context of time and the registrationAuthority that assigned
              it.
          registrationAuthority:
            description: >-
              Represents the recognized or statutory body responsible for
              assigning the RegisteredIdentifier and associating it with a
              Party.
            type: string
          type:
            description: A value that classifies the RegisteredIdentifier
            type: string
            enum:
              - VZID
              - ENTERPRISE_ID
              - EMPLID
              - SSN
              - ONE_WORLD
      - $ref: '#/definitions/EffectiveDates'
      - description: >-
          The RegisteredIdentifier represents an identifier for a Party that has
          been assigned by a recognized or statutory body.
      - title: RegisteredIdentifier
  PartyIdentifier:
    allOf:
      - $ref: '#/definitions/UniqueIdentifier'
      - title: PartyIdentifier
  Party:
    type: object
    description: >-
      Represents an identifiable, addressable entity that may have a legal
      status and that normally has autonomous control over (at least some of)
      its actions.
    properties:
      partyIdentifier:
        type: string
        description: An identifier for the Party that is unique within a given context..
      addresses:
        type: array
        items:
          $ref: '#/definitions/Address'
        default: '[]'
        description: An array of the Party's addresses.
      description:
        type: string
        default: 'null'
        description: An optional description of the Party.
      preferences:
        description: A list of Preferences associated with the Party.
        type: array
        items:
          $ref: '#/definitions/Preference'
        default: '[]'
      registeredIds:
        type: array
        items:
          $ref: '#/definitions/RegisteredIdentifier'
        default: '[]'
        description: >-
          An identifier for a Party that has been assigend by a recognized or
          statutory body.
  Ethnicity:
    allOf:
      - $ref: '#/definitions/Nominative'
      - required:
          - name
      - description: >-
          Represents a classification of one or more People according to common
          racial, national, tribal, religious, linguistic, or cultural origin or
          background. Each Person may have zero or more Ethnicities.

          Ethnicities can be used to categorize Preferences by cohorts (and not
          by individual). E.g., Jains are strict vegetarians; Muslims eat meat
          prepared as prescribed by Muslim law.
      - title: Ethnicity
      - required:
          - name
  IsoSex:
    description: >-
      ISO/IEC 5218:2004 specifies a uniform representation of human sexes for
      the interchange of information. It provides a set of numeric codes that
      are independent of language-derived codes and as such is intended to
      provide a common basis for the international exchange of information
      containing human sex data.
    type: object
    properties:
      '0':
        type: string
        description: Not known
        enum:
          - NOTKNOWN
      '1':
        type: integer
        description: Male
        enum:
          - MALE
      '2':
        type: integer
        description: Female
        enum:
          - FEMALE
      '9':
        type: integer
        description: Not specified
        enum:
          - NOTSPECIFIED
      NOTKNOWN:
        type: integer
        description: Not known
        enum:
          - 0
      MALE:
        type: integer
        description: Male
        enum:
          - 1
      FEMALE:
        type: integer
        description: Female
        enum:
          - 2
      NOTSPECIFIED:
        type: integer
        description: Not specified
        enum:
          - 9
  Gender:
    description: >-
      Represents the range of characteristics pertaining to, and differentiating
      between, masculinity and femininity. Depending on the context, these
      characteristics may include biological sex (i.e. the state of being male,
      female or an intersex variation which may complicate sex assignment),
      sex-based social structures (including gender roles and other social
      roles), or gender identity. Some cultures have specific gender roles that
      can be considered distinct from male and female, such as the hijra
      (chhaka) of India and Pakistan.
    type: object
    properties:
      name:
        description: The designated name of the Gender.
        type: string
        enum:
          - Agender
          - Androgyne
          - Androgynes
          - Androgynous
          - Asexual
          - Bigender
          - Cis
          - Cis Female
          - Cis Male
          - Cis Man
          - Cis Woman
          - Cisgender
          - Cisgender Female
          - Cisgender Male
          - Cisgender Man
          - Cisgender Woman
          - F2M
          - FTM
          - Female to Male
          - Female to male trans man
          - Female to male transgender man
          - Female to male transsexual man
          - Gender Fluid
          - Gender Nonconforming
          - Gender Questioning
          - Gender Variant
          - Gender neutral
          - Genderqueer
          - Hermaphrodite
          - Intersex
          - Intersex man
          - Intersex person
          - Intersex woman
          - M2F
          - MTF
          - Male to Female
          - Male to female trans woman
          - Male to female transgender woman
          - Male to female transsexual woman
          - Man
          - Neither
          - Neutrois
          - Non-binary
          - Other
          - Pangender
          - Polygender
          - T* man
          - T* woman
          - Trans
          - Trans Female
          - Trans Male
          - Trans Man
          - Trans Person
          - Trans*Female
          - Trans*Male
          - Trans*Man
          - Trans*Person
          - Trans*Woman
          - Transexual
          - Transexual Female
          - Transexual Male
          - Transexual Man
          - Transexual Person
          - Transexual Woman
          - Transgender Female
          - Transgender Person
          - Transmasculine
          - Two* person
          - Two-spirit
          - Two-spirit person
          - Woman
      description:
        description: A summary or definition of the Gender.
        type: string
        enum:
          - Androgyne Bisexual Androdite
          - Androgyne Bisexual Androfemale
          - Androgyne Bisexual Andromale
          - Androgyne Bisexual Hermaphrofemale
          - Androgyne Bisexual Hermaphromale
          - Androgyne Bisexual Man
          - Androgyne Bisexual Woman
          - Androgyne Female-Attracted Androdite
          - Androgyne Female-Attracted Hermaphrofemale
          - Androgyne Female-Attracted Hermaphromale
          - Androgyne Heterosexual Androfemale
          - Androgyne Heterosexual Andromale
          - Androgyne Heterosexual Man
          - Androgyne Heterosexual Woman
          - Androgyne Homosexual Androfemale
          - Androgyne Homosexual Andromale
          - Androgyne Homosexual Man
          - Androgyne Homosexual Woman
          - Androgyne Male-Attracted Androdite
          - Androgyne Male-Attracted Hermaphrofemale
          - Androgyne Male-Attracted Hermaphromale
          - Feminine Bisexual Androdite
          - Feminine Bisexual Androfemale
          - Feminine Bisexual Andromale
          - Feminine Bisexual Hermaphrofemale
          - Feminine Bisexual Hermaphromale
          - Feminine Bisexual Man
          - Feminine Bisexual Woman
          - Feminine Female-Attracted Androdite
          - Feminine Female-Attracted Hermaphrofemale
          - Feminine Female-Attracted Hermaphromale
          - Feminine Heterosexual Androfemale
          - Feminine Heterosexual Andromale
          - Feminine Heterosexual Man
          - Feminine Heterosexual Woman
          - Feminine Homosexual Androfemale
          - Feminine Homosexual Andromale
          - Feminine Homosexual Man
          - Feminine Homosexual Woman
          - Feminine Male-Attracted Androdite
          - Feminine Male-Attracted Hermaphrofemale
          - Feminine Male-Attracted Hermaphromale
          - Masculine Bisexual Androdite
          - Masculine Bisexual Androfemale
          - Masculine Bisexual Andromale
          - Masculine Bisexual Hermaphrofemale
          - Masculine Bisexual Hermaphromale
          - Masculine Bisexual Man
          - Masculine Bisexual Woman
          - Masculine Female-Attracted Androdite
          - Masculine Female-Attracted Hermaphrofemale
          - Masculine Female-Attracted Hermaphromale
          - Masculine Heterosexual Androfemale
          - Masculine Heterosexual Andromale
          - Masculine Heterosexual Man
          - Masculine Heterosexual Woman
          - Masculine Homosexual Androfemale
          - Masculine Homosexual Andromale
          - Masculine Homosexual Man
          - Masculine Homosexual Woman
          - Masculine Male-Attracted Androdite
          - Masculine Male-Attracted Hermaphrofemale
          - Masculine Male-Attracted Hermaphromale
  PersonName:
    allOf:
      - description: Represents a name for a `Person`.
      - properties:
          familyName:
            description: >-
              The last name in Western countries. This is the only manditory
              component of `PersonName` and the only one used if a `Person` has
              only one name.
            type: string
          givenNames:
            description: The first name in Western countries.
            type: array
            items:
              type: string
              example: []
          middleNames:
            description: Any name other than the given name(s) and the family name(s).
            type: array
            items:
              type: string
              example: []
          preferredName:
            description: A name (or names) that the person is commonly known by.
            type: array
            items:
              type: string
              example: 'null'
          prefixes:
            description: 'An honorific such as Ms., Dr., etc.'
            type: array
            items:
              type: string
              example: []
          suffixes:
            description: >-
              Potentially a generational label (e.g., Jr., III); a
              qualification, (e.g., Ph.D.).
            type: array
            items:
              type: string
              example: []
          uses:
            description: >-
              Zero or more short descriptions of what the name is used for
              (e.g., a stage name or a legal name).
            type: array
            items:
              type: string
              example: []
      - required:
          - familyName
      - $ref: '#/definitions/EffectiveDates'
      - title: PersonName
  Person:
    allOf:
      - $ref: '#/definitions/Party'
      - description: Represents information about a human being.
      - properties:
          dateOfBirth:
            description: The Person's date of birth.
            type: string
            format: date
          ethnicities:
            type: array
            items:
              $ref: '#/definitions/Ethnicity'
          gender:
            $ref: '#/definitions/Gender'
          isoSex:
            $ref: '#/definitions/IsoSex'
          personName:
            $ref: '#/definitions/PersonName'
          otherPersonNames:
            type: array
            items:
              $ref: '#/definitions/PersonName'
      - required:
          - personName
          - gender
          - isoSex
      - title: Person
  OrganizationName:
    allOf:
      - properties:
          name:
            description: The name of the `Organization`.
            type: string
          use:
            description: >-
              The way in which the `OrganizationName` is normally or correctly
              used.
            type: string
      - $ref: '#/definitions/EffectiveDates'
      - title: OrganizationName
  Organization:
    allOf:
      - $ref: '#/definitions/Party'
      - properties:
          organizationName:
            $ref: '#/definitions/OrganizationName'
          otherOrganizationNames:
            type: array
            items:
              $ref: '#/definitions/OrganizationName'
      - $ref: '#/definitions/EffectiveDates'
      - title: Organization
  OrganizationUnit:
    allOf:
      - $ref: '#/definitions/Organization'
      - description: An Organization that is part of another Organization.
      - title: OrganizationUnit
  Company:
    allOf:
      - $ref: '#/definitions/Organization'
      - description: >-
          Represents an Organization created to make money by selling goods or
          services, with a legal identity that is separate from its owners.
      - title: Company
  CompanyGroup:
    allOf:
      - $ref: '#/definitions/Company'
      - description: >-
          An Organization comprising a collection of Companies that have a legal
          relationship.
      - title: CompanyGroup
