-- YML module extracted from ITU-T Q.819 (01/2022)

openapi: 3.0.0
info:
  title: ITU-T_NotificationService
  description: ''This is the formal definition of the ITU-T Notification Service.''
  termsOfService: https://www.itu.int/en/ITU-T/about/Pages/default.aspx
  contact:
    email: zlwang@bupt.edu.cn
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
externalDocs:
  description: See Recommendation ITU-T Q.819
  url: https://www.itu.int/itu-t/recommendations/index.aspx?ser=X
servers:
- url: http://www.itu.int/sg2/rest/NotificationService/v1.0.0
- url: https://www.itu.int/sg2/rest/NotificationService/v1.0.0
tags:
- name: NotificationService
  description: All APIs realted to the ITU-T Notification Service
  externalDocs:
    description: Find out more
    url: https://www.itu.int/itu-t/recommendations/index.aspx?ser=X

paths:
  /Subscription:
    post:
      tags:
      - NotificationService
      summary: "subscribe notification"
      description: "create an subscription in the notification services with the specified parameters list"
      operationId: "subscribeNotification"
      requestBody:
        description: "The input parameters of the subscribeNotification operation"
        content:
          application/json:
            schema:
              $ref: ''#/components/schemas/SubscribeNotificationRequest''
        required: true
      responses:
        201:
          description: "Subscription is successfully created, and the new Subscription ID value will be returned."
          content:
            application/json:
              schema:
                $ref: ''#/components/schemas/subscriptionId''
        400:
          description: "Parameter Error occurred in the subscribeNotification operation"
          content:
            application/json:
              schema:
                $ref: ''#/components/schemas/ErrorInfo''
        404:
          description: "The URI does not exist"
          content: {}
        409:
          description: "Subscription Conflict"
          content: {}
        500:
          description: "Internal Server Error"
          content: {}
      callbacks:
        notification:
          ''{$request.query.requestBody.destination}'':
          #''{$request.query.requestBody.destination}?event={$request.query.requestBody.eventTypes}'':
            post:
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: ''#/components/schemas/NotificationInfo''
                    #example:
                      #messageasdfasdf: Some event
              responses:
                ''200'':
                  description: OK
                  
    get:
      tags:
      - NotificationService
      summary: "Get Subscription Information"
      description: "get the list of Identifiers of all the existing Notification Subscriptions"
      operationId: "listAllSubscriptionIds"
      responses:
        200:
          description: "The attribute value list of the specified MO is retrieved successfully"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/subscriptionId"
        404:
          description: "Specified Subscription Not found"
          content: {}
        500:
          description: "Internal Server Error"   
          content: {}
  
  /Subscription={subscriptionId}:
    parameters:
      - name: subscriptionId
        in: path
        description: "The unique Identifier of the notification Subscription"
        required: true
        schema:
          type: string
          
    get:
      tags:
      - NotificationService
      summary: "Query Subscription Information"
      description: "query the attributes information of a specific Notification Subscription"
      operationId: querySubscription"
      responses:
        200:
          description: "The attribute value list of the specified MO is retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionInfo"
        404:
          description: "Specified Subscription Not found"
          content: {}
        500:
          description: "Internal Server Error"   
          content: {}
      
    delete:
      tags:
      - NotificationService
      summary: "Unsubscribe Notification"
      description: "delete a specific Notification Subscription"
      operationId: "unsubscribeNotification"
      responses:
        200:
          description: "The specified Subscription is deleted successfullly"
          content: {}
        404:
          description: "Specified Subscription does not exist"
          content: {}
        405:
          description: "Method Not Allowed, the specified Subscription cannot be deleted"
          content: {}
        500:
          description: "Internal Server Error"
          content: {}
          
    patch:
      tags:
      - NotificationService
      summary: "Modify Subscription"
      description: "modify a specific Notification Subscription"
      operationId: "modifySuscription"
      requestBody:
        description: "The input parameters of the modifySuscription operation"
        content:
          application/json:
            schema:
              $ref: ''#/components/schemas/ModifySubscriptionRequest''
        required: true
      responses:
        200:
          description: "The specified Subscription is modified successfullly, and the modified Suscription information is returned"
          content: 
            application/json:
              schema:
                $ref: ''#/components/schemas/SubscriptionInfo''
        400:
          description: "Parameter Error occurred in the modifySuscription operation"
          content:
            application/json:
              schema:
                $ref: ''#/components/schemas/ErrorInfo''
        404:
          description: "Specified Subscription does not exist"
          content: {}
        405:
          description: "Method Not Allowed, the specified Subscription cannot be modified"
          content: {}
        500:
          description: "Internal Server Error"
          content: {}
          
  /Subscription={subscriptionId}/suspend:
    parameters:
      - name: subscriptionId
        in: path
        description: "The unique Identifier of the notification Subscription"
        required: true
        schema:
          type: string
          
    post:
      tags:
      - NotificationService
      summary: "Suspend Subscription "
      description: "Suspend the specific Notification Subscription"
      operationId: "suspendSubscription"
      responses:
        200:
          description: "The specified Subscription is suspended successfully"
          content: {}
        404:
          description: "Specified Subscription Not found"
          content: {}
        405:
          description: "Method Not Allowed"
          content: {}
        409:
          description: "Subscription already Suspended"
          content: {}
        500:
          description: "Internal Server Error"   
          content: {}
          
  /Subscription={subscriptionId}/resume:
    parameters:
      - name: subscriptionId
        in: path
        description: "The unique Identifier of the notification Subscription"
        required: true
        schema:
          type: string
          
    post:
      tags:
      - NotificationService
      summary: "Resume Subscription "
      description: "Resume the specific suspended Notification Subscription"
      operationId: "resumeSubscription"
      responses:
        200:
          description: "The specified Subscription is resumed successfully"
          content: {}
        400:
          description: "Subscription already Resumed"
          content: {}
        404:
          description: "Specified Subscription Not found"
          content: {}
        405:
          description: "Method Not Allowed"
          content: {}
        500:
          description: "Internal Server Error"   
          content: {}

  /NotificationTypes:
    get:
      tags:
      - NotificationService
      summary: "Get Motification Types"
      description: "get the supportted Notification Types."
      operationId: "getNotificationTypes"
      responses:
        200:
          description: "The attribute value list of the specified MO is retrieved successfully"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NotificationType"
  
        404:
          description: "Specified Subscription Not found"
          content: {}
        500:
          description: "Internal Server Error"   
          content: {}

components:
  schemas:
    
    NVPair:
      type: object
      required:
      - name
      - value
      properties:
        name: 
          type: string
        value:
          type: string
        type:
          type: string
          
    NVPairList:
      type: object
      properties:
        attributeList:
          type: array
          items:
            $ref: ''#/components/schemas/NVPair''

    SubscribeNotificationRequest:
      type: object
      properties:
        managerId:
          type: string
        notificationTypeList:
        #empty list means subscribing all notification types.
          type: array
          items:
            $ref: ''#/components/schemas/NotificationType''
        filteringCritteria:
        #optional
          type: string
        destination:
        #URI of the notification subscriber
          type: string
          format: uri
      required:
        - managerId
        - destination
        
    NotificationType:
      type: string
      enum:
        - objectCreation
        - objectDeletion
        - attributeValueChange
        - stateChange
        - communicationAlarm
        - environmentalAlarm
        - equipmentAlarm
        - processingErrorAlarm
        - qualityOfServiceAlarm
        - integrityViolation
        - operationalViolation
        - physicalViolation
        - securityViolation
        - timeDomainViolation
        - relationshipChange
        - heartbeat
    
    subscriptionId:
      type: string
      
    ErrorInfo:
      type: object
      properties:
        code:
          type: string
          enum:
            - invalidObjectInstance
            - noSuchObjectClass
            - noSuchAttribute
            - invalidAttributeValue
            - missingAttributeValue
            - notFound
            - cannotBeDeleted
        message:
          type: string
      required:
        - code
      
    SubscriptionInfo:
      type: object
      properties:
        subscriptionId:
          type: string
        managerId:
        #the identifier of manager of this notification subscription
          type: string
        notificationTypeList:
        #empty list means subscribing all notification types.
          type: array
          items:
            $ref: ''#/components/schemas/NotificationType''
        filteringCriteria:
        #optional
          type: string
        destination:
        #URI of the notification subscriber
          type: string
          format: uri
        subscriptionStatus:
        #Whether the subscription is suspended or resumed
          type: string
          enum: 
            - suspended
            - resumed
      required:
        - subcriptionId
        - managerId
        - destination
        - subscriptionState
        
    ModifySubscriptionRequest:
      type: object
      properties:
        notificationTypeList:
        #empty list means subscribing all notification types.
          type: array
          items:
            $ref: ''#/components/schemas/NotificationType''
        filteringCriteria:
        #optional
          type: string
        destination:
        #URI of the notification subscriber
          type: string
          format: uri
      
    NotificationInfo:
      type: object
      properties:
        notificationHeader:
          $ref: ''#/components/schemas/NotificationHeader''
        notificationBody:
          $ref: ''#/components/schemas/NotificationBody''
      required:
      - notificationHeader
      - notificationBody
          
    NotificationHeader:
      type: object
      properties:
        objectClass:
          type: string
        objectInstance:
          type: string
          format: uri
        notificationId:
          type: string
        eventTime:
          type: string
          # to be confirmed.
          format: date-time
        systemDN:
          type: string
        notificationType:
          $ref: ''#/components/schemas/NotificationType''
      required:
        - objectClass
        - objectInstance
        - notificationId
        - eventTime
        - systemDN
        - notificationType
    
    NotificationBody:
      type: object
      #One of the following will be used in a concreate notification
      properties:
        objectCreationBody:
          $ref: ''#/components/schemas/ObjectCreationDeletionBody''
        objectDeletionBody:
          $ref: ''#/components/schemas/ObjectCreationDeletionBody''
        atributeValueChangeBody:
          $ref: ''#/components/schemas/AttributeValueChangeBody''
        stateChangeBody:
          $ref: ''#/components/schemas/StateChangeBody''
        alarmNotificationBody:
          #for communicationsAlarm, environmentalAlarm, equipmentAlarm, processingErrorAlarm, qualityOfServiceAlarm
          $ref: ''#/components/schemas/AlarmNotificationBody''
        violationsNoitificationBody:
          $ref: ''#/components/schemas/ViolationsNoitificationBody''
        relationshipChangeNotificationBody:
          $ref: ''#/components/schemas/RelationshipChangeNotificationBody''
        heartbeatNotificationBody:
          $ref: ''#/components/schemas/HeartbeatNotificationBody''
    
    ObjectCreationDeletionBody:
      type: object
      properties:
        commonAttributes:
          $ref: ''#/components/schemas/CMNotificationCommonAttrs''
        attributeList:
          $ref: ''#/components/schemas/NVPairList''
          
    AttributeValueChangeBody:
      type: object
      properties:
        commonAttributes:
          $ref: ''#/components/schemas/CMNotificationCommonAttrs''
        attributeChanges:
          $ref: ''#/components/schemas/NVPairList''
      required:
        - attributeChanges
          
    StateChangeBody:
      type: object
      properties:
        commonAttributes:
          $ref: ''#/components/schemas/CMNotificationCommonAttrs''
        stateChanges:
          $ref: ''#/components/schemas/NVPairList''
      required:
        - stateChanges
    
    CMNotificationCommonAttrs:
      type: object
      properties:
        correlatedNotifications:
          type: array
          items:
            type: string
        additionalText:
          type: string
        additionalInfo:
          type: string
        sourceIndicator:
          $ref: ''#/components/schemas/SourceIndicator''
          
    SourceIndicator:
      type: string
      format: enum
        - resourceOperation
        - managementOperation
        - unknown

    AlarmNotificationBody:
      type: object
      properties:
        correlatedNotifications:
          type: array
          items:
            type: string
        additionalText:
          type: string
        additionalInfo:
          type: string
        probableCause:
          type: string
        specificProblems:
          type: array
          items:
            type: string
        perceivedSeverity:
           $ref: ''#/components/schemas/AlarmSeverity''
        backedUpStatus:
          type: boolean
        backUpObject:
          type: string
          format: uri
        trendIndication:
          $ref: ''#/components/schemas/TrendIndication''
        thresholdInfo:
          $ref: ''#/components/schemas/ThresholdInfo''
        stateChangeDefinition:
          $ref: ''#/components/schemas/StateChangeDefinition''
        moniterdAttributes:
          type: array
          items:
            type: string
        proposedRepairActions:
          type: array
          items:
            type: string
        alarmEffectOnService:
          type: boolean
        alarmingResumed:
          type: boolean
        suspectObjectList:
          type: array
          items:
            type: string
            format: uri
      required:
        - probableCause
        - perceivedSeverity
        
        
    AlarmSeverity:
      type: string
      format: enum
        - cleared
        - warning
        - indetermined
        - minor
        - major
        - critical
    
    TrendIndication:
      type: string
      format: enum
        - lessSevere
        - noChange
        - moreSevere

    ThresholdInfo:
      type: object
      properties:
        attributeID:
          type: string
        observedValue:
          type: number
          format: float
        thresholdLevel:
          $ref: ''#/components/schemas/ThresholdLevelInd''
        armTime:
          type: string
          format: date-time

    ThresholdLevelInd:
      type: object
      properties:
        indication:
          $ref: ''#/components/schemas/ThresholdIndication''
        low:
          type: number
          format: float
        high:
          type: number
          format: float
    
    ThresholdIndication:
      type: string
      format: enum
        - up
        - down
      
    StateChangeDefinition:
      $ref: ''#/components/schemas/NVPairList''
      
    ViolationsNoitificationBody:
      type: object
      properties:
        correlatedNotifications:
          type: array
          items:
            type: string
        additionalText:
          type: string
        additionalInfo:
          type: string
        securityAlarmCause:
          type: string
        securityAlarmSeverity:
           $ref: ''#/components/schemas/AlarmSeverity''
        securityAlarmDetector:
          $ref: ''#/components/schemas/SecurityAlarmDetector''
        serviceUser:
          type: string
        serviceProvider:
          type: string
      required:
        - securityAlarmCause
        - securityAlarmSeverity
        - securityAlarmDetector
        - serviceUser
        - serviceProvider
    
    
    SecurityAlarmDetector:
      type: object
      properties:
        mechanism:
          $ref: ''#/components/schemas/UID''
        obj:
          type: string
          format: uri
          
    UID:
      type: object
      properties:
        uri:
          type: string
          format: uri
        value:
          type: integer
          format: unsignedLong
 
    RelationshipChangeNotificationBody:
      type: object
      properties:
        commonAttributes:
          $ref: ''#/components/schemas/CMNotificationCommonAttrs''
        relationshipChanges:
          $ref: ''#/components/schemas/AttributeChangeSet''
      required:
        - relationshipChanges

    AttributeChangeSet:
      type: array
      items:
        $ref: ''#/components/schemas/AttributeChange''

    AttributeChange:
      type: object
      properties:
        attribugteName:
          type: string
        attributeType:
          type: string
        oldValue:
          type: string
        newValue:
          type: string

    HeartbeatNotificationBody:
      type: object
      properties:
        systemLabel:
          type: string
          format: uri
        period:
          type: integer
          format: unitsInSeconds
        timeStamp:
          type: string
          format: date-time