openapi: 3.0.1
info:
  description: |

    It allows the Buyer to retrieve address information from the Seller, including
    exact formats, for addresses known to the Seller.

    List of supported use cases:
    
    - Validate Address
    - Retrieve Address by Identifier

    Copyright 2021 MEF Forum and its contributors

    This file includes content based on the TM Forum Geographic Address API
    (TMF673 v4.0.1) available at
    https://github.com/tmforum-apis/TMF673_GeographicAddress, which is licensed
    by the TM Forum under the Apache License version 2.0. Such content has been
    modified by the MEF Forum and its contributors.
  title: Geographic Address Management
  version: 7.0.1
servers:
  - url: 'https://{serverBase}/mefApi/sonata/geographicAddressManagement/v7/'
    variables:
      serverBase:
        default: mef.net
        description: The base of Seller's URL.
tags:
  - name: geographicAddressValidation
  - name: geographicAddress
  - name: events subscription
paths:
  /geographicAddressValidation:
    post:
      description: This operation creates a GeographicAddressValidation entity.
      operationId: createGeographicAddressValidation
      parameters:
        - description: >-
            The unique identifier of the organization that is acting as the a
            Buyer. MUST be specified in the request only when the requester
            represents more than one Buyer.

            Reference: MEF 79 (Sn 8.8)
          in: query
          name: buyerId
          schema:
            type: string
        - description: >-
            The unique identifier of the organization that is acting as the
            Seller. MUST be specified in the request only when responding
            entity  represents more than one Seller.

            Reference: MEF 79 (Sn 8.8)
          in: query
          name: sellerId
          schema:
            type: string
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/GeographicAddressValidation_Create'
        description: The GeographicAddressValidation to be created
        required: true
      responses:
        '200':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/GeographicAddressValidation'
          description:
            'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'
        '400':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
          description: Bad Request
        '401':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
          description: Unauthorized
        '403':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
          description: Forbidden
        '422':
          content:
            application/json;charset=utf-8:
              schema:
                items:
                  $ref: '#/components/schemas/Error422'
                type: array
          description:
            Unprocessable entity due to the business validation problems
        '500':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
          description: Internal Server Error
      summary: Creates a GeographicAddressValidation
      tags:
        - geographicAddressValidation
      x-codegen-request-body-name: geographicAddressValidation
  '/geographicAddress/{id}':
    get:
      description: >-
        This operation retrieves a GeographicAddress entity.
      operationId: retrieveGeographicAddress
      parameters:
        - description: Identifier of the GeographicAddress
          in: path
          name: id
          required: true
          schema:
            type: string
        - description: >-
            The unique identifier of the organization that is acting as the a
            Buyer. MUST be specified in the request only when the requester
            represents more than one Buyer.

            Reference: MEF 79 (Sn 8.8)
          in: query
          name: buyerId
          schema:
            type: string
        - description: >-
            The unique identifier of the organization that is acting as the
            Seller. MUST be specified in the request only when responding
            entity  represents more than one Seller.

            Reference: MEF 79 (Sn 8.8)
          in: query
          name: sellerId
          schema:
            type: string
      responses:
        '200':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/GeographicAddress'
          description: OK
        '400':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
          description: Bad Request
        '401':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
          description: Unauthorized
        '403':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
          description: Forbidden
        '404':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
          description: Not Found
        '500':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
          description: Internal Server Error
      summary: Retrieves a GeographicAddress by ID
      tags:
        - geographicAddress
components:
  schemas:
    Error400Code:
      description: >-
        One of the following error codes:

        - missingQueryParameter: The URI is missing a required query-string
        parameter

        - missingQueryValue: The URI is missing a required query-string
        parameter value

        - invalidQuery: The query section of the URI is invalid.

        - invalidBody: The request has an invalid body
      enum:
        - missingQueryParameter
        - missingQueryValue
        - invalidQuery
        - invalidBody
      type: string
    Error:
      description: >
        Standard Class used to describe API response error Not intended to be
        used directly. The `code` in the HTTP header is used as a discriminator
        for the type of error returned in runtime.
      properties:
        reason:
          description: >-
            Text that explains the reason for error. This can be shown to a
            client user.
          maxLength: 255
          type: string
        message:
          description: >-
            Text that provides mode details and corrective actions related to
            the error. This can be shown to a client user.
          type: string
        referenceError:
          description: URL pointing to documentation describing the error
          format: uri
          type: string
      required:
        - reason
      type: object
    Error400:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              $ref: '#/components/schemas/Error400Code'
          required:
            - code
          type: object
      description:
        'Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)'
    Error401:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              $ref: '#/components/schemas/Error401Code'
          required:
            - code
          type: object
      description:
        'Unauthorized.  (https://tools.ietf.org/html/rfc7235#section-3.1)'
    Error401Code:
      description: |-
        One of the following error codes:
        - missingCredentials: No credentials provided.
        - invalidCredentials: Provided credentials are invalid or expired
      enum:
        - missingCredentials
        - invalidCredentials
      type: string
    Error403:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              $ref: '#/components/schemas/Error403Code'
          required:
            - code
          type: object
      description:
        'Forbidden. (https://tools.ietf.org/html/rfc7231#section-6.5.3)'
    Error403Code:
      description: |-
        This code indicates that the server understood
        the request but refuses to authorize it because
        of one of the following error codes:
        - accessDenied: Access denied
        - forbiddenRequester: Forbidden requester
        - tooManyUsers: Too many users
      enum:
        - accessDenied
        - forbiddenRequester
        - tooManyUsers
      type: string
    Error404:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              description: >-
                The following error code:

                - notFound: A current representation for the target resource
                not found
              enum:
                - notFound
              type: string
          required:
            - code
          type: object
      description: >-
        Resource for the requested path not found.
        (https://tools.ietf.org/html/rfc7231#section-6.5.4)
    Error422:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              $ref: '#/components/schemas/Error422Code'
            propertyPath:
              description: >
                A pointer to a particular property of the payload that caused
                the validation issue. It is highly recommended that this
                property should be used.

                Defined using JavaScript Object Notation (JSON) Pointer
                (https://tools.ietf.org/html/rfc6901).
              type: string
          required:
            - code
          type: object
      description: >-
        Unprocessable entity due to a business validation problem.
        (https://tools.ietf.org/html/rfc4918#section-11.2)
    Error422Code:
      description: |
        One of the following error codes:
          - missingProperty: The property the Seller has expected is not present in the payload
          - invalidValue: The property has an incorrect value
          - invalidFormat: The property value does not comply with the expected value format
          - referenceNotFound: The object referenced by the property cannot be identified in the Seller system
          - unexpectedProperty: Additional property, not expected by the Seller has been provided
          - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold.
          - otherIssue: Other problem was identified (detailed information provided in a reason)
      enum:
        - missingProperty
        - invalidValue
        - invalidFormat
        - referenceNotFound
        - unexpectedProperty
        - tooManyRecords
        - otherIssue
      type: string
    Error500:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              description: >-
                The following error code:

                - internalError: Internal server error - the server encountered
                an unexpected condition that prevented it from fulfilling the
                request.
              enum:
                - internalError
              type: string
          required:
            - code
          type: object
      description: >-
        Internal Server Error.
        (https://tools.ietf.org/html/rfc7231#section-6.6.1)
    FieldedAddress:
      allOf:
        - $ref: '#/components/schemas/GeographicAddress'
        - properties:
            country:
              description: The country that the address is in
              type: string
            streetType:
              description: >-
                The type of street (e.g., alley, avenue, boulevard, brae,
                crescent, drive, highway, lane, terrace, parade, place, tarn,
                way, wharf)
              type: string
            postcodeExtension:
              description: >-
                An extension of a postal code. E.g. the part following the dash
                in a US urban property address
              type: string
            city:
              description: The city that the address is in
              type: string
            streetNr:
              description: >-
                Number identifying a specific property on a public street. It
                may be combined with streetNrLast for ranged addresses. MEF 79
                defines it as required however as in certain countries it is
                not used we make it optional in API.
              type: string
            locality:
              description: The locality that the address is in
              type: string
            postcode:
              description: >-
                A descriptor for a postal delivery area used to speed and
                simplify the delivery of mail (also known as zip code) MEF 79
                defines it as required however as in certain countries it is
                not used we make it optional in API.
              type: string
            streetNrLast:
              description:
                Last number in a range of street numbers allocated to a
                property
              type: string
            streetNrSuffix:
              description: The first street number suffix
              type: string
            streetName:
              description: Name of the street or other street type
              type: string
            stateOrProvince:
              description: The State or Province that the address is in
              type: string
            streetNrLastSuffix:
              description: Last street number suffix for a ranged address
              type: string
            geographicSubAddress:
              $ref: '#/components/schemas/GeographicSubAddress'
              description:
                Additional fields used to specify an address, as detailed as
                possible.
            streetSuffix:
              description: A modifier denoting a relative direction
              type: string
          required:
            - city
            - country
            - streetName
          type: object
      description: >-
        A type of Address that has a discrete field and value for each type of
        boundary or identifier down to the lowest level of detail. For example
        "street number" is one field, "street name" is another field, etc.
        Reference: MEF 79 (Sn 8.9.2)
    FormattedAddress:
      allOf:
        - $ref: '#/components/schemas/GeographicAddress'
        - properties:
            country:
              description: The country that the address is in
              type: string
            postcodeExtension:
              description: >-
                An extension of a postal code. E.g. the part following the dash
                in a US urban property address
              type: string
            stateOrProvince:
              description: The State or Province that the address is in
              type: string
            city:
              description: The city that the address is in
              type: string
            addrLine2:
              description: The second address line in a formatted address
              type: string
            addrLine1:
              description: The first address line in a formatted address
              type: string
            locality:
              description: >-
                An area of defined or undefined boundaries within a local
                authority or other legislatively defined area, usually rural or
                semi-rural in nature
              type: string
            postcode:
              description: >-
                A descriptor for a postal delivery area used to speed and
                simplify the delivery of mail (also known as ZIP code)
              type: string
          required:
            - addrLine1
            - city
            - country
          type: object
      description: >-
        A type of Address that has discrete fields for each type of boundary or
        identifier with the exception of street and more specific location
        details, which are combined into a maximum of two strings based on
        local postal addressing conventions.  Reference: MEF 79 (Sn 8.9.3)
    GeographicAddress:
      description: >-
        Structured textual way of describing how to find a property in an urban
        area (country properties are often defined differently).

        Note: Address corresponds to SID UrbanPropertyAddress
      discriminator:
        mapping:
          FieldedAddress: '#/components/schemas/FieldedAddress'
          FormattedAddress: '#/components/schemas/FormattedAddress'
          MEFGeographicPoint: '#/components/schemas/MEFGeographicPoint'
          GeographicAddressLabel: '#/components/schemas/GeographicAddressLabel'
        propertyName: '@type'
      properties:
        hasPublicSite:
          description: >-
            This attribute specifies if that Address contains Service Sites
            that are public such as Meet-Me-Rooms at an interconnect location
            or a shared telecom room in the basement of a multi-tenant building
          readOnly: true
          type: boolean
        '@type':
          description: >
            This field is used as discriminator. The value is the name of one
            of the types that inherit from it using 'allOf', i.e. one of
            FieldedAddress, FormattedAddress, GeographicAddressLabel,
            MEFGeographicPoint. Moreover, it might discriminate for an
            additional related place as defined in '@schemaLocation'.
          type: string
        allowsNewSite:
          description: >-
            This attribute specifies if a Buyer must use one of the known
            existing Service Sites at this location for any Products delivered
            to this Address. For example, if a particular building owner
            mandated that all interconnects be done in a shared Public
            Meet-Me-Room, this attribute would be set to False for that
            Address.
          readOnly: true
          type: boolean
        id:
          description: Unique identifier of the place
          readOnly: true
          type: string
        href:
          description: Unique reference of the place
          readOnly: true
          type: string
        '@schemaLocation':
          description: >-
            A URI to a JSON-Schema file that defines additional attributes and
            relationships. May be used to define additional GeographicAddress
            types. Usage of this attribute must be agreed upon between Buyer
            and Seller.
          format: uri
          type: string
        associatedGeographicAddress:
          $ref: '#/components/schemas/FieldedAddress'
          readOnly: true
          description:
            A Fielded Address that is associated with the Geographic Point or
            the Geographic Address Label.
      required:
        - '@type'
      type: object
    GeographicAddressLabel:
      allOf:
        - $ref: '#/components/schemas/GeographicAddress'
        - properties:
            externalReferenceId:
              description: >-
                The unique reference to an Address as provided by the
                Administrative Authority.
              type: string
            externalReferenceType:
              description: >-
                The organization or standard from the organization that
                administers this Geographic Address Label ensuring it is unique
                within the Administrative Authority. The value(s) to be used
                are to be agreed during the onboarding. For North American
                providers this would normally be CLLI (Common Language Location
                Identifier) code.
              type: string
          required:
            - externalReferenceId
            - externalReferenceType
          type: object
      description: >-
        A unique identifier controlled by a generally accepted independent
        administrative authority that specifies a fixed geographical location. 

        Reference: MEF 79 (Sn 8.9.4)
    GeographicAddressValidation:
      description: This resource is used to manage address validation response.
      properties:
        validationResult:
          $ref: '#/components/schemas/MEFValidationResultType'
          description:
            Result of the address validation (success, partial, fail)
        alternateGeographicAddress:
          items:
            $ref: '#/components/schemas/GeographicAddress'
          type: array
          description: |
            An array of zero or more Addresses known to the Seller that are
            considered by the Seller to match the submittedGeographicAddress.
            Not including the bestMatchAddress. MEF: Alternatives should be
            provided regardless of whether best match was found.
        provideAlternative:
          description: >
            Indicator provided by the requester to specify if alternate
            addresses must be provided in case of partial or fail result. MEF:
            The attribute is kept for TMF API compliance. MEF requires this
            attribute always to be set to 'true'. Alternatives should be
            provided regardless of whether best match was found. The Seller is
            allowed not to implement the support for 'false'
          type: boolean
        submittedGeographicAddress:
          $ref: '#/components/schemas/GeographicAddress'
          description:
            'The address as submitted to validation. MEF: Structure used by the
            buyer to request geographic address validation'
        bestMatchGeographicAddress:
          $ref: '#/components/schemas/GeographicAddress'
          description:
            Represents that the Seller is confident this is likely a direct
            match to the submittedGeographicAddress
      required:
        - provideAlternative
        - submittedGeographicAddress
      type: object
    GeographicAddressValidation_Create:
      description: >-
        This resource is used to manage address validation request.


        Skipped properties: alternateGeographicAddress,
        bestMatchGeographicAddress, validationResult.
      properties:
        provideAlternative:
          description: >
            Indicator provided by the requester to specify if alternate
            addresses must be provided in case of partial or fail result. MEF:
            The attribute is kept for TMF API compliance. MEF requires this
            attribute always to be set to 'true'. Alternatives should be
            provided regardless of whether best match was found. The Seller is
            allowed not to implement the support for 'false'
          type: boolean
        submittedGeographicAddress:
          $ref: '#/components/schemas/GeographicAddress'
          description:
            'The address as submitted to validation. MEF: Structure used by the
            buyer to request geographic address validation'
      required:
        - provideAlternative
        - submittedGeographicAddress
      type: object
    GeographicSubAddress:
      description:
        'Additional fields used to specify an address, as detailed as possible.'
      properties:
        buildingName:
          description: >
            Allows for identification of places that require building name  as
            part of addressing information
          type: string
        subUnit:
          description: >-
            Representation of a MEFSubUnit It is used for describing subunit
            within a subAddress e.g.BERTH, FLAT, PIER, SUITE, SHOP, TOWER,
            UNIT, WHARF.
          items:
            $ref: '#/components/schemas/MEFSubUnit'
          type: array
        levelType:
          description: Describes level types within a building
          type: string
        levelNumber:
          description:
            'Used where a level type may be repeated e.g. BASEMENT 1, BASEMENT
            2'
          type: string
        privateStreetNumber:
          description: Private streets numbers internal to a private street
          type: string
        privateStreetName:
          description: >-
            Private streets internal to a property (e.g. a university) may have
            internal names that are not recorded by the land title office
          type: string
      type: object
    MEFGeographicPoint:
      allOf:
        - $ref: '#/components/schemas/GeographicAddress'
        - properties:
            spatialRef:
              description: >-
                The spatial reference system used to determine the coordinates.
                The system used and the value of this field are to be agreed
                during the onboarding process.
              type: string
            x:
              description: >-
                The latitude expressed in the format specified by the
                `spacialRef`
              type: string
            'y':
              description: >-
                The longitude expressed in the format specified by the
                `spacialRef`
              type: string
            z:
              description: >-
                The elevation expressed in the format specified by the
                `spacialRef`
              type: string
          required:
            - spatialRef
            - x
            - 'y'
          type: object
      description: >
        A MEFGeographicPoint defines a geographic point through coordinates.
        Reference: MEF 79 (Sn 8.9.5), MEF 79.0.2 (Sn 8.9.5)
    MEFSubUnit:
      description: Allows for sub unit identification
      properties:
        subUnitNumber:
          description: >-
            The discriminator used for the subunit, often just a simple number
            but may also be a range.
          type: string
        subUnitType:
          description: >-
            The type of subunit e.g. BERTH, FLAT, PIER, SUITE, SHOP, TOWER,
            UNIT, WHARF.
          type: string
      required:
        - subUnitNumber
        - subUnitType
      type: object
    MEFValidationResultType:
      description: |
        Result of the address validation:
        - success - best match found,
        - partial - no best match but alternatives available,
        - fail - neither best match nor alternatives provided
      enum:
        - success
        - partial
        - fail
      type: string
