From 361b27c65584429f9ed948ebb73825076a61a8c1 Mon Sep 17 00:00:00 2001 From: David Roff Date: Wed, 3 Jan 2024 14:46:33 +0000 Subject: [PATCH 01/22] Initial Start for Notifications --- .../notification/v1/rmo_ntf_v1.0.0.yaml | 264 ++++++++++++++++++ 1 file changed, 264 insertions(+) create mode 100644 reefer_monitoring/notification/v1/rmo_ntf_v1.0.0.yaml diff --git a/reefer_monitoring/notification/v1/rmo_ntf_v1.0.0.yaml b/reefer_monitoring/notification/v1/rmo_ntf_v1.0.0.yaml new file mode 100644 index 000000000..97405da67 --- /dev/null +++ b/reefer_monitoring/notification/v1/rmo_ntf_v1.0.0.yaml @@ -0,0 +1,264 @@ +openapi: 3.0.0 +info: + version: 2.0.0-Beta-1 + title: DCSA OpenAPI specification for Operational Reefer Notifications + description: | + API specification issued by DCSA.org. + + Operational Reefer Monitoring Notifications for [DCSA OpenAPI specification for Operational Reefer Monitoring](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 changes state or is updated. + + 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 Operational Reefer Monitoring 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). 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: + /v2/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 is called whenever a `Reefer` that a consumer has subscribed to changes state or is updated. + 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: 2.0.0-Beta-1 + requestBody: + description: | + The payload used to create a [`Operational Reefer Notification`](#/OperationalReeferNotification) + content: + application/json: + schema: + $ref: '#/components/schemas/OperationalReeferNotification' + examples: + alarmActivatedExample: + summary: | + A reefer container with an activated alarm notification + 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: BICU4812097 + geoLocation: + latitude: '48.858550' + longitude: '2.294492' + alarm: + alarmStatus: ACTIVE + alarmNumber: "100" + alarmSeverity: CRITICAL + declinedExample: + summary: | + A reefer container with a deactivated alarm notification + 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: BICU4812097 + 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: 2.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: BICU4812097 + 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. + 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' + 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' From 770d10efd4918702f615d02e947be52928341b0c Mon Sep 17 00:00:00 2001 From: David Roff Date: Wed, 3 Jan 2024 14:50:51 +0000 Subject: [PATCH 02/22] corrected version --- reefer_monitoring/notification/v1/rmo_ntf_v1.0.0.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reefer_monitoring/notification/v1/rmo_ntf_v1.0.0.yaml b/reefer_monitoring/notification/v1/rmo_ntf_v1.0.0.yaml index 97405da67..0a2e9dcb7 100644 --- a/reefer_monitoring/notification/v1/rmo_ntf_v1.0.0.yaml +++ b/reefer_monitoring/notification/v1/rmo_ntf_v1.0.0.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - version: 2.0.0-Beta-1 + version: 1.0.0-Beta-1 title: DCSA OpenAPI specification for Operational Reefer Notifications description: | API specification issued by DCSA.org. From 037afe80d2f6d2f081162f24f1e6b042e5dc306f Mon Sep 17 00:00:00 2001 From: David Roff Date: Wed, 3 Jan 2024 14:55:24 +0000 Subject: [PATCH 03/22] Modified 6 files --- .../notification/v1/rmo_ntf_v1.0.0.yaml | 8 +- {reefer_monitoring => rmo}/v1/README.md | 4 + .../v1/reefer_v1.0.0-Beta-1.yaml | 113 +++++++++++++++--- 3 files changed, 107 insertions(+), 18 deletions(-) rename {reefer_monitoring => rmo}/notification/v1/rmo_ntf_v1.0.0.yaml (98%) rename {reefer_monitoring => rmo}/v1/README.md (90%) rename {reefer_monitoring => rmo}/v1/reefer_v1.0.0-Beta-1.yaml (91%) diff --git a/reefer_monitoring/notification/v1/rmo_ntf_v1.0.0.yaml b/rmo/notification/v1/rmo_ntf_v1.0.0.yaml similarity index 98% rename from reefer_monitoring/notification/v1/rmo_ntf_v1.0.0.yaml rename to rmo/notification/v1/rmo_ntf_v1.0.0.yaml index 0a2e9dcb7..b7ccae91d 100644 --- a/reefer_monitoring/notification/v1/rmo_ntf_v1.0.0.yaml +++ b/rmo/notification/v1/rmo_ntf_v1.0.0.yaml @@ -1,4 +1,6 @@ openapi: 3.0.0 +x-stoplight: + id: 56d39d62070e0 info: version: 1.0.0-Beta-1 title: DCSA OpenAPI specification for Operational Reefer Notifications @@ -68,7 +70,7 @@ paths: longitude: '2.294492' alarm: alarmStatus: ACTIVE - alarmNumber: "100" + alarmNumber: '100' alarmSeverity: CRITICAL declinedExample: summary: | @@ -228,7 +230,7 @@ components: alarmNumber: type: string description: Alarm Code provided by Manufacturer - example: "100" + example: '100' alarmSeverity: type: string description: |- @@ -253,6 +255,8 @@ components: 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: diff --git a/reefer_monitoring/v1/README.md b/rmo/v1/README.md similarity index 90% rename from reefer_monitoring/v1/README.md rename to rmo/v1/README.md index 63e5c983d..2763450a1 100644 --- a/reefer_monitoring/v1/README.md +++ b/rmo/v1/README.md @@ -1,3 +1,7 @@ +--- +stoplight-id: ozs4u0b14gxnx +--- + ## Reefer Monitoring The DCSA Interface Standard for Reefer Monitoring is documented on [**DCSA Reefer Monitoring**](https://app.swaggerhub.com/apis/dcsaorg/DCSA_RMO) SwaggerHub. diff --git a/reefer_monitoring/v1/reefer_v1.0.0-Beta-1.yaml b/rmo/v1/reefer_v1.0.0-Beta-1.yaml similarity index 91% rename from reefer_monitoring/v1/reefer_v1.0.0-Beta-1.yaml rename to rmo/v1/reefer_v1.0.0-Beta-1.yaml index bff11e287..1f5a7b978 100644 --- a/reefer_monitoring/v1/reefer_v1.0.0-Beta-1.yaml +++ b/rmo/v1/reefer_v1.0.0-Beta-1.yaml @@ -1,4 +1,6 @@ openapi: 3.0.0 +x-stoplight: + id: 29d30143d7267 info: version: 1.0.0-Beta-1 title: DCSA OpenAPI specification for Operational Reefer Monitoring @@ -120,7 +122,7 @@ paths: model: '100' receivedDateTime: '2023-12-10T10:34:12Z' isDeviceConnectedToPower: true - brand: "2" + brand: '2' inspection: - inspectionType: REMOTE inspectionDate: '2023-12-10T10:34:12Z' @@ -130,9 +132,8 @@ paths: description: Unexpected error content: application/json: - schema: + schema: $ref: ../../domain/error/error_domain_v3.0.0.yaml#/components/schemas/Error - tags: - name: Events description: Event operations @@ -146,7 +147,7 @@ components: controller: $ref: '#/components/schemas/controller' equipmentReference: - $ref: '#/components/schemas/equipmentReference' + $ref: ../../domain/dcsa/dcsa_domain_v3.1.0.yaml#/components/schemas/equipmentReference equipmentOptions: $ref: '#/components/schemas/equipmentOptions' geoLocation: @@ -184,6 +185,8 @@ components: - setpoints - reeferSettings - device + x-stoplight: + id: 5qb1b34xkxt0d alarms: type: object properties: @@ -216,6 +219,8 @@ components: required: - alarmDate - alarmNumber + x-stoplight: + id: xjzk5aisqefp8 controller: type: object description: |- @@ -245,6 +250,8 @@ components: - maker - model - operatingState + x-stoplight: + id: up81j6hmb0hrj controllerDateTime: type: string description: |- @@ -253,9 +260,13 @@ components: COA UDM Key: P15 format: date-time example: '2023-12-10T10:34:12Z' + x-stoplight: + id: 3kygiwhuc6i0p controllerHardwareVersion: type: string description: The hardware revision of the controller device + x-stoplight: + id: 83u27svagzl36 controllerMaker: type: string description: |- @@ -263,12 +274,16 @@ components: COA UDM Key: P13 example: '100' + x-stoplight: + id: yr78q4gvhj7hl controllerModel: type: string description: |- The model of the controller from the maker. COA UDM Key: P14 + x-stoplight: + id: ohslmbgfc0vzb controllerOperatingState: type: string description: |- @@ -276,29 +291,25 @@ components: COA UDM Key: P12 example: '2' + x-stoplight: + id: 6o6yydrdkuo9j controllerSerialNumber: type: string description: The serial number of the controller device + x-stoplight: + id: q5vk9d7gcipru controllerSoftwareVersion: type: string description: The software version running on the controller device - equipmentReference: - type: string - 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. - - COA UDM Key: P1 - pattern: ^\S+(\s+\S+)*$ - maxLength: 11 - example: BICU4812097 + x-stoplight: + id: 0vrofhp33s7sx equipmentOptions: type: array description: List of equipment options available on the container items: type: string + x-stoplight: + id: gwi88rl9890an geoLocation: type: object properties: @@ -306,10 +317,14 @@ components: $ref: '#/components/schemas/latitude' longitude: $ref: '#/components/schemas/longitude' + x-stoplight: + id: r0k5juxkfqndb lastDefrostDateTime: type: string description: The end time of the past defrost period format: date-time + x-stoplight: + id: blu8hqpl8k31n latitude: type: string pattern: '^[+-]?[0-9]{1,3}\.[0-9]{1,6}$' @@ -317,6 +332,8 @@ components: description: | Geographic coordinate that specifies the north–south position of a point on the Earth's surface. example: '48.858550' + x-stoplight: + id: 46hg4w1wdk2ml longitude: type: string pattern: '^[+-]?[0-9]{1,3}\.[0-9]{1,6}$' @@ -324,6 +341,8 @@ components: description: | Geographic coordinate that specifies the east–west position of a point on the Earth's surface. example: '2.294492' + x-stoplight: + id: oed8u0n72wdev measurements: type: object title: Measurements @@ -419,6 +438,8 @@ components: - supplySensor1Temperature - supplySensor2Temperature - supplyTemperature + x-stoplight: + id: jhptt1q0ha74p measuredAmbientTemperature: type: number description: | @@ -427,6 +448,8 @@ components: COA UDM Key: P6 format: float example: -15 + x-stoplight: + id: h009y1xnv3yoq measuredTemperature: type: number description: | @@ -435,6 +458,8 @@ components: COA UDM Key: P22 format: float example: -15 + x-stoplight: + id: wc2f5gny5b6uh temperatureUnit: enum: - CEL @@ -445,6 +470,8 @@ components: - CEL (Celsius) - FAH (Fahrenheit) example: CEL + x-stoplight: + id: ah5wmqyeej1z3 measuredO2: type: number description: |- @@ -455,6 +482,8 @@ components: minimum: 0 maximum: 100 example: 75.3 + x-stoplight: + id: 0n7a3ceoixoh0 measuredCo2: type: number description: | @@ -465,6 +494,8 @@ components: minimum: 0 maximum: 100 example: 75.3 + x-stoplight: + id: 2pdqq572e0bqn measuredHumidity: type: number description: |- @@ -476,6 +507,8 @@ components: minimum: 0 maximum: 100 example: 95.6 + x-stoplight: + id: sbc345ti9vbqh measuredAirExchange: type: number description: | @@ -483,6 +516,8 @@ components: format: float minimum: 0 example: 15.4 + x-stoplight: + id: cnxt83lyksrxy airExchangeUnit: enum: - MQH @@ -495,41 +530,59 @@ components: **NB:** This is a conditional field. If `airExchange` is specified then this field is required example: MQH + x-stoplight: + id: dyvtso1h2dkn9 currentPhaseA: type: number description: The phase A current or average current in Amps format: float + x-stoplight: + id: 8ijzc1jwg0sfu currentPhaseB: type: number description: The phase B current or average current in Amps format: float + x-stoplight: + id: o81ugil8ilqhi currentPhaseC: type: number description: The phase C current or average current in Amps format: float + x-stoplight: + id: 0os5x4kg1ojl2 dischargePressure: type: number description: The discharge pressure in BarRelative units format: float + x-stoplight: + id: 8oe8wt29774ko dischargeTemperature: type: number description: The discharge temperature format: float example: -15 + x-stoplight: + id: r1k1sejd5sh22 evaporatorTemperature: type: number description: The evaporator temperature in CEL format: float + x-stoplight: + id: uye0yfqcx66r6 lineFrequency: type: number description: The mains power frequency in Hz format: float example: 50 + x-stoplight: + id: zf3uf41zsd9wh lineVoltage: type: number description: The mains power voltage in volts format: float example: 400 + x-stoplight: + id: yoc50twu46d2c returnProbe1Temperature: type: number description: |- @@ -538,6 +591,8 @@ components: COA UDM Key: P115 format: float example: -15 + x-stoplight: + id: zfwkcobgjx8th returnProbe2Temperature: type: number description: |- @@ -546,6 +601,8 @@ components: COA UDM Key: P116 format: float example: -15 + x-stoplight: + id: jkfoarx6n270o returnTemperature: type: number description: |- @@ -554,15 +611,21 @@ components: COA UDM Key: P5 format: float example: -15 + x-stoplight: + id: d849ygq6ekh19 suctionPressure: type: number description: The suction pressure in BarRelative units format: float + x-stoplight: + id: k0csuto6i2ceh suctionTemperature: type: number description: The suction temperature format: float example: -15 + x-stoplight: + id: cx93397p2p0oj supplySensor1Temperature: type: number description: |- @@ -571,6 +634,8 @@ components: COA UDM Key: P16 format: float example: -15 + x-stoplight: + id: 71ph34qp9uuyj supplySensor2Temperature: type: number description: |- @@ -579,6 +644,8 @@ components: COA UDM Key: P17 format: float example: -15 + x-stoplight: + id: c0r6a1lmx876v supplyTemperature: type: number description: |- @@ -587,6 +654,8 @@ components: COA UDM Key: P4 format: float example: -15 + x-stoplight: + id: dytsdx2qw4a3p setpoints: type: object properties: @@ -611,6 +680,8 @@ components: - temperatureUnit - o2 - co2 + x-stoplight: + id: 4tefsnmhqojmi reeferSettings: type: object properties: @@ -622,21 +693,31 @@ components: $ref: '#/components/schemas/efficiencySetting' required: - controlledAtmosphereMode + x-stoplight: + id: aqjjtj10pt6nm controlledAtmosphereMode: type: string description: |- The controlled atmosphere mode setting. COA UDM Key: P18 + x-stoplight: + id: ob3mgaauntpps isDefrosting: type: boolean description: Indicates if the device is defrosting + x-stoplight: + id: 3ukn8rtdt80k3 efficiencySetting: type: number description: The efficiency Setting (controller specific) COA UDM List 5.5.8 + x-stoplight: + id: ha53yg6py1bz5 unitModel: type: string description: 'The unit model specific to the maker, COA UDM 5.5.3 code list' + x-stoplight: + id: s9ryg72pvxgup device: title: device x-stoplight: From 29545816b1be4c79b01dc52c23cf4aaa74fe82e8 Mon Sep 17 00:00:00 2001 From: David Roff Date: Wed, 3 Jan 2024 15:08:10 +0000 Subject: [PATCH 04/22] remove stoplight ids --- rmo/v1/README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/rmo/v1/README.md b/rmo/v1/README.md index 2763450a1..63e5c983d 100644 --- a/rmo/v1/README.md +++ b/rmo/v1/README.md @@ -1,7 +1,3 @@ ---- -stoplight-id: ozs4u0b14gxnx ---- - ## Reefer Monitoring The DCSA Interface Standard for Reefer Monitoring is documented on [**DCSA Reefer Monitoring**](https://app.swaggerhub.com/apis/dcsaorg/DCSA_RMO) SwaggerHub. From 9aba590e583e50de3b2b40af4203d9f8f592beb7 Mon Sep 17 00:00:00 2001 From: David Roff Date: Wed, 3 Jan 2024 15:16:00 +0000 Subject: [PATCH 05/22] Update rmo/notification/v1/rmo_ntf_v1.0.0.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Helmø Larsen --- rmo/notification/v1/rmo_ntf_v1.0.0.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rmo/notification/v1/rmo_ntf_v1.0.0.yaml b/rmo/notification/v1/rmo_ntf_v1.0.0.yaml index b7ccae91d..f672be6ba 100644 --- a/rmo/notification/v1/rmo_ntf_v1.0.0.yaml +++ b/rmo/notification/v1/rmo_ntf_v1.0.0.yaml @@ -14,7 +14,7 @@ info: ### 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 Operational Reefer Monitoring 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). Please also [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments. + 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' From 263c8b09ec625e8f00a1ac8fd59fdf01ad8b478f Mon Sep 17 00:00:00 2001 From: David Roff Date: Wed, 3 Jan 2024 15:16:19 +0000 Subject: [PATCH 06/22] Update rmo/v1/reefer_v1.0.0-Beta-1.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Helmø Larsen --- rmo/v1/reefer_v1.0.0-Beta-1.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rmo/v1/reefer_v1.0.0-Beta-1.yaml b/rmo/v1/reefer_v1.0.0-Beta-1.yaml index 1f5a7b978..19a98279a 100644 --- a/rmo/v1/reefer_v1.0.0-Beta-1.yaml +++ b/rmo/v1/reefer_v1.0.0-Beta-1.yaml @@ -16,7 +16,7 @@ info: Calling this endPoint will return a list of events that fulfill the query parameters specified. The list returned is sorted in ascending (`ASC`) order based on the creation date-time of the event (`eventCreatedDateTime`). **This endPoint is mandatory to implement.** - For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/reefer-monitoring/v1#v1000B1). Please also [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments. + For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/reefer-monitoring/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) email: info@dcsa.org From fde420e0add7627fa3b5409de8a5792c2e856818 Mon Sep 17 00:00:00 2001 From: David Roff Date: Wed, 3 Jan 2024 15:16:39 +0000 Subject: [PATCH 07/22] Update rmo/notification/v1/rmo_ntf_v1.0.0.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Helmø Larsen --- rmo/notification/v1/rmo_ntf_v1.0.0.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rmo/notification/v1/rmo_ntf_v1.0.0.yaml b/rmo/notification/v1/rmo_ntf_v1.0.0.yaml index f672be6ba..ae40cf4c8 100644 --- a/rmo/notification/v1/rmo_ntf_v1.0.0.yaml +++ b/rmo/notification/v1/rmo_ntf_v1.0.0.yaml @@ -41,7 +41,7 @@ paths: required: true schema: type: string - example: 2.0.0-Beta-1 + example: 1.0.0-Beta-1 requestBody: description: | The payload used to create a [`Operational Reefer Notification`](#/OperationalReeferNotification) From 6e38a55a83d36f161cfe5e745bd3f65c058e12d8 Mon Sep 17 00:00:00 2001 From: David Roff Date: Wed, 3 Jan 2024 15:16:53 +0000 Subject: [PATCH 08/22] Update rmo/notification/v1/rmo_ntf_v1.0.0.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Helmø Larsen --- rmo/notification/v1/rmo_ntf_v1.0.0.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rmo/notification/v1/rmo_ntf_v1.0.0.yaml b/rmo/notification/v1/rmo_ntf_v1.0.0.yaml index ae40cf4c8..e033a749b 100644 --- a/rmo/notification/v1/rmo_ntf_v1.0.0.yaml +++ b/rmo/notification/v1/rmo_ntf_v1.0.0.yaml @@ -72,7 +72,7 @@ paths: alarmStatus: ACTIVE alarmNumber: '100' alarmSeverity: CRITICAL - declinedExample: + deactivedExample: summary: | A reefer container with a deactivated alarm notification description: | From 799a13a3271e61f926fbf0bf37c67dee2fff4847 Mon Sep 17 00:00:00 2001 From: David Roff Date: Wed, 3 Jan 2024 15:31:22 +0000 Subject: [PATCH 09/22] Update rmo/notification/v1/rmo_ntf_v1.0.0.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Helmø Larsen --- rmo/notification/v1/rmo_ntf_v1.0.0.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rmo/notification/v1/rmo_ntf_v1.0.0.yaml b/rmo/notification/v1/rmo_ntf_v1.0.0.yaml index e033a749b..5d0144917 100644 --- a/rmo/notification/v1/rmo_ntf_v1.0.0.yaml +++ b/rmo/notification/v1/rmo_ntf_v1.0.0.yaml @@ -104,7 +104,7 @@ paths: [SemVer](https://semver.org/) used to indicate the version of the consumer (the responding party). This is optional to provide. schema: type: string - example: 2.0.0-Beta-1 + example: 1.0.0-Beta-1 servers: - url: 'http://localhost:3000' parameters: [] From d4dcbc261aa0df6ca59183d226a5a25bff3c14fb Mon Sep 17 00:00:00 2001 From: David Roff Date: Wed, 3 Jan 2024 15:31:35 +0000 Subject: [PATCH 10/22] Update rmo/v1/reefer_v1.0.0-Beta-1.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Helmø Larsen --- rmo/v1/reefer_v1.0.0-Beta-1.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rmo/v1/reefer_v1.0.0-Beta-1.yaml b/rmo/v1/reefer_v1.0.0-Beta-1.yaml index 19a98279a..6a2fab373 100644 --- a/rmo/v1/reefer_v1.0.0-Beta-1.yaml +++ b/rmo/v1/reefer_v1.0.0-Beta-1.yaml @@ -16,7 +16,7 @@ info: Calling this endPoint will return a list of events that fulfill the query parameters specified. The list returned is sorted in ascending (`ASC`) order based on the creation date-time of the event (`eventCreatedDateTime`). **This endPoint is mandatory to implement.** - For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/reefer-monitoring/v1#v100B1). Please also [create a GitHub issue](https://github.com/dcsaorg/DCSA-OpenAPI/issues/new) if you have any questions/comments. + For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/blob/master/rmo/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) email: info@dcsa.org From f3c52a80d308cb864197b99cbd0bd11adb10b817 Mon Sep 17 00:00:00 2001 From: David Roff Date: Wed, 3 Jan 2024 15:36:44 +0000 Subject: [PATCH 11/22] comments from draft PR --- rmo/notification/v1/rmo_ntf_v1.0.0.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rmo/notification/v1/rmo_ntf_v1.0.0.yaml b/rmo/notification/v1/rmo_ntf_v1.0.0.yaml index 5d0144917..0101990b3 100644 --- a/rmo/notification/v1/rmo_ntf_v1.0.0.yaml +++ b/rmo/notification/v1/rmo_ntf_v1.0.0.yaml @@ -7,7 +7,8 @@ info: description: | API specification issued by DCSA.org. - Operational Reefer Monitoring Notifications for [DCSA OpenAPI specification for Operational Reefer Monitoring](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 changes state or is updated. + Operational Reefer Monitoring Notifications for [DCSA OpenAPI specification for Operational Reefer Monitoring](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. @@ -32,7 +33,7 @@ paths: summary: Send a new Operational Reefer Notification operationId: operational-reefer-notifications description: | - Creates a new [`Operational Reefer Notification`](#/OperationalReeferNotification). This endPoint is called whenever a `Reefer` that a consumer has subscribed to changes state or is updated. + 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 From 0c69fbbeafa4f7b20bfad1aaf39e8779a4d5820b Mon Sep 17 00:00:00 2001 From: David Roff Date: Wed, 3 Jan 2024 15:37:28 +0000 Subject: [PATCH 12/22] Change filename to align to beta state --- .../v1/{rmo_ntf_v1.0.0.yaml => rmo_ntf_v1.0.0-Beta-1.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rmo/notification/v1/{rmo_ntf_v1.0.0.yaml => rmo_ntf_v1.0.0-Beta-1.yaml} (100%) diff --git a/rmo/notification/v1/rmo_ntf_v1.0.0.yaml b/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml similarity index 100% rename from rmo/notification/v1/rmo_ntf_v1.0.0.yaml rename to rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml From f2ab0f941d3553f8d7e837056a537debe0b577cc Mon Sep 17 00:00:00 2001 From: David Roff Date: Mon, 29 Jan 2024 10:47:24 +0000 Subject: [PATCH 13/22] Added examples for the 'lite' and 'full' notifications to RMO NTF API --- .../v1/rmo_ntf_v1.0.0-Beta-1.yaml | 164 +++++++++++++++++- 1 file changed, 157 insertions(+), 7 deletions(-) diff --git a/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml b/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml index 0101990b3..a8312e7f2 100644 --- a/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml +++ b/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml @@ -7,13 +7,13 @@ info: description: | API specification issued by DCSA.org. - Operational Reefer Monitoring Notifications for [DCSA OpenAPI specification for Operational Reefer Monitoring](https://app.swaggerhub.com/apis/dcsaorg/DCSA_RMO/1.0.0-Beta-1) is a lightweight notification based on [CloudEvents](https://cloudevents.io/). + 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 Operational Reefer Monitoring Notification API. Further details can be found [here](https://developer.dcsa.org/#/http/guides/api-guides/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: @@ -53,7 +53,7 @@ paths: examples: alarmActivatedExample: summary: | - A reefer container with an activated alarm notification + 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: @@ -65,7 +65,7 @@ paths: datacontenttype: application/json data: notificationType: ALARM - equipmentReference: BICU4812097 + equipmentReference: APZU4812090 geoLocation: latitude: '48.858550' longitude: '2.294492' @@ -75,7 +75,7 @@ paths: alarmSeverity: CRITICAL deactivedExample: summary: | - A reefer container with a deactivated alarm notification + 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: @@ -87,7 +87,7 @@ paths: datacontenttype: application/json data: notificationType: ALARM - equipmentReference: BICU4812097 + equipmentReference: APZU4812090 geoLocation: latitude: '48.858550' longitude: '2.294492' @@ -95,6 +95,156 @@ paths: alarmStatus: INACTIVE alarmNumber: '100' alarmSeverity: CRITICAL + heartbeatExample: + summary: "A 'full' notification of the reefer measurements at a point in time" + description: Used to push the full payload to a subscriber for the Reefer Monitoring Operational (RMO) detailing the measurements and settings at point in time. + value: + alarms: + activeAlarmCount: 0 + controller: + dateTime: '2023-10-23T15:40:28Z' + hardwareVersion: 1.1.1 + maker: '900' + model: N99 + operatingState: '1' + serialNumber: '123456789' + softwareVersion: 1.1.1 + equipmentReference: APZU4812090 + equipmentOptions: + - N00 + - N05 + geoLocation: + latitude: '48.858550' + longitude: '2.294492' + isConnectedToPowerSource: true + lastDefrostDateTime: '2023-10-23T15:40:28Z' + measurements: + ambientTemperature: 12 + temperature: 5 + temperatureUnit: CEL + o2: 20 + co2: 25 + relativeHumidity: 98 + airExchange: 0 + airExchangeUnit: MQH + cargoProbe1Temperature: 6 + cargoProbe2Temperature: 6 + cargoProbe3Temperature: 6 + currentPhaseA: 15 + currentPhaseB: 15 + currentPhaseC: 15 + dischargePressure: 21 + dischargeTemperature: 10 + evaporatorTemperature: 10 + lineFrequency: 60 + lineVoltage: 400 + returnProbe1Temperature: 10 + returnProbe2Temperature: 10 + returnTemperature: 10 + suctionPressure: 60 + suctionTemperature: 10 + supplySensor1Temperature: 10 + supplySensor2Temperature: 10 + supplyTemperature: 10 + setpoints: + temperature: -15 + temperatureUnit: CEL + o2: 20 + co2: 25 + humidity: 96 + reeferSettings: + controlledAtmosphereMode: 'ON' + isDefrosting: false + efficiencySetting: 2 + unitModel: N00 + device: + deviceDateTime: '2023-12-10T10:34:12Z' + model: '100' + receivedDateTime: '2023-12-10T10:34:12Z' + isDeviceConnectedToPower: true + brand: '2' + inspection: + - inspectionType: REMOTE + inspectionDate: '2023-12-10T10:34:12Z' + expiryDate: '2023-12-10T10:34:12Z' + inspectionResult: PASSED + heartbeatExampleWithAlarm: + summary: "A 'full' notification of the reefer measurements at a point in time with activated alarm" + description: Used to push the full payload to a subscriber for the Reefer Monitoring Operational (RMO) detailing the measurements and settings at point in time. + value: + alarms: + activeAlarmCount: 0 + activeAlarms: + - alarmDate: '2024-01-23T15:40:28Z' + alarmNumber: N999 + alarmSeverity: ALARM + controller: + dateTime: '2023-10-23T15:40:28Z' + hardwareVersion: 1.1.1 + maker: '900' + model: N99 + operatingState: '1' + serialNumber: '123456789' + softwareVersion: 1.1.1 + equipmentReference: APZU4812090 + equipmentOptions: + - N00 + - N05 + geoLocation: + latitude: '48.858550' + longitude: '2.294492' + isConnectedToPowerSource: true + lastDefrostDateTime: '2023-10-23T15:40:28Z' + measurements: + ambientTemperature: 12 + temperature: 5 + temperatureUnit: CEL + o2: 20 + co2: 25 + relativeHumidity: 98 + airExchange: 0 + airExchangeUnit: MQH + cargoProbe1Temperature: 6 + cargoProbe2Temperature: 6 + cargoProbe3Temperature: 6 + currentPhaseA: 15 + currentPhaseB: 15 + currentPhaseC: 15 + dischargePressure: 21 + dischargeTemperature: 10 + evaporatorTemperature: 10 + lineFrequency: 60 + lineVoltage: 400 + returnProbe1Temperature: 10 + returnProbe2Temperature: 10 + returnTemperature: 10 + suctionPressure: 60 + suctionTemperature: 10 + supplySensor1Temperature: 10 + supplySensor2Temperature: 10 + supplyTemperature: 10 + setpoints: + temperature: -15 + temperatureUnit: CEL + o2: 20 + co2: 25 + humidity: 96 + reeferSettings: + controlledAtmosphereMode: 'ON' + isDefrosting: false + efficiencySetting: 2 + unitModel: N00 + device: + deviceDateTime: '2023-12-10T10:34:12Z' + model: '100' + receivedDateTime: '2023-12-10T10:34:12Z' + isDeviceConnectedToPower: true + brand: '2' + inspection: + - inspectionType: REMOTE + inspectionDate: '2023-12-10T10:34:12Z' + expiryDate: '2023-12-10T10:34:12Z' + inspectionResult: PASSED responses: '204': description: | @@ -205,7 +355,7 @@ components: 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: BICU4812097 + example: APZU4812090 geoLocation: type: object properties: From bedec4b5a7bf9057459991c81026aa82dd2d5f03 Mon Sep 17 00:00:00 2001 From: David Roff Date: Fri, 2 Feb 2024 17:07:16 +0000 Subject: [PATCH 14/22] removed 'full' notifications from the RMO_NTF api, responses now array of the object and added POST to handle heartbeat data to a carrier. --- .../v1/rmo_ntf_v1.0.0-Beta-1.yaml | 232 +++--------------- rmo/v1/rmo_v1.0.0-Beta-1.yaml | 207 +++++++++------- 2 files changed, 148 insertions(+), 291 deletions(-) diff --git a/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml b/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml index f038e806d..618b410c0 100644 --- a/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml +++ b/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml @@ -49,7 +49,9 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/OperationalReeferNotification' + type: array + items: + $ref: '#/components/schemas/OperationalReeferNotification' examples: alarmActivatedExample: summary: | @@ -57,208 +59,44 @@ paths: 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 + - 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 - heartbeatExample: - summary: "A 'full' notification of the reefer measurements at a point in time" - description: Used to push the full payload to a subscriber for the Reefer Monitoring Operational (RMO) detailing the measurements and settings at point in time. - 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: - alarms: - activeAlarmCount: 0 - controller: - dateTime: '2023-10-23T15:40:28Z' - hardwareVersion: 1.1.1 - maker: '900' - model: N99 - operatingState: '1' - serialNumber: '123456789' - softwareVersion: 1.1.1 - equipmentReference: APZU4812090 - equipmentOptions: - - N00 - - N05 - geoLocation: - latitude: '48.858550' - longitude: '2.294492' - isConnectedToPowerSource: true - lastDefrostDateTime: '2023-10-23T15:40:28Z' - measurements: - ambientTemperature: 12 - temperature: 5 - temperatureUnit: CEL - o2: 20 - co2: 25 - relativeHumidity: 98 - airExchange: 0 - airExchangeUnit: MQH - cargoProbe1Temperature: 6 - cargoProbe2Temperature: 6 - cargoProbe3Temperature: 6 - currentPhaseA: 15 - currentPhaseB: 15 - currentPhaseC: 15 - dischargePressure: 21 - dischargeTemperature: 10 - evaporatorTemperature: 10 - lineFrequency: 60 - lineVoltage: 400 - returnProbe1Temperature: 10 - returnProbe2Temperature: 10 - returnTemperature: 10 - suctionPressure: 60 - suctionTemperature: 10 - supplySensor1Temperature: 10 - supplySensor2Temperature: 10 - supplyTemperature: 10 - setpoints: - temperature: -15 - temperatureUnit: CEL - o2: 20 - co2: 25 - humidity: 96 - reeferSettings: - controlledAtmosphereMode: 'ON' - isDefrosting: false - efficiencySetting: 2 - unitModel: N00 - device: - deviceDateTime: '2023-12-10T10:34:12Z' - model: '100' - receivedDateTime: '2023-12-10T10:34:12Z' - isDeviceConnectedToPower: true - brand: '2' - inspection: - - inspectionType: REMOTE - inspectionDate: '2023-12-10T10:34:12Z' - expiryDate: '2023-12-10T10:34:12Z' - inspectionResult: PASSED - heartbeatExampleWithAlarm: - summary: "A 'full' notification of the reefer measurements at a point in time with activated alarm" - description: Used to push the full payload to a subscriber for the Reefer Monitoring Operational (RMO) detailing the measurements and settings at point in time. - 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: - alarms: - activeAlarmCount: 0 - activeAlarms: - - alarmDate: '2024-01-23T15:40:28Z' - alarmNumber: N999 - alarmSeverity: ALARM - controller: - dateTime: '2023-10-23T15:40:28Z' - hardwareVersion: 1.1.1 - maker: '900' - model: N99 - operatingState: '1' - serialNumber: '123456789' - softwareVersion: 1.1.1 - equipmentReference: APZU4812090 - equipmentOptions: - - N00 - - N05 - geoLocation: - latitude: '48.858550' - longitude: '2.294492' - isConnectedToPowerSource: true - lastDefrostDateTime: '2023-10-23T15:40:28Z' - measurements: - ambientTemperature: 12 - temperature: 5 - temperatureUnit: CEL - o2: 20 - co2: 25 - relativeHumidity: 98 - airExchange: 0 - airExchangeUnit: MQH - cargoProbe1Temperature: 6 - cargoProbe2Temperature: 6 - cargoProbe3Temperature: 6 - currentPhaseA: 15 - currentPhaseB: 15 - currentPhaseC: 15 - dischargePressure: 21 - dischargeTemperature: 10 - evaporatorTemperature: 10 - lineFrequency: 60 - lineVoltage: 400 - returnProbe1Temperature: 10 - returnProbe2Temperature: 10 - returnTemperature: 10 - suctionPressure: 60 - suctionTemperature: 10 - supplySensor1Temperature: 10 - supplySensor2Temperature: 10 - supplyTemperature: 10 - setpoints: - temperature: -15 - temperatureUnit: CEL - o2: 20 - co2: 25 - humidity: 96 - reeferSettings: - controlledAtmosphereMode: 'ON' - isDefrosting: false - efficiencySetting: 2 - unitModel: N00 - device: - deviceDateTime: '2023-12-10T10:34:12Z' - model: '100' - receivedDateTime: '2023-12-10T10:34:12Z' - isDeviceConnectedToPower: true - brand: '2' - inspection: - - inspectionType: REMOTE - inspectionDate: '2023-12-10T10:34:12Z' - expiryDate: '2023-12-10T10:34:12Z' - inspectionResult: PASSED + - 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: | diff --git a/rmo/v1/rmo_v1.0.0-Beta-1.yaml b/rmo/v1/rmo_v1.0.0-Beta-1.yaml index 975efa71b..6b082f286 100644 --- a/rmo/v1/rmo_v1.0.0-Beta-1.yaml +++ b/rmo/v1/rmo_v1.0.0-Beta-1.yaml @@ -16,6 +16,10 @@ info: Calling this endPoint will return a list of events that fulfill the query parameters specified. The list returned is sorted in ascending (`ASC`) order based on the creation date-time of the event (`eventCreatedDateTime`). **This endPoint is mandatory to implement.** + ### 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/blob/master/rmo/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) @@ -47,7 +51,9 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/reeferResponse' + type: array + items: + $ref: '#/components/schemas/reeferResponse' examples: 'Reefer data related to equipmentReference: ''APZU4812090''': description: | @@ -55,96 +61,117 @@ paths: GET /events?equipmentReference=APZU4812090 value: - alarms: - activeAlarmCount: 0 - activeAlarms: - - alarmDate: '2023-10-23T15:40:28Z' - alarmNumber: N999 - alarmSeverity: ALARM - controller: - dateTime: '2023-10-23T15:40:28Z' - hardwareVersion: 1.1.1 - maker: '900' - model: N99 - operatingState: '1' - serialNumber: '123456789' - softwareVersion: 1.1.1 - equipmentReference: APZU4812090 - equipmentOptions: - - N00 - - N05 - geoLocation: - latitude: '48.858550' - longitude: '2.294492' - isConnectedToPowerSource: true - lastDefrostDateTime: '2023-10-23T15:40:28Z' - measurements: - ambientTemperature: 12 - temperature: 5 - temperatureUnit: CEL - o2: 20 - co2: 25 - relativeHumidity: 98 - airExchange: 0 - airExchangeUnit: MQH - cargoProbe1Temperature: 6 - cargoProbe2Temperature: 6 - cargoProbe3Temperature: 6 - currentPhaseA: 15 - currentPhaseB: 15 - currentPhaseC: 15 - dischargePressure: 21 - dischargeTemperature: 10 - evaporatorTemperature: 10 - lineFrequency: 60 - lineVoltage: 400 - returnProbe1Temperature: 10 - returnProbe2Temperature: 10 - returnTemperature: 10 - suctionPressure: 60 - suctionTemperature: 10 - supplySensor1Temperature: 10 - supplySensor2Temperature: 10 - supplyTemperature: 10 - setpoints: - temperature: -15 - temperatureUnit: CEL - o2: 20 - co2: 25 - humidity: 96 - reeferSettings: - controlledAtmosphereMode: 'ON' - isDefrosting: false - efficiencySetting: 2 - unitModel: N00 - device: - deviceDateTime: '2023-12-10T10:34:12Z' - model: '100' - receivedDateTime: '2023-12-10T10:34:12Z' - isDeviceConnectedToPower: true - brand: '2' - inspection: - - inspectionType: REMOTE - inspectionDate: '2023-12-10T10:34:12Z' - expiryDate: '2023-12-10T10:34:12Z' - inspectionResult: PASSED + - alarms: + activeAlarmCount: 0 + activeAlarms: + - alarmDate: '2023-10-23T15:40:28Z' + alarmNumber: N999 + alarmSeverity: ALARM + controller: + dateTime: '2023-10-23T15:40:28Z' + hardwareVersion: 1.1.1 + maker: '900' + model: N99 + operatingState: '1' + serialNumber: '123456789' + softwareVersion: 1.1.1 + equipmentReference: APZU4812090 + equipmentOptions: + - N00 + - N05 + geoLocation: + latitude: '48.858550' + longitude: '2.294492' + isConnectedToPowerSource: true + lastDefrostDateTime: '2023-10-23T15:40:28Z' + measurements: + ambientTemperature: 12 + temperature: 5 + temperatureUnit: CEL + o2: 20 + co2: 25 + relativeHumidity: 98 + airExchange: 0 + airExchangeUnit: MQH + cargoProbe1Temperature: 6 + cargoProbe2Temperature: 6 + cargoProbe3Temperature: 6 + currentPhaseA: 15 + currentPhaseB: 15 + currentPhaseC: 15 + dischargePressure: 21 + dischargeTemperature: 10 + evaporatorTemperature: 10 + lineFrequency: 60 + lineVoltage: 400 + returnProbe1Temperature: 10 + returnProbe2Temperature: 10 + returnTemperature: 10 + suctionPressure: 60 + suctionTemperature: 10 + supplySensor1Temperature: 10 + supplySensor2Temperature: 10 + supplyTemperature: 10 + setpoints: + temperature: -15 + temperatureUnit: CEL + o2: 20 + co2: 25 + humidity: 96 + reeferSettings: + controlledAtmosphereMode: 'ON' + isDefrosting: false + efficiencySetting: 2 + unitModel: N00 + device: + deviceDateTime: '2023-12-10T10:34:12Z' + model: '100' + receivedDateTime: '2023-12-10T10:34:12Z' + isDeviceConnectedToPower: true + brand: '2' + inspection: + - inspectionType: REMOTE + inspectionDate: '2023-12-10T10:34:12Z' + expiryDate: '2023-12-10T10:34:12Z' + inspectionResult: PASSED '404': description: Not Found content: application/json: example: - httpMethod: "GET" - requestUri: "/events" - statusCode: 404, - statusCodeText: "Not Found" - statusCodeMessage: "Either no container found or no events to report" - errorDateTime: "2024-01-23T07:41:00+08:30" - errors: [ - { - errorCodeText: "No reefer data available", - errorCodeMessage: "Either no container found or no events to report for given reefer container" - } - ] + httpMethod: GET + requestUri: /events + statusCode: 404 + statusCodeText: Not Found + statusCodeMessage: Either no container found or no events to report + errorDateTime: '2024-01-23T07:41:00+08:30' + errors: + - errorCodeText: No reefer data available + errorCodeMessage: Either no container found or no events to report for given reefer container + post: + summary: Provide Reefer Information + operationId: postReefer + responses: + '200': + description: OK + description: Provide the current monitoring data available for reefer container(s) by pushing to the container operator. + parameters: + - schema: + type: string + in: header + name: API-Version + description: SemVer used to indicate the version of the contract (API version) returned. + requestBody: + content: + application/json: + schema: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/reeferResponse' + description: Reefer Response Body being provided + tags: + - Events tags: - name: Events description: Event operations @@ -467,8 +494,6 @@ components: COA UDM Key: P22 format: float example: -15 - x-stoplight: - id: wc2f5gny5b6uh temperatureUnit: enum: - CEL @@ -479,8 +504,6 @@ components: - CEL (Celsius) - FAH (Fahrenheit) example: CEL - x-stoplight: - id: ah5wmqyeej1z3 measuredO2: type: number description: |- @@ -491,8 +514,6 @@ components: minimum: 0 maximum: 100 example: 75.3 - x-stoplight: - id: 0n7a3ceoixoh0 measuredCo2: type: number description: | @@ -503,8 +524,6 @@ components: minimum: 0 maximum: 100 example: 75.3 - x-stoplight: - id: 2pdqq572e0bqn measuredHumidity: type: number description: |- From 434bd7f6d7fba1f2228a6a38e789d33448e14256 Mon Sep 17 00:00:00 2001 From: David Roff Date: Fri, 2 Feb 2024 17:15:24 +0000 Subject: [PATCH 15/22] Create README.md added readme for RMO_NTF --- rmo/notification/v1/README.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 rmo/notification/v1/README.md diff --git a/rmo/notification/v1/README.md b/rmo/notification/v1/README.md new file mode 100644 index 000000000..d57976bd1 --- /dev/null +++ b/rmo/notification/v1/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 From 7afdddd7458758da391a023a9e46abd1c2dbcddc Mon Sep 17 00:00:00 2001 From: David Roff Date: Fri, 2 Feb 2024 17:15:38 +0000 Subject: [PATCH 16/22] Update README.md Updat Readme for RMO for consistency --- rmo/v1/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rmo/v1/README.md b/rmo/v1/README.md index 63e5c983d..d938d5703 100644 --- a/rmo/v1/README.md +++ b/rmo/v1/README.md @@ -1,6 +1,6 @@ -## Reefer Monitoring +## Reefer Monitoring Operational (RMO) -The DCSA Interface Standard for Reefer Monitoring is documented on [**DCSA Reefer Monitoring**](https://app.swaggerhub.com/apis/dcsaorg/DCSA_RMO) SwaggerHub. +The DCSA Interface Standard for Reefer Monitoring is documented on [**SwaggerHub.**](https://app.swaggerhub.com/apis/dcsaorg/DCSA_RMO) [Release v1.0.0-Beta-1 (Unpublished)](https://app.swaggerhub.com/apis/dcsaorg/DCSA_RMO/1.0.0-Beta-1) --- From 0aac595d411607c2d46927515d4a350fa7267d44 Mon Sep 17 00:00:00 2001 From: David Roff Date: Mon, 5 Feb 2024 11:11:05 +0000 Subject: [PATCH 17/22] Update rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Helmø Larsen --- rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml b/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml index 618b410c0..f874cbeca 100644 --- a/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml +++ b/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml @@ -230,6 +230,7 @@ components: 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 From fb913171083d0c6524149ec3bff1eb28b145e372 Mon Sep 17 00:00:00 2001 From: David Roff Date: Mon, 5 Feb 2024 11:11:41 +0000 Subject: [PATCH 18/22] Update rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Helmø Larsen --- rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml b/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml index f874cbeca..ad9507870 100644 --- a/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml +++ b/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml @@ -26,7 +26,7 @@ tags: servers: - url: 'http://localhost:3000' paths: - /v2/operational-reefer-notifications: + /v1/operational-reefer-notifications: post: tags: - Notifications From 66c70d9b26ff341eeda84ea13f3c6b82b5f0aadb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Helm=C3=B8=20Larsen?= Date: Mon, 5 Feb 2024 13:35:36 +0100 Subject: [PATCH 19/22] Fix APIVersionHeader link --- rmo/v1/rmo_v1.0.0-Beta-1.yaml | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/rmo/v1/rmo_v1.0.0-Beta-1.yaml b/rmo/v1/rmo_v1.0.0-Beta-1.yaml index 6b082f286..b51c2496d 100644 --- a/rmo/v1/rmo_v1.0.0-Beta-1.yaml +++ b/rmo/v1/rmo_v1.0.0-Beta-1.yaml @@ -44,7 +44,14 @@ paths: in: query name: activeControllerAlarms description: Will filter by all live reefers with one or more active alarms - - $ref: ../../models/CommonComponents.yaml#/components/parameters/APIVersionHeader + - 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 responses: '200': description: Successful operation From 2363c85e3ccd04d865f39b03d568642cea0dc923 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Helm=C3=B8=20Larsen?= Date: Mon, 5 Feb 2024 13:37:11 +0100 Subject: [PATCH 20/22] Add v1 to /events endPoints --- rmo/v1/rmo_v1.0.0-Beta-1.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rmo/v1/rmo_v1.0.0-Beta-1.yaml b/rmo/v1/rmo_v1.0.0-Beta-1.yaml index b51c2496d..2e0965c3a 100644 --- a/rmo/v1/rmo_v1.0.0-Beta-1.yaml +++ b/rmo/v1/rmo_v1.0.0-Beta-1.yaml @@ -29,7 +29,7 @@ info: url: 'http://www.apache.org/licenses/LICENSE-2.0.html' name: Apache 2.0 paths: - /events: + /v1/events: get: tags: - Events @@ -66,7 +66,7 @@ paths: description: | To retrieve the reefer data for a specific `equipmentReference` the following request could be made: - GET /events?equipmentReference=APZU4812090 + GET /v1/events?equipmentReference=APZU4812090 value: - alarms: activeAlarmCount: 0 @@ -147,7 +147,7 @@ paths: application/json: example: httpMethod: GET - requestUri: /events + requestUri: /v1/events statusCode: 404 statusCodeText: Not Found statusCodeMessage: Either no container found or no events to report From 8a8d1b0b22ee50669f83bcc309a3a77cddffdf0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Helm=C3=B8=20Larsen?= Date: Mon, 5 Feb 2024 14:27:15 +0100 Subject: [PATCH 21/22] Move README.me to the v1/notification folder --- rmo/{notification/v1 => v1/notification}/README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rmo/{notification/v1 => v1/notification}/README.md (100%) diff --git a/rmo/notification/v1/README.md b/rmo/v1/notification/README.md similarity index 100% rename from rmo/notification/v1/README.md rename to rmo/v1/notification/README.md From 211bf468bd3a6b3a52fed625970686d8b01022ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Helm=C3=B8=20Larsen?= Date: Mon, 5 Feb 2024 14:30:02 +0100 Subject: [PATCH 22/22] Move rmo_ntf_v1.0.0-Beta-1.yaml to /v1/notifications --- .../v1 => v1/notification}/rmo_ntf_v1.0.0-Beta-1.yaml | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename rmo/{notification/v1 => v1/notification}/rmo_ntf_v1.0.0-Beta-1.yaml (100%) diff --git a/rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml b/rmo/v1/notification/rmo_ntf_v1.0.0-Beta-1.yaml similarity index 100% rename from rmo/notification/v1/rmo_ntf_v1.0.0-Beta-1.yaml rename to rmo/v1/notification/rmo_ntf_v1.0.0-Beta-1.yaml