Open APIs

 View Only
  • 1.  geographicLocation schema: old version (TMF675) vs new version (as a part of v5 APIs)

    TM Forum Member
    Posted Apr 02, 2024 08:26

    Hi All,

    In the old (non-active) version of TMF675 we have following schema for geographicLocation:

      GeographicLocation:
        description: Structured textual way of describing a geographic location. A geographic location allows describing through coordinate(s), a point, a line or a space.
        required:
          - name
          - geometryType
          - spatialRef
          - accuracy
          - geometry
        type: object
        properties:
          id:
            description: Unique identifier of the geographic location
            type: string
          href:
            description: An URI used to access to the geographic location resource
            type: string
          name:
            description: Name of the geo location
            type: string
          geometryType:
            description: 'Type of the geographic location - one of: point, line, graph, ring polygon'
            type: string
          spatialRef:
            description: Geocoding referential
            type: string
          accuracy:
            description: Accuracy of the coordinate specified
            type: string
          geometry:
            type: array
            items:
              $ref: '#/definitions/GeographicPoint'
          '@baseType':
            description: Indicates the base type of the resource. Here can be 'geographicLocation'.
            type: string
          '@type':
            description: Indicates the type of the resource
            type: string
          '@schemaLocation':
            description: A link to the schema describing this REST Resource
            type: string

    In v5 APIs (for example TMF637) the following one:

       GeographicLocation:
          allOf:
            - $ref: '#/components/schemas/Place'
            - type: object
              description: >-
                A GeographicLocation is a pure-virtual super-class to the GeoJSON-aligned geometries of
                Point (addresses and locations), MultiPoint, LineString (streets, highways and
                boundaries), MultiLineString and Polygon (countries, provinces, tracts of land). Use the
                @type attribute to specify which of these is being specified by the geometry attribute.
              properties:
                id:
                  type: string
                  description: Unique identifier of the geographic location
                href:
                  type: string
                  description: An URI used to access to the geographic location resource
                '@type':
                  type: string
                  enum:
                    - GeoJsonPoint
                    - GeoJsonMultiPoint
                    - GeoJsonLineString
                    - GeoJsonMultiLineString
                    - GeoJsonPolygon
                  description: The name of the GeoJSON structure used in the geometry attribute
                bbox:
                  type: array
                  description: >-
                    A bounding box array that contains the geometry. The axes order follows the axes
                    order of the geometry
                  items:
                    type: number

    Questions:

    1. Does it mean that new APIs define new (valid) schema for geographicLocation in the absence of valid TMF675 specification?
    2. Is really reserved parameter @type used here to define type of geometry??


    ------------------------------
    Anna Berdnikova
    Deutsche Telekom AG
    ------------------------------


  • 2.  RE: geographicLocation schema: old version (TMF675) vs new version (as a part of v5 APIs)

    TM Forum Member
    Posted Apr 04, 2024 04:29

    Hi Anna

    Indeed yes, the GeoLocation schema has been updated in gen5 Open APIs. It looks like the work on publishing the API itself is still in progress, I don't have visibility on when it will be ready.

    In gen5 APIs @type is a mandatory property, and it is used as a discriminator for polymorphic objects, such as in the new Characteristic pattern, or here for GeoJSON types.

    Hope it helps, but I'm referring this thread to the lead for the TMF675 API for additional comment.



    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 3.  RE: geographicLocation schema: old version (TMF675) vs new version (as a part of v5 APIs)

    TM Forum Member
    Posted Apr 09, 2024 03:13

    Hi Jonathan,

    Thank you for the reply and clarification. I expected to see discriminator in specification and here is enum, but good that you can confirm the usual usage of this property.

    Just a wish from my side (to the lead for the TMF675 API probably): geo entities are really required by a lot of APIs, it would be great to have valid versions of them.



    ------------------------------
    Anna Berdnikova
    Deutsche Telekom AG
    ------------------------------