Reefer Operational Monitoring Notification API

rmo/v1/README.md

@@ -0,0 +1,7 @@
+## Reefer Monitoring Operational (RMO)
+
+The DCSA Interface Standard for Reefer Monitoring is documented on [**SwaggerHub.**](https://app.swaggerhub.com/apis/dcsaorg/DCSA_RMO) 
+
+<a name="v100B1"></a>[Release v1.0.0-Beta-1 (Unpublished)](https://app.swaggerhub.com/apis/dcsaorg/DCSA_RMO/1.0.0-Beta-1)
+---
+Initial release for the Operational Reefer Monitoring API

rmo/v1/notification/README.md

@@ -0,0 +1,7 @@
+## Reefer Monitoring Operational Notification (RMO_NTF) API
+
+The DCSA Reefer Monitoring Operational Notification API is specified on [**SwaggerHub.**](https://app.swaggerhub.com/apis/dcsaorg/DCSA_RMO_NTF)
+
+Release v1.0.0 Beta 1 (Unpublished)
+---
+Initial release of the DCSA OpenAPI definitions for Reefer Monitoring Operational Notification API 

rmo/v1/notification/rmo_ntf_v1.0.0-Beta-1.yaml

@@ -0,0 +1,272 @@
+openapi: 3.0.0
+x-stoplight:
+  id: 56d39d62070e0
+info:
+  version: 1.0.0-Beta-1
+  title: DCSA OpenAPI specification for Operational Reefer Notifications
+  description: |
+    API specification issued by DCSA.org.
+
+    Reefer Monitoring Operational Notifications for [DCSA OpenAPI specification for Reefer Monitoring Operational](https://app.swaggerhub.com/apis/dcsaorg/DCSA_RMO/1.0.0-Beta-1) is a lightweight notification based on [CloudEvents](https://cloudevents.io/). 
+    The `POST` endpoint of the consumer is called whenever a `Reefer` that is being subscribed to meets the agreed notification criteria.
+
+    Subscribing to notification is done outside scope of this API.
+
+    ### Stats API
+    The Stats API offers crucial statistical information for both API providers and consumers to enhance their services and helps DCSA to understand and scale the ecosystem. We expect you to invoke the Stats API for every request made to the Reefer Monitoring Operational Notification API. Further details can be found [here](https://developer.dcsa.org/#/http/guides/api-guides/stats-api)
+
+    For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/rmo/notification/v1#v100B1). Please also [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments.
+  contact:
+    name: Digital Container Shipping Association (DCSA)
+    url: 'https://dcsa.org'
+    email: info@dcsa.org
+tags:
+  - name: Notifications
+    description: Notification operations
+servers:
+  - url: 'http://localhost:3000'
+paths:
+  /v1/operational-reefer-notifications:
+    post:
+      tags:
+        - Notifications
+      summary: Send a new Operational Reefer Notification
+      operationId: operational-reefer-notifications
+      description: |
+        Creates a new [`Operational Reefer Notification`](#/OperationalReeferNotification). This endpoint of the consumer is called whenever a `Reefer` that is being subscribed to meets the agreed notification criteria.
+      parameters:
+        - name: API-Version
+          in: header
+          description: |
+            An API-Version header **MUST** be provided to the request (mandatory). The header **MUST** be a [SemVer](https://semver.org/) specifying the provider (the calling party) API version.
+          required: true
+          schema:
+            type: string
+            example: 1.0.0-Beta-1
+      requestBody:
+        description: |
+          The payload used to create a [`Operational Reefer Notification`](#/OperationalReeferNotification)
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                $ref: '#/components/schemas/OperationalReeferNotification'
+            examples:
+              alarmActivatedExample:
+                summary: |
+                  A 'lite' notification for a reefer container with an activated alarm
+                description: |
+                  A notification that an alarm has been triggered for a reefer container
+                value:
+                  - specversion: '1.0'
+                    id: 3cecb101-7a1a-43a4-9d62-e88a131651e2
+                    source: 'https://member.com/'
+                    type: org.dcsa.operational-reefer-notification.v1
+                    time: '2024-01-03T17:31:00Z'
+                    datacontenttype: application/json
+                    data:
+                      notificationType: ALARM
+                      equipmentReference: APZU4812090
+                      geoLocation:
+                        latitude: '48.858550'
+                        longitude: '2.294492'
+                      alarm:
+                        alarmStatus: ACTIVE
+                        alarmNumber: '100'
+                        alarmSeverity: CRITICAL
+              deactivedExample:
+                summary: |
+                  A 'lite' notification for a reefer container with a deactivated alarm
+                description: |
+                  A notification that an alarm has been deactivated for a reefer container
+                value:
+                  - specversion: '1.0'
+                    id: 3cecb101-7a1a-43a4-9d62-e88a131651e2
+                    source: 'https://member.com/'
+                    type: org.dcsa.operational-reefer-notification.v1
+                    time: '2024-01-03T17:31:00Z'
+                    datacontenttype: application/json
+                    data:
+                      notificationType: ALARM
+                      equipmentReference: APZU4812090
+                      geoLocation:
+                        latitude: '48.858550'
+                        longitude: '2.294492'
+                      alarm:
+                        alarmStatus: INACTIVE
+                        alarmNumber: '100'
+                        alarmSeverity: CRITICAL
+      responses:
+        '204':
+          description: |
+            No Content
+          headers:
+            API-Version:
+              description: |
+                [SemVer](https://semver.org/) used to indicate the version of the consumer (the responding party). This is optional to provide.
+              schema:
+                type: string
+                example: 1.0.0-Beta-1
+      servers:
+        - url: 'http://localhost:3000'
+    parameters: []
+components:
+  schemas:
+    OperationalReeferNotification:
+      type: object
+      x-stoplight:
+        id: 621758c14a567
+      title: Operational Reefer Notification
+      description: |
+        `CloudEvent` specific properties for the `Notification`.
+      properties:
+        specversion:
+          type: string
+          description: |
+            The version of the CloudEvents specification which the event uses. This enables the interpretation of the context. Compliant event producers MUST use a value of `1.0` when referring to this version of the specification.
+
+            Currently, this attribute will only have the 'major' and 'minor' version numbers included in it. This allows for 'patch' changes to the specification to be made without changing this property's value in the serialization. Note: for 'release candidate' releases a suffix might be used for testing purposes.
+          enum:
+            - '1.0'
+          example: '1.0'
+        id:
+          type: string
+          maxLength: 100
+          description: |
+            Identifies the event. Producers MUST ensure that `source` + `id` is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same `id`. Consumers MAY assume that Events with identical `source` and `id` are duplicates.
+          example: 3cecb101-7a1a-43a4-9d62-e88a131651e2
+        source:
+          type: string
+          maxLength: 4096
+          description: |
+            Identifies the context in which an event happened. Often this will include information such as the type of the event source, the organization publishing the event or the process that produced the event. The exact syntax and semantics behind the data encoded in the URI is defined by the event producer.
+
+            Producers MUST ensure that `source` + `id` is unique for each distinct event.
+
+            An application MAY assign a unique `source` to each distinct producer, which makes it easy to produce unique IDs since no other producer will have the same source. The application MAY use UUIDs, URNs, DNS authorities or an application-specific scheme to create unique `source` identifiers.
+
+            A source MAY include more than one producer. In that case the producers MUST collaborate to ensure that `source` + `id` is unique for each distinct event.
+          example: 'https://member.com/'
+        type:
+          type: string
+          description: |
+            This attribute contains a value describing the type of event related to the originating occurrence. Often this attribute is used for routing, observability, policy enforcement, etc. The format of this is producer defined and might include information such as the version of the type - see [Versioning of CloudEvents in the Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md#versioning-of-cloudevents) for more information.
+          enum:
+            - org.dcsa.operational-reefer-notification.v1
+          example: org.dcsa.operational-reefer-notification.v1
+        time:
+          type: string
+          format: date-time
+          description: |
+            Timestamp of when the occurrence happened. If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer, however all producers for the same `source` MUST be consistent in this respect. In other words, either they all use the actual time of the occurrence or they all use the same algorithm to determine the value used.
+          example: '2018-04-05T17:31:00Z'
+        datacontenttype:
+          type: string
+          description: |
+            Content type of `data` value. This attribute enables `data` to carry any type of content, whereby format and encoding might differ from that of the chosen event format. For example, an event rendered using the [JSON envelope](formats/json-format.md#3-envelope) format might carry an XML payload in `data`, and the consumer is informed by this attribute being set to "application/xml". The rules for how `data` content is rendered for different `datacontenttype` values are defined in the event format specifications; for example, the JSON event format defines the relationship in [section 3.1](formats/json-format.md#31-handling-of-data).
+
+            For some binary mode protocol bindings, this field is directly mapped to the respective protocol's content-type metadata property. Normative rules for the binary mode and the content-type metadata mapping can be found in the respective protocol.
+
+            In some event formats the `datacontenttype` attribute MAY be omitted. For example, if a JSON format event has no `datacontenttype` attribute, then it is implied that the `data` is a JSON value conforming to the "application/json" media type. In other words: a JSON-format event with no `datacontenttype` is exactly equivalent to one with `datacontenttype="application/json"`.
+
+            When translating an event message with no `datacontenttype` attribute to a different format or protocol binding, the target `datacontenttype` SHOULD be set explicitly to the implied `datacontenttype` of the source.
+          enum:
+            - application/json
+          example: application/json
+        data:
+          type: object
+          description: |
+            `Reefer` specific properties for the `Notification`
+          required:
+            - notificationType
+            - equipmentReference
+          properties:
+            notificationType:
+              type: string
+              x-stoplight:
+                id: 04xq44dojym5x
+              description: |-
+                The type of notification being reported.  Possible values are:
+
+                * `ALARM` Reefer is in state of alarm that meets criteria for notification
+                * `GEOFENCE` Reefer has triggered a provided geofence for entry or exit
+              example: ALARM
+            reason:
+              type: string
+              maxLength: 5000
+              description: This property can be used to explain `NotificationType`.
+              example: Reefer container is in alarm state
+            equipmentReference:
+              type: string
+              x-stoplight:
+                id: qh4d8ugkuck2a
+              description: |-
+                The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.
+                                According to ISO 6346, a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit).
+                                If a container does not comply with ISO 6346, it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG.
+              pattern: ^\S+(\s+\S+)*$
+              maxLength: 11
+              example: APZU4812090
+            geoLocation:
+              type: object
+              properties:
+                latitude:
+                  $ref: '#/components/schemas/latitude'
+                longitude:
+                  $ref: '#/components/schemas/longitude'
+              description: 'The latitude, longitude geo location of the reefer when the notification was generated.'
+            alarm:
+              type: object
+              x-stoplight:
+                id: 23fcnasr894y0
+              description: Provided when alarm is activated deactivated on the reefer.
+              properties:
+                alarmStatus:
+                  type: string
+                  x-stoplight:
+                    id: h63fl95ba6npl
+                  description: |-
+                    Indicates if the alarm is active or inactive.  Possible values are:
+                    * `ACTIVE` meaning the alarm has been activated.
+                    * `INACTIVE` meaning the alarm is no longer active.
+                  example: ACTIVE
+                alarmNumber:
+                  type: string
+                  description: Alarm Code provided by Manufacturer
+                  example: '100'
+                alarmSeverity:
+                  type: string
+                  description: |-
+                    An indicator of the severity of the alarm being reported.  Possible values are:
+                    * `CRITICAL` risk to cargo and the equipment, requires intervention
+                    * `ALARM` possible risk to cargo, investigation required
+                    * `WARNING` warning of an abnormal situation, little or no change to operational running
+                    * `LOG` informational only, recorded in the datalog but no on the display.
+                  example: CRITICAL
+      required:
+        - specversion
+        - id
+        - source
+        - type
+        - time
+        - datacontenttype
+        - data
+    latitude:
+      type: string
+      pattern: '^[+-]?[0-9]{1,3}\.[0-9]{1,6}$'
+      maxLength: 10
+      description: |
+        Geographic coordinate that specifies the north–south position of a point on the Earth's surface.
+      example: '48.858550'
+      x-stoplight:
+        id: kawmon8dxjpd9
+    longitude:
+      type: string
+      x-stoplight:
+        id: 4d9bda5935ebe
+      pattern: '^[+-]?[0-9]{1,3}\.[0-9]{1,6}$'
+      maxLength: 11
+      description: |
+        Geographic coordinate that specifies the east–west position of a point on the Earth's surface.
+      example: '2.294492'