OVS_HUB_NTF_v1.0.0.yaml

openapi: 3.0.3
info:
  version: 1.0.0
  title: OVS Hub Notification and Subscriptions
  description: |
    <h1>DCSA OVS Hub OpenAPI Specification for notifications and subscriptions</h1>

    Notifications for DCSA OVS Hub OpenAPI subscriptions are lightweight notifications based on [CloudEvents](https://cloudevents.io/). The `POST` endpoint of the consumer is called whenever a `Service`, `Vessel` or `Location` that is being subscribed to changes state or is updated.

    It is also possible to set up subscriptions. A subscription can be set up to push events to a callbackUrl defined as part of the subscription or by an email. It is not possible to define the email as part of the subscription - the email used is the email address associated with the authenticated user.

    Subscriptions support sending notifications for all changes the customer is authorized to see. It is possible to only send notifications for specific events - in order to do so - filters must be used when setting up a subscription. See the [subscription](https://app.swaggerhub.com/apis/dcsaorg/DCSA_OVS_NTF/1.0.0#/Subscription) section for more info.
  contact:
    name: Digital Container Shipping Association (DCSA)
    url: 'https://dcsa.org'
    email: info@dcsa.org
tags:
  - name: Notification
    description: |
      Endpoint implemented by the receiver of the Notifications (Terminals, Carriers, etc)
  - name: Subscription
    description: |
      Endpoints implemented by the OVS Hub for the customer to set up subscriptions
  - name: Secret
    description: |
      Endpoint implemented by the OVS Hub for the customer to update the secret
paths:
  '/{callbackUrl}':
    post:
      tags:
        - Notification
      summary: Send notification
      operationId: post-notification
      description: |
        Creates a new `Notification`. This endpoint is called whenever a `Service`, `Vessel` or `Location` that a consumer has subscribed to is updated. The `callbackUrl` is defined as part of the subscription.

          **👉 Important:** This endpoint is to be implemented by a **consumer** of the **OVS Hub API** in order to **receive Notifications**.
      parameters:
        - name: callbackUrl
          in: path
          required: true
          description: |
            The endpoint specifying where OVS Hub sends the notification to the customer. The callback can contain customer defined query parameters.

            The `callbackUrl` **MUST** be an open endpoint for OVS Hub to call when sending a notification. OVS Hub does not send any authentication information apart from what is in the `callbackUrl`. The receiver **MUST** validate the authenticity of the notification by looking at the `Notification-Signature` header.
          schema:
            type: string
            format: uri
            example: https://myserver.com/send/callback/here?myInternalId=123
        - name: Request-Id
          in: header
          required: true
          description: |
            The `Request-Id` which is included in the encoded `Notification-Signature`.
            
            When receiving a notification the receiver **MUST** validate the "uniqueness" of the `Request-Id`. If a notification has already been sent with the `Request-Id` then the request **MUST** be rejected.

            **Note:** It is not necessary to store the `Request-Id` for more than 5 minutes as all other cases are covered by the `Signature-Timestamp` header
          schema:
            type: string
            format: ulid
            example: 01KKH4JGKBPT6J9VJX1WXKWPGK
        - name: Signature-Timestamp
          in: header
          required: true
          description: |
            The `Signature-Timestamp` which is included in the encoded `Notification-Signature`.
            
            When receiving a notification the receiver **MUST** validate the "freshness" of the timestamp. If it is older than 5 minutes, or too far in the future, it **MUST** be rejected.

                abs(now_utc - timestamp_utc) <= 300 seconds

            **Note:** This value is to be used when calculating the `Notification-Signature` on the receiver side.
          schema:
            type: string
            format: date-time
            example: 2025-01-23T01:23:45Z
        - name: Notification-Signature
          in: header
          required: true
          description: |
            The `Notification-Signature` is used to more confidently verify whether requests from OVS Hub are authentic. The header has the following format: 

                Notification-Signature: sha256=<signature>

            When OVS Hub sends a notification, the notification **MUST** be checked to make sure it's authentic. This is done by computing a signature.

            The `signature` is calculated by calculating a **HMAC_SHA256** using the `secret` (defined when setting up a subscription) on the `Signature-Timestamp` header (*unredacted*) concatenated with a dot (`.`) concatenated with the `Request-Id` header concatenated with a dot (`.`) concatenated with the `request body`

                signature = HMAC_SHA256(secret, Signature-Timestamp + "." + Request-Id + "." + request-body)

            The signature **MUST** cover the entire request body of the request. Before the signature is created the request body **MUST** be in the [RFC 8785](https://datatracker.ietf.org/doc/html/rfc8785) canonical form. The content **MUST** be decoded into bytes using the UTF-8 encoding before computing the signature.
            
            **Note:** None of the HTTP headers nor the request URL is covered by the signature.

            ## Example
            
            A concrete example of how the `Notification-Signature` header could look like for:
              * `secret`: OWY4YzdhNGQ=
              * `Signature-Timestamp`: March 12, 2026 at 14:47:00Z
              * `Request-Id`: 01KKH4JGKBPT6J9VJX1WXKWPGK
              * `request-body`: {"lastName":"Doe" , "firstName":"John",  "age":40}
            
            would be:

                signature = HMAC_SHA256(Base64Decode(OWY4YzdhNGQ=), '2026-03-12T14:47:00Z.01KKH4JGKBPT6J9VJX1WXKWPGK.{"age":40,"firstName":"John","lastName":"Doe"}')

            The `Notification-Signature` header would then look like this:

                Notification-Signature: sha256=8d3a7837713e319d1466139903ffd5b1b8d96f6a769f6d53c03a29dc5c3f3630
          schema:
            type: string
            pattern: ^sha256=[A-Fa-f0-9]{64}$
            maxLength: 71
            minLength: 71
            example: sha256=8d3a7837713e319d1466139903ffd5b1b8d96f6a769f6d53c03a29dc5c3f3630
        - $ref: '#/components/parameters/Api-Version-Major'
      requestBody:
        description: |
          Enough information for a recipient to evaluate if more information should be fetched.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Notification'
      responses:
        '204':
          description: No Content
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
  /subscriptions:
    get:
      tags:
        - Subscription
      summary: Receive a list of your active subscriptions
      operationId: get-all-subscriptions
      description: |
        Get a list of all subscriptions.
      parameters:
        - name: limit
          in: query
          description: |
            Maximum number of `Subscriptions` to include in each page of the response.
          example: 5
          schema:
            type: integer
            format: int32
            default: 10
            example: 10
            minimum: 1
        - name: offset
          in: query
          example: 0
          description: |
            The (zero-based) offset of the first item returned in the collection. In zero-based indexing, 0 is a valid value.
          schema:
            type: integer
            format: int32
            default: 0
            example: 10
            minimum: 0
        - $ref: '#/components/parameters/Api-Version-Major'
      responses:
        '200':
          description: |
            Returns a list of subscriptions you are authorized to see.
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Subscription'
        default:
          description: |
            For other errors the error object should be populated with relevant information
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                tooManyRequestsExample:
                  summary: |
                    Making too many Subscription Requests
                  description: |
                    Calling the endpoint

                        GET /subscriptions

                    too many times within a time period.
                  value:
                    httpMethod: GET
                    requestUri: /subscriptions
                    statusCode: 429
                    statusCodeText: Too Many Requests
                    statusCodeMessage: |
                      Too many requests to fetch subscriptions have been made. Please try again in 1 hour
                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                    errorDateTime: '2026-03-01T09:41:00Z'
                    errors:
                      - errorCodeText: Max number of subscription requests reached
                        errorCodeMessage: A maximum of 10 subscription requests can be fetched per hour
    post:
      tags:
        - Subscription
      summary: Create a subscription
      operationId: post-subscription
      description: |
        Creates a new subscription. This endpoint specifies when a Notification is sent. It is possible to specify on multiple levels:
          - **Service**: it is possible to only be notified when something in a specific Service changes
          - **Vessel IMO**: it is possible to only be notified when something related to a specific Vessel changes
          - **Location**: it is possible to only be notified when something related to a specific Location changes

        It is possible to specify the above groups as **filters**. If nothing is specified for: `Service`, `Vessel` or `Location` then anything you are authorized to see will be sent to you.

        If `callbackUrl` is specified, when setting up a subscription, the notification will be pushed to the

            POST {{callbackUrl}}
        
        endpoint of the consumer. If `callbackUrl` is omitted as part of the subscription, a notification will be sent via email to the authenticated user. Email is defined as part of the user-profile.

        When a notification is sent, it is the responsibility of the consumer to go to OVS Hub, either via the API or the UI, to get more information.
      parameters:
        - $ref: '#/components/parameters/Api-Version-Major'
      requestBody:
        description: |
          The parameters used to configure the subscription and send notifications.
          
          All values in the subscription (except: `callbackUrl` and `secret`) will be used as filters when sending notifications. All specified filters must be met in order for a notification to be sent. A logical **AND** is used between filters. So specifying
          
              carrierServiceCodes = 'FE1'
              AND
              vesselIMONumbers = '12345678'
          
          means that the notifications sent for this subscription **MUST** be for service `FE1` (*carrierServiceCode='FE1'*) **and** vessel IMO `12345678` (*vesselIMONumber='12345678'*). If all filters are not fulfilled - then the notification will not be sent.
          
          Filters that are specified as lists use logical **OR** between list values. So
          
              carrierServiceCodes = ['FE1','DR02']
          
          means that notifications sent will match **either** `FE1` **OR** `DR02` carrierServiceCodes.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionBodyWithSecret'
            examples:
              callbackExample:
                summary: |
                  Subscription using callback for Vessel changes
                description: |
                  A subscription setup using the `callbackUrl` in order for notifications to be sent to:

                    POST https://api.myserver.com/notifications?myId=123

                  The notification is only triggered when changes occur to `vesselIMONumber`: 9321483 or 9929429 that occur maximum 1 week in the future (`weekRange` = 1)
                value:
                  notificationChannel:
                    callbackUrl: https://api.myserver.com/notifications?myId=123
                    secret: MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDM2NTc4NjIzODk3NDY5MDgyNzM0OTg3MTIzNzg2NA==
                  weekRange: 1
                  vesselIMONumbers:
                    - '9321483'
                    - '9929429'
              emailAllExample:
                summary: |
                  Subscription using emails to be notified about everything
                description: |
                  A subscription setup using the email channel to be notified about all authorized changes occurring within 6 weeks in the future.
                value:
                  notificationChannel:
                    useEmail: true
                  weekRange: 6
              emailServiceExample:
                summary: |
                  Subscription using emails to be notified about Service changes
                description: |
                  A subscription setup using the email channel to be notified about changes to `carrierServiceCodes`: FE1 and DR001.
                value:
                  notificationChannel:
                    useEmail: true
                  carrierServiceCodes:
                    - FE1
                    - DR001
                  weekRange: 3
      responses:
        '201':
          description: Subscription created
          headers:
            API-Version:
              schema:
                type: string
                example: 1.0.0
              description: |
                SemVer used to indicate the version of the contract (API version) returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        default:
          description: |
            For other errors the error object should be populated with relevant information
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                tooManyRequestsExample:
                  summary: |
                    Making too many Subscription Requests
                  description: |
                    Calling the endpoint

                        POST /subscriptions

                    too many times within a time period.

                    **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example"
                  value:
                    httpMethod: POST
                    requestUri: /subscriptions
                    statusCode: 429
                    statusCodeText: Too Many Requests
                    statusCodeMessage: |
                      Too many requests to create a subscription have been made. Please try again in 1 hour
                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                    errorDateTime: '2026-03-01T09:41:00Z'
                    errors:
                      - errorCode: 7003
                        errorCodeText: Max number of subscriptions created
                        errorCodeMessage: A maximum of 10 subscriptions can be created per hour
  /subscriptions/{subscriptionReference}:
    get:
      tags:
        - Subscription
      summary: Find a subscription by subscription reference
      operationId: get-subscription
      description: |
        Get the subscription matching `subscriptionReference`.
      parameters:
        - name: subscriptionReference
          in: path
          required: true
          description: |
            Fetches the subscription matching the `subscriptionReference` provided.
          example: 01KJZDQ1CC6HQYP8V2NE2MPRNC
          schema:
            type: string
            format: ulid
            maxLength: 26
        - $ref: '#/components/parameters/Api-Version-Major'
      responses:
        '200':
          description: Subscription returned
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        default:
          description: |
            For other errors the error object should be populated with relevant information
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                tooManyRequestsExample:
                  summary: |
                    Making too many Subscription Requests
                  description: |
                    Calling the endpoint

                        GET /subscriptions/{subscriptionReference}

                    too many times within a time period.

                    **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example"
                  value:
                    httpMethod: GET
                    requestUri: /subscriptions/{subscriptionReference}
                    statusCode: 429
                    statusCodeText: Too Many Requests
                    statusCodeMessage: |
                      Too many requests to fetch subscription with subscriptionReference: {subscriptionReference} have been made. Please try again in 1 hour
                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                    errorDateTime: '2026-03-01T09:41:00Z'
                    errors:
                      - errorCode: 7003
                        errorCodeText: Maximum number of subscription requests
                        errorCodeMessage: A maximum of 10 subscription requests can be made per hour
    delete:
      tags:
        - Subscription
      summary: Stop a subscription by subscription reference
      operationId: delete-subscription
      description: |
        Deletes the subscription with `subscriptionReference`.
      parameters:
        - name: subscriptionReference
          in: path
          required: true
          description: |
            Fetches the subscription matching the `subscriptionReference` provided.
          example: 01KJZDQ1CC6HQYP8V2NE2MPRNC
          schema:
            type: string
            format: ulid
            maxLength: 26
        - $ref: '#/components/parameters/Api-Version-Major'
      responses:
        '204':
          description: Subscription stopped
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
        default:
          description: |
            For other errors the error object should be populated with relevant information
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                tooManyRequestsExample:
                  summary: |
                    Making too many Subscription Requests
                  description: |
                    Calling the endpoint

                        DELETE /subscriptions/{subscriptionReference}

                    too many times within a time period.

                    **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example"
                  value:
                    httpMethod: DELETE
                    requestUri: /subscriptions/{subscriptionReference}
                    statusCode: 429
                    statusCodeText: Too Many Requests
                    statusCodeMessage: |
                      Too many requests to delete subscription with subscriptionReference: {subscriptionReference} have been made. Please try again in 1 hour
                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                    errorDateTime: '2026-03-01T09:41:00Z'
                    errors:
                      - errorCode: 7003
                        errorCodeText: Maximum number of subscription requests
                        errorCodeMessage: A maximum of 10 subscription delete requests can be made per hour
    put:
      tags:
        - Subscription
      summary: Update a subscription by subscription reference
      operationId: put-subscription
      description: |
        Updates the subscription with `subscriptionReference`.
      parameters:
        - name: subscriptionReference
          in: path
          required: true
          description: |
            Fetches the subscription matching the `subscriptionReference` provided.
          example: 01KJZDQ1CC6HQYP8V2NE2MPRNC
          schema:
            type: string
            format: ulid
            maxLength: 26
        - $ref: '#/components/parameters/Api-Version-Major'
      requestBody:
        description: Parameters used to configure the subscription
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
      responses:
        '200':
          description: Subscription updated
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        default:
          description: |
            For other errors the error object should be populated with relevant information
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                tooManyRequestsExample:
                  summary: |
                    Making too many Subscription Requests
                  description: |
                    Calling the endpoint

                        PUT /subscriptions/{subscriptionReference}

                    too many times within a time period.

                    **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example"
                  value:
                    httpMethod: PUT
                    requestUri: /subscriptions/{subscriptionReference}
                    statusCode: 429
                    statusCodeText: Too Many Requests
                    statusCodeMessage: |
                      Too many requests to update subscription with subscriptionReference: {subscriptionReference} have been made. Please try again in 1 hour
                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                    errorDateTime: '2026-03-01T09:41:00Z'
                    errors:
                      - errorCode: 7003
                        errorCodeText: Maximum number of subscription requests
                        errorCodeMessage: A maximum of 10 subscription update requests can be made per hour
  /subscriptions/{subscriptionReference}/secret:
    put:
      tags:
        - Secret
      summary: Resets the Secret on an existing subscription
      operationId: put-secret
      description: |
        Updates the secret of subscription with `subscriptionReference`.
      parameters:
        - name: subscriptionReference
          in: path
          required: true
          description: |
            Updates the subscription matching the `subscriptionReference` provided.
          example: 01KJZDQ1CC6HQYP8V2NE2MPRNC
          schema:
            type: string
            format: ulid
            maxLength: 26
        - $ref: '#/components/parameters/Api-Version-Major'
      requestBody:
        description: Parameters used to configure the subscription
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                secret:
                  type: string
                  format: byte
                  description: |
                    A Base64 encoded secret sent to the OVS Hub from the customer.
                    It is used to compute the contents of the `Notification-Signature` header every time a notification is sent.
                  example: 'MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDM2NTc4NjIzODk3NDY5MDgyNzM0OTg3MTIzNzg2NA=='
      responses:
        '204':
          description: Secret updated
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
        default:
          description: |
            For other errors the error object should be populated with relevant information
          headers:
            API-Version:
              $ref: '#/components/headers/API-Version'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                tooManyRequestsExample:
                  summary: |
                    Making too many Subscription Secret Requests
                  description: |
                    Calling the endpoint

                        PUT /subscriptions/{subscriptionReference}/secret

                    too many times within a time period.

                    **NB**: `errorCode` not yet standardized by DCSA. Value `7003` is just a "random example"
                  value:
                    httpMethod: PUT
                    requestUri: /subscriptions/{subscriptionReference}/secret
                    statusCode: 429
                    statusCodeText: Too Many Requests
                    statusCodeMessage: |
                      Too many requests to update subscription secret with subscriptionReference: {subscriptionReference} have been made. Please try again in 1 hour
                    providerCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962
                    errorDateTime: '2026-03-01T09:41:00Z'
                    errors:
                      - errorCode: 7003
                        errorCodeText: Max number of subscriptions secret requests
                        errorCodeMessage: A maximum of 10 subscription secret update requests can be made per hour

components:
  headers:
    API-Version:
      schema:
        type: string
        example: 1.0.0
      description: |
        SemVer used to indicate the version of the contract (API version) returned.
  parameters:
    Api-Version-Major:
      name: API-Version
      in: header
      required: true
      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.

        The purpose of this is for OVS Hub to know which version of the API the caller is on.
      schema:
        type: string
        example: 1.0.0
  schemas:
    Subscription:
      type: object
      title: Subscription
      description: |
        ...
      properties:
        subscriptionReference:
          type: string
          format: ulid
          maxLength: 26
          description: |
            The OVS Hub assigned unique reference to the subscription.
          example: 01KJZDQ1CC6HQYP8V2NE2MPRNC
        notificationChannel:
          type: object
          description: |
            Defines the channel where a matched notification is sent. At least one of the possible properties **MUST** be provided:
              - `callbackUrl`
              - `useEmail`
          properties:
            callbackUrl:
              type: string
              format: uri
              description: |
                The endpoint where OVS Hub should send the notification to the customer. The callback can contain query parameters uniquely identifying the originator of the events.

                The `callbackUrl` **MUST** be an open endpoint for OVS Hub to call when sending a notification. The receiver **MUST** validate the authenticity of the notification by looking at the `Notification-Signature` header.

                **Condition:** If `callbackUrl` is provided, the `secret` property must also be provided. It can be updated via the [update-secret](https://app.swaggerhub.com/apis/dcsaorg/DCSA_OVS_NTF/1.0.0#/Secret/put-secret) endpoint.
              example: https://myserver.com/send/callback/here?shipperRef=myID123
            useEmail:
              type: boolean
              description: |
                If `true` a possible notification match will be sent to the email address of the user who has created the subscription.
              example: true
        weekRange:
          type: integer
          format: int32
          description: |
            Number of weeks into the future for which this subscription will send notifications. If the number is `4` it means that any changes further in the future than 4 weeks from now will **not** be sent.
          example: 4
        carrierServiceCodes:
          type: array
          description: |
            An array of **carrier-specific codes** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.

            If this property is empty, you will be notified for all `carrierServiceCodes` that have changes you are authorized to see.
          items:
            type: string
            pattern: ^\S(?:.*\S)?$
            maxLength: 11
            description: |
              The carrier-specific code of the service for which the schedule details are published.
            example: FE1
          example:
            - FE1
            - DR01
        universalServiceReferences:
          type: array
          description: |
            An array of **universal service references** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.

            If this property is empty, you will be notified for all `universalServiceReferences` that have changes you are authorized to see.
          items:
            type: string
            pattern: ^SR\d{5}[A-Z]$
            maxLength: 8
            minLength: 8
            example: SR12345A
          example:
            - SR12345A
            - SR33322T
            - SR03732R
        carrierSMDGCodes:
          type: array
          description: |
            An array of **carrier SMDG codes** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.

            If this property is empty, you will be notified for all `carrierSMDGCodes` that have changes you are authorized to see.
          items:
            type: string
            maxLength: 10
            description: |
              The carrier code based on SMDG Liner Code List.
            example: MSK
          example:
            - MSK
            - EMC
        vesselNames:
          type: array
          description: |
            An array of **vessel names** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.

            If this property is empty, you will be notified for all `vesselNames` that have changes you are authorized to see.
          items:
            type: string
            maxLength: 35
            description: |
              The name of the Vessel given by the Vessel Operator and registered with IMO.

              **Note:** In case the vessel is a "dummy vessel" (`isDummyVessel='true'`) then the following recommendations should be followed:
              
              Dummy vessel names should begin with the **SMDG Operating Carrier Code** to ensure uniqueness across carriers.
              The suffix can be **alphanumeric** and up to **10 characters long**, allowing each carrier to use internal naming conventions (e.g., `MSKTBN1`, `CMATEMP01`, `MSCX01A`).

              This approach:
              - Ensures consistency and uniqueness across carriers
              - Allows flexibility in local implementations
              - Avoids the need to assign dummy IMO numbers
              - Maintains the role of the dummy vessel name as a **stable and persistent identifier** throughout the planning process
            example: King of the Seas
          example:
            - King of the Seas
            - Express 001
        vesselIMONumbers:
          type: array
          description: |
            An array of **vessel IMO numbers** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.

            If this property is empty, you will be notified for all `vesselIMONumbers` that have changes you are authorized to see.
          items:
            type: string
            pattern: ^\d{7,8}$
            minLength: 7
            maxLength: 8
            description: |
              The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel

              **Condition:** If `isDummyVessel` is `false` - at least one of `vesselIMONumber` or `MMSINumber` **MUST** be specified in order to identify the `Vessel`. It is also acceptable to provide both properties. If `isDummyVessel` is `true` it is optional to provide this property.
            example: '9321483'
          example:
            - '9321483'
            - '12345678'
        MMSINumbers:
          type: array
          description: |
            An array of **MMSI numbers** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.

            If this property is empty, you will be notified for all `MMSINumbers` that have changes you are authorized to see.
          items:
            type: string
            pattern: ^\d{9}$
            minLength: 9
            maxLength: 9
            description: |
              Maritime Mobile Service Identities (MMSIs) are nine-digit numbers used by maritime digital selective calling (DSC), automatic identification systems (AIS) and certain other equipment to uniquely identify a ship or a coast radio station.

              **Condition:** If `isDummyVessel` is `false` - at least one of `vesselIMONumber` or `MMSINumber` **MUST** be specified in order to identify the `Vessel`. It is also acceptable to provide both properties.  If `isDummyVessel` is `true` it is optional to provide this property.
            example: '278111222'
          example:
            - '278111222'
            - '278173294'
            - '234422543'
        locations:
          type: array
          minItems: 1
          description: |
            An array of **UNLocationCode and/or facilitySMDGCode combinations** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the objects when matching.

            If this property is empty, you will be notified for all `locations` that have changes you are authorized to see.
          items:
            type: object
            description: |
              It is possible to provide the `UNLocationCode`, the `facilitySMDGCode` or both when specifying the location.

              If multiple `UNLocationCode` or `facilitySMDGCode` values need to be provided, then they must be specified as separate objects in the `locations` array.

              **Condition:** At least one of `UNLocationCode` and/or `facilitySMDGCode` **MUST** be specified, both are also allowed.
            properties:
              UNLocationCode:
                type: string
                pattern: ^[A-Z]{2}[A-Z2-9]{3}$
                minLength: 5
                maxLength: 5
                description: |
                  The UN Location code specifying where the place is located. The pattern used must be

                  - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)
                  - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used

                  More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)
                example: NLAMS
              facilitySMDGCode:
                type: string
                maxLength: 6
                description: |
                  The code used for identifying the specific facility. This code does not include the UN Location Code.

                  The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/wp-content/uploads/Codelists/Terminals/SMDG-Terminal-Code-List-v20210401.xlsx)
                example: ACT
          example:
            - UNLocationCode: NLAMS
              facilitySMDGCode: APMT
            - UNLocationCode: DEHAM
            - facilitySMDGCode: APMT
      required:
        - subscriptionReference
        - notificationChannel
        - weekRange

    SubscriptionBodyWithSecret:
      type: object
      title: Subscription with Secret
      description: |
        ...
      properties:
        notificationChannel:
          type: object
          title: Notification Channel
          description: |
            Defines the channel where a matched notification is sent. At least one of the possible properties **MUST** be provided:
              - `callbackUrl` and `secret`
              - `useEmail`
          properties:
            callbackUrl:
              type: string
              format: uri
              description: |
                The endpoint where OVS Hub should send the notification to the customer. The callback can contain query parameters uniquely identifying the originator of the events.

                The `callbackUrl` **MUST** be an open endpoint for OVS Hub to call when sending a notification. The receiver **MUST** validate the authenticity of the notification by looking at the `Notification-Signature` header.

                **Condition:** If `callbackUrl` is provided then `secret` property is mandatory to provide also.
              example: https://myserver.com/send/callback/here?shipperRef=myID123
            secret:
              type: string
              format: byte
              maxLength: 1024
              description: |
                A Base64 encoded secret sent to the OVS Hub from the customer.
                It is used to compute the contents of the `Notification-Signature` header every time a notification is sent.

                **Condition:** If `callbackUrl` is provided then this property is mandatory to provide.
              example: 'MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDM2NTc4NjIzODk3NDY5MDgyNzM0OTg3MTIzNzg2NA=='
            useEmail:
              type: boolean
              description: |
                If `true` a possible notification match will be sent to the email address of the user who has created the subscription.
              example: true
        weekRange:
          type: integer
          format: int32
          description: |
            Number of weeks into the future for which this subscription will send notifications. If the number is `4` it means that any changes further in the future than 4 weeks from now will **not** be sent.
          example: 4
        carrierServiceCodes:
          type: array
          description: |
            An array of **carrier-specific codes** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.

            If this property is empty, you will be notified for all `carrierServiceCodes` that have changes you are authorized to see.
          items:
            type: string
            pattern: ^\S(?:.*\S)?$
            maxLength: 11
            description: |
              The carrier-specific code of the service for which the schedule details are published.
            example: FE1
          example:
            - FE1
            - DR01
        universalServiceReferences:
          type: array
          description: |
            An array of **universal service references** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.

            If this property is empty, you will be notified for all `universalServiceReferences` that have changes you are authorized to see.
          items:
            type: string
            pattern: ^SR\d{5}[A-Z]$
            maxLength: 8
            minLength: 8
            example: SR12345A
          example:
            - SR12345A
            - SR33322T
            - SR03732R
        carrierSMDGCodes:
          type: array
          description: |
            An array of **carrier SMDG codes** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.

            If this property is empty, you will be notified for all `carrierSMDGCodes` that have changes you are authorized to see.
          items:
            type: string
            maxLength: 10
            description: |
              The carrier code based on SMDG Liner Code List.
            example: MSK
          example:
            - MSK
            - EMC
        vesselNames:
          type: array
          description: |
            An array of **vessel names** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.

            If this property is empty, you will be notified for all `vesselNames` that have changes you are authorized to see.
          items:
            type: string
            maxLength: 35
            description: |
              The name of the Vessel given by the Vessel Operator and registered with IMO.

              **Note:** In case the vessel is a "dummy vessel" (`isDummyVessel='true'`) then the following recommendations should be followed:
              
              Dummy vessel names should begin with the **SMDG Operating Carrier Code** to ensure uniqueness across carriers.
              The suffix can be **alphanumeric** and up to **10 characters long**, allowing each carrier to use internal naming conventions (e.g., `MSKTBN1`, `CMATEMP01`, `MSCX01A`).

              This approach:
              - Ensures consistency and uniqueness across carriers
              - Allows flexibility in local implementations
              - Avoids the need to assign dummy IMO numbers
              - Maintains the role of the dummy vessel name as a **stable and persistent identifier** throughout the planning process
            example: King of the Seas
          example:
            - King of the Seas
            - Express 001
        vesselIMONumbers:
          type: array
          description: |
            An array of **vessel IMO numbers** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.

            If this property is empty, you will be notified for all `vesselIMONumbers` that have changes you are authorized to see.
          items:
            type: string
            pattern: ^\d{7,8}$
            minLength: 7
            maxLength: 8
            description: |
              The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel

              **Condition:** If `isDummyVessel` is `false` - at least one of `vesselIMONumber` or `MMSINumber` **MUST** be specified in order to identify the `Vessel`. It is also acceptable to provide both properties. If `isDummyVessel` is `true` it is optional to provide this property.
            example: '9321483'
          example:
            - '9321483'
            - '12345678'
        MMSINumbers:
          type: array
          description: |
            An array of **MMSI numbers** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.

            If this property is empty, you will be notified for all `MMSINumbers` that have changes you are authorized to see.
          items:
            type: string
            pattern: ^\d{9}$
            minLength: 9
            maxLength: 9
            description: |
              Maritime Mobile Service Identities (MMSIs) are nine-digit numbers used by maritime digital selective calling (DSC), automatic identification systems (AIS) and certain other equipment to uniquely identify a ship or a coast radio station.

              **Condition:** If `isDummyVessel` is `false` - at least one of `vesselIMONumber` or `MMSINumber` **MUST** be specified in order to identify the `Vessel`. It is also acceptable to provide both properties.  If `isDummyVessel` is `true` it is optional to provide this property.
            example: '278111222'
          example:
            - '278111222'
            - '278173294'
            - '234422543'
        locations:
          type: array
          description: |
            An array of **UNLocationCode and/or facilitySMDGCode combinations** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the objects when matching.

            If this property is empty, you will be notified for all `locations` that have changes you are authorized to see.
          items:
            type: object
            description: |
              It is possible to provide the `UNLocationCode`, the `facilitySMDGCode` or both when specifying the location.

              If multiple `UNLocationCode` or `facilitySMDGCode` values need to be provided, then they must be specified as separate objects in the `locations` array.

              **Condition:** At least one of `UNLocationCode` and/or `facilitySMDGCode` **MUST** be specified, both are also allowed.
            properties:
              UNLocationCode:
                type: string
                pattern: ^[A-Z]{2}[A-Z2-9]{3}$
                minLength: 5
                maxLength: 5
                description: |
                  The UN Location code specifying where the place is located. The pattern used must be

                  - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)
                  - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used

                  More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)
                example: NLAMS
              facilitySMDGCode:
                type: string
                maxLength: 6
                description: |
                  The code used for identifying the specific facility. This code does not include the UN Location Code.

                  The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/wp-content/uploads/Codelists/Terminals/SMDG-Terminal-Code-List-v20210401.xlsx)
                example: ACT
          example:
            - UNLocationCode: NLAMS
              facilitySMDGCode: APMT
            - UNLocationCode: DEHAM
            - facilitySMDGCode: APMT
      required:
        - notificationChannel
        - weekRange

    ######################
    # Notification
    ######################
    Notification:
      type: object
      title: Notification
      description: |
        `CloudEvent` specific properties for the `Notification`.
        
        The `type` property will contain the origin causing the notification to be sent: e.g. if a **Terminal** update is the trigger for a notification then the type will be:
        
            'type': 'org.dcsa.ovs-hub.schedules.terminal'
        
        If the `type` is from a Terminal - then the GET endpoint of the [**Terminal Timestamp API**](https://app.swaggerhub.com/apis/dcsaorg/DCSA_OVS_TER) should be used to get more information.

        If the `type` is from a Service - then the GET endpoint of [**Operational Vessel Schedules API**](https://app.swaggerhub.com/apis/dcsaorg/DCSA_OVS) should be used to get more information

        The matching subscription is stored in the `subscriptionreference` property. It can be used when fetching the subscription via:
            GET /subscriptions/{subscriptionreference}
      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: 'ovs-hub.dcsa.org'
        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.

            - `org.dcsa.ovs-hub.schedules.service` (for Service originated notifications)
            - `org.dcsa.ovs-hub.schedules.terminal` (for Terminal originated notifications)
          enum:
            - org.dcsa.ovs-hub.schedules.service
            - org.dcsa.ovs-hub.schedules.terminal
          example: org.dcsa.ovs-hub.schedules.service
        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
        subscriptionreference:
          type: string
          format: ulid
          maxLength: 26
          description: |
            The OVS Hub assigned unique reference for the matching subscription.
          example: 01KJZDQ1CC6HQYP8V2NE2MPRNC
        data:
          $ref: '#/components/schemas/NotificationData'
      required:
        - specversion
        - id
        - source
        - type
        - time
        - datacontenttype
        - subscriptionreference
        - data

    ###############################
    # Data for Notification
    ###############################
    NotificationData:
      type: object
      title: Data
      description: |
        `Service Schedule` specific properties for the `Notification`. When this notification is sent, a property in one of these three groups has changed:
          - `service` (carrierServiceCode, universalServiceReference, carrierSMDGCode)
          - `vessel` (vesselIMONumber,MMSINumber, vesselName, isDummyVessel)
          - `location` (location object: UNLocationCode and facilitySMDGCode)

        Some examples could be (not exhaustive):
          - `ETA`, `ETD` or any other timestamp has changed by more than Δ (delta) minutes according to the SLA (Service Level Agreement) made between the customer and OVS Hub.
          - a port is `OMIT` (omitted), `ADHO` (visited ad hoc) or any other `statusCode` has been changed or added.
          - the vessel has changed, or a new flag or vesselOperator has been assigned
          - the location of a port has changed, a new location has been added or a location has been removed from a schedule
        
        The notification will only be sent to authorized parties.

        To get more details, fetch the updated schedule data to see what changed. This is done by calling the OVS Hub
            GET /v3/service-schedules
        endpoint.
      properties:
        carrierServiceCode:
          type: string
          pattern: ^\S(?:.*\S)?$
          maxLength: 11
          description: |
            The carrier-specific code of the service for which the schedule details are published. In combination with `carrierSMDGCode` this uniquely identifies the service.
          example: FE1
        universalServiceReference:
          type: string
          pattern: ^SR\d{5}[A-Z]$
          maxLength: 8
          minLength: 8
          description: |
            Globally unique identifier of a liner service, assigned by carriers as specified by DCSA.

            DCSA generates and distributes batches of Universal Service References (USRs)
            to member and non-member carriers upon request, for their own use or for their alliances and VSAs.

            A carrier can use each of its assigned USRs either in agreement with its partners for a service under a VSA or Alliance, or independently for one of its own non-VSA, non-Alliance services.

            Every Universal Service Reference is an 8-character string with the following format:
             * the prefix "SR"
             * 5 digits
             * 1 uppercase English letter (A-Z).
          example: SR12345A
        carrierSMDGCode:
          type: string
          maxLength: 10
          description: |
            The carrier code based on SMDG Liner Code List. The `carrierSMDGCode` is linked to the carrier-specific properties:
              - `carrierServiceCode`
              - `carrierImportVoyageNumber`
              - `carrierExportVoyageNumber`
          example: MSK
        carrierImportVoyageNumber:
          type: string
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
          description: |
            The identifier of an import voyage. The carrier-specific identifier of the import Voyage. In combination with `carrierSMDGCode` and `carrierServiceCode` this uniquely identifies the import voyage.
          example: 2103N
        carrierExportVoyageNumber:
          type: string
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
          description: |
            The identifier of an export voyage. The carrier-specific identifier of the export Voyage. In combination with `carrierSMDGCode` and `carrierServiceCode` this uniquely identifies the export voyage.
          example: 2103S
        universalImportVoyageReference:
          type: string
          minLength: 5
          maxLength: 5
          pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$
          description: |
            A globally unique voyage reference for the import Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]`
            
            - `2 digits` for the year
            - `2 alphanumeric characters` for the sequence number of the voyage
            - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).

          example: 2103N
        universalExportVoyageReference:
          type: string
          minLength: 5
          maxLength: 5
          pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$
          description: |
            A globally unique voyage reference for the export Voyage, as per DCSA standard, agreed by VSA partners for the voyage. The voyage reference must match the regular expression pattern: `\d{2}[0-9A-Z]{2}[NEWSR]`
            
            - `2 digits` for the year
            - `2 alphanumeric characters` for the sequence number of the voyage
            - `1 character` for the direction/haul (`N`orth, `E`ast, `W`est, `S`outh or `R`oundtrip).
          example: 2103N
        vesselName:
          type: string
          maxLength: 50
          pattern: ^\S(?:.*\S)?$
          description: |
            The name of the Vessel given by the Vessel Operator and registered with IMO.

            **Note:** In case the vessel is a "dummy vessel" (`isDummyVessel='true'`) then the following recommendations should be followed:
            
            Dummy vessel names should begin with the **SMDG Operating Carrier Code** to ensure uniqueness across carriers.
            The suffix can be **alphanumeric** and up to **10 characters long**, allowing each carrier to use internal naming conventions (e.g., `MSKTBN1`, `CMATEMP01`, `MSCX01A`).

            This approach:
            - Ensures consistency and uniqueness across carriers
            - Allows flexibility in local implementations
            - Avoids the need to assign dummy IMO numbers
            - Maintains the role of the dummy vessel name as a **stable and persistent identifier** throughout the planning process
          example: King of the Seas
        vesselIMONumber:
          type: string
          pattern: ^\d{7,8}$
          minLength: 7
          maxLength: 8
          description: |
            The unique reference for a registered Vessel. The reference is the International Maritime Organisation (IMO) number, also sometimes known as the Lloyd's register code, which does not change during the lifetime of the vessel

            **Condition:** If `isDummyVessel` is `false` - at least one of `vesselIMONumber` or `MMSINumber` **MUST** be specified in order to identify the `Vessel`. It is also acceptable to provide both properties. If `isDummyVessel` is `true` it is optional to provide this property.
          example: '9321483'
        MMSINumber:
          type: string
          pattern: ^\d{9}$
          minLength: 9
          maxLength: 9
          description: |
            Maritime Mobile Service Identities (MMSIs) are nine-digit numbers used by maritime digital selective calling (DSC), automatic identification systems (AIS) and certain other equipment to uniquely identify a ship or a coast radio station.

            **Condition:** If `isDummyVessel` is `false` - at least one of `vesselIMONumber` or `MMSINumber` **MUST** be specified in order to identify the `Vessel`. It is also acceptable to provide both properties.  If `isDummyVessel` is `true` it is optional to provide this property.
          example: '278111222'
        isDummyVessel:
          type: boolean
          description: |
            Is this notification regarding a dummy vessel? In case no vessel has been assigned yet - this property will be set to `true` indicating that the `vesselIMONumber`/`MMSINumber` does not exist.

            When `true`, the `vesselName` must be used as a unique identifier for the dummy vessel. See the `vesselName` field description for the recommended naming convention.
        location:
          $ref: '#/components/schemas/Location'

    Location:
      title: Location
      type: object
      description: |
        The location can be specified using **any** of the nested structures:
          - `UNLocationCode`
          - `facilitySMDGCode`
      properties:
        UNLocationCode:
          type: string
          pattern: ^[A-Z]{2}[A-Z2-9]{3}$
          minLength: 5
          maxLength: 5
          description: |
            The UN Location code specifying where the place is located. The pattern used must be

            - 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)
            - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used

            More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)
          example: NLAMS
        facilitySMDGCode:
          type: string
          description: |
            The code used for identifying the specific facility. This code does not include the UN Location Code.

            The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/wp-content/uploads/Codelists/Terminals/SMDG-Terminal-Code-List-v20210401.xlsx)
          maxLength: 6
          example: ACT


    #################
    # Error Responses
    #################
    ErrorResponse:
      title: Error Response
      type: object
      description: Unexpected error
      properties:
        httpMethod:
          description: |
            The HTTP method used to make the request e.g. `GET`, `POST`, etc
          type: string
          example: POST
          enum:
            - GET
            - HEAD
            - POST
            - PUT
            - DELETE
            - OPTIONS
            - PATCH
        requestUri:
          description: |
            The URI that was requested.
          type: string
          example: /v1/events
        statusCode:
          description: |
            The HTTP status code returned.
          type: integer
          format: int32
          example: 400
        statusCodeText:
          description: |
            A standard short description corresponding to the HTTP status code.
          type: string
          maxLength: 50
          example: Bad Request
        statusCodeMessage:
          description: |
            A long description corresponding to the HTTP status code with additional information.
          type: string
          maxLength: 200
          example: The supplied data could not be accepted
        providerCorrelationReference:
          description: |
            A unique identifier to the HTTP request within the scope of the API provider.
          type: string
          maxLength: 100
          example: 4426d965-0dd8-4005-8c63-dc68b01c4962
        errorDateTime:
          description: |
            The date-time when the error occurred.
          type: string
          format: date-time
          example: '2024-09-04T09:41:00Z'
        errors:
          type: array
          description: |
            An array of errors providing more detail about the root cause.
          minItems: 1
          items:
            $ref: '#/components/schemas/DetailedError'
      required:
        - httpMethod
        - requestUri
        - statusCode
        - statusCodeText
        - errorDateTime
        - errors

    DetailedError:
      type: object
      title: Detailed Error
      description: |
        A detailed description of what has caused the error.
      properties:
        errorCode:
          type: integer
          format: int32
          description: |
            The detailed error code returned. The codes returned are maintained by the implementor of the API. For further explanation as to the meaning of an errorCode please consult the API implementer.

            **Note:** Previously it was the intention of DCSA to standardize this but it never gained traction.
          minimum: 7000
          maximum: 9999
          example: 7003
        property:
          type: string
          maxLength: 100
          description: |
            The name of the property causing the error.
          example: facilityCode
        value:
          type: string
          maxLength: 500
          description: |
            The value of the property causing the error serialised as a string exactly as in the original request.
          example: SG SIN WHS
        jsonPath:
          type: string
          maxLength: 500
          description: |
            A path to the property causing the error, formatted according to [JSONPath](https://github.com/json-path/JsonPath).
          example: $.location.facilityCode
        errorCodeText:
          description: |
            A standard short description corresponding to the `errorCode`.
          type: string
          maxLength: 100
          example: invalidData
        errorCodeMessage:
          type: string
          maxLength: 5000
          description: |
            A long description corresponding to the `errorCode` with additional information.
          example: Spaces not allowed in facility code
      required:
        - errorCodeText
        - errorCodeMessage