openapi: '3.1.1'
info:
  title: Block Notification API
  version: '1.0.0'
  description: |
    The blocking process is a process in the automotive industry to segregate or quarantine nonconforming parts in the supply chain to prevent using them in the production process. Therefore, the supplier must send all relevant information to the customer, so that he is able to identify the affected parts for example at the assembly line or in logistics.

    This API is to be used to transfer this information in a standardized manner and to trace the individual parts back to see whether they have been blocked and sorted out on the customer side in order to prevent subsequent damage or major product recalls. In addition, the notification is intended to improve the quality and speed of the block information provided.

    Version 1.0.0 is the first release of the Block Notification API as part of the standalone CX-0164 Blocking Notifications standard. It introduces a Create, Update, Remove based operation model with an asynchronous Feedback channel. It supersedes the Block Notification API that was formerly specified within CX-0125 Traceability Use Case (last released as Block Notification API v2.0.0); the version counter restarts at 1.0.0 for the new standalone standard. The API is compliant to CX-0151 Industry Core: Basics.

    ## Referenced Standards
    - CX-0151 Industry Core: Basics
    - CX-0152 Policy Constraints for Data Exchange
    - CX-0018 Dataspace Connectivity

    ## Connector Asset (CX-0151 compliant)
    Exactly one asset MUST be defined in the connector for this notification API:
    - Asset-ID: `BlockNotificationAPI`
    - `dct:type`: `https://w3id.org/catenax/taxonomy#BlockNotificationAPI`
    - `cx-common:version`: `1.0`
  license:
    name: Apache License v2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
- url: https://example.com/api/v1
  variables:
    api-version:
      default: '1.0.0'

paths:

  # Create a new block notification (Supplier → Customer)
  /create:
    post:
      tags:
      - Block Notification
      operationId: create
      summary: Create a new Block Notification
      description: |
        Creates a new block notification with the associated blocking information.

        **Direction:** Supplier → Customer

        The `manufacturerProblemId` is assigned by the sender (supplier) and serves as the stable supplier-side business identifier for this block notification.
        The `customerProblemId` carries the corresponding customer-side reference. It MAY be empty or omitted in the initial Create operation and becomes mandatory for subsequent Update/Remove operations once known.
        All parts listed in `blockInformations` are implicitly blocked (ACTIVE); no per-part block status is carried in the Create operation.
        Feedback from the receiver is provided asynchronously via the Feedback operation.
      requestBody:
        $ref: '#/components/requestBodies/BlockNotificationCreate'
      responses:
        "200":
          $ref: '#/components/responses/Successful'
        "4XX":
          $ref: '#/components/responses/ClientError'
        "5XX":
          $ref: '#/components/responses/ServerError'

  # Update an existing block notification (Supplier → Customer)
  /update:
    post:
      tags:
      - Block Notification
      operationId: update
      summary: Update an existing Block Notification
      description: |
        Updates an existing block notification. Parts are added via `partsToAdd` and changed via `partsToUpdate`:
        - `partsToAdd`: parts to add to the blocking list. Each item carries the full part blocking information (as in Create). Added parts are implicitly ACTIVE.
        - `partsToUpdate`: parts whose attributes / containment data change. The provided information fully replaces the previously stored values (no merge). Block status is NOT changed here — use the Remove operation to cancel a part.

        Master-data fields (`problemDescription`, `criticality`, `supplierContactPerson`) MAY also be updated. A message with no `partsToAdd`/`partsToUpdate` and only master-data fields signals a master-data-only update.

        **Direction:** Supplier → Customer
      requestBody:
        $ref: '#/components/requestBodies/BlockNotificationUpdate'
      responses:
        "200":
          $ref: '#/components/responses/Successful'
        "4XX":
          $ref: '#/components/responses/ClientError'
        "5XX":
          $ref: '#/components/responses/ServerError'

  # Remove (cancel) parts or the whole block notification (Supplier → Customer)
  /remove:
    post:
      tags:
      - Block Notification
      operationId: remove
      summary: Remove (cancel) parts or the whole Block Notification
      description: |
        Cancels parts of a block notification — it sets the affected parts to block status CANCELED ("released / free for production"). Removal is therefore always a cancellation, never a hard delete; the parts remain in the record marked CANCELED.

        If `parts` is provided, only those parts are cancelled. If `parts` is omitted, the entire block notification is cancelled. A `cancellationReason` MUST be provided for the audit trail.

        **Direction:** Supplier → Customer
      requestBody:
        $ref: '#/components/requestBodies/BlockNotificationRemove'
      responses:
        "200":
          $ref: '#/components/responses/Successful'
        "4XX":
          $ref: '#/components/responses/ClientError'
        "5XX":
          $ref: '#/components/responses/ServerError'

  # Send feedback for a block notification (Receiver → Sender)
  /feedback:
    post:
      tags:
      - Block Notification
      operationId: feedback
      summary: Send Feedback for a Block Notification
      description: |
        Provides structured business feedback from the receiver to the sender about exactly one block notification (one problem).
        Depending on `feedbackType` it conveys:
        - `CUSTOMER_PROBLEM_ID_CREATED`: returns the `customerProblemId` generated by the customer after a Create.
        - `ERROR`: a business-level rejection with `errorCode` / `statusMessage`.

        **Direction:** Receiver → Sender (i.e., Customer → Supplier).

        The `relatedMessageId` in the header is OPTIONAL. Feedback is correlated to the problem via `manufacturerProblemId` in the content; it MAY additionally reference the `messageId` of the message it responds to.
      requestBody:
        $ref: '#/components/requestBodies/BlockNotificationFeedback'
      responses:
        "200":
          $ref: '#/components/responses/Successful'
        "4XX":
          $ref: '#/components/responses/ClientError'
        "5XX":
          $ref: '#/components/responses/ServerError'

components:

  # ─────────────────────────────────────────────────────────────────────────────
  # SCHEMAS
  # ─────────────────────────────────────────────────────────────────────────────
  schemas:

    # ═══════════════════════════════════════════════════════════════════════════
    # Top-level request body schemas
    # ═══════════════════════════════════════════════════════════════════════════

    BlockNotificationCreate:
      type: object
      description: "Request schema to create a new block notification."
      properties:
        header:
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic'
        content:
          $ref: '#/components/schemas/NotificationContentCreate'
      required:
        - header
        - content

    BlockNotificationUpdate:
      type: object
      description: "Request schema to update an existing block notification."
      properties:
        header:
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic'
        content:
          $ref: '#/components/schemas/NotificationContentUpdate'
      required:
        - header
        - content

    BlockNotificationRemove:
      type: object
      description: "Request schema for the Remove operation (cancel parts or the whole block notification)."
      properties:
        header:
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic'
        content:
          $ref: '#/components/schemas/NotificationContentRemove'
      required:
        - header
        - content

    BlockNotificationFeedback:
      type: object
      description: "Request schema to send feedback for a block notification."
      properties:
        header:
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic'
        content:
          $ref: '#/components/schemas/NotificationContentFeedback'
      required:
        - header
        - content

    # ═══════════════════════════════════════════════════════════════════════════
    # Header schemas (shared, MessageHeaderAspect 3.0.0 per CX-0151)
    # ═══════════════════════════════════════════════════════════════════════════

    urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic:
      description: Characteristic describing the common shared aspect Message Header
      type: object
      properties:
        messageId:
          description: "Unique ID identifying the message. The purpose of the ID is\
            \ to uniquely identify a single message, therefore it MUST not be reused."
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait'
        context:
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_ContextCharacteristic'
        sentDateTime:
          description: Time zone aware timestamp holding the date and the time the
            message was sent by the sending party. The value MUST be formatted according
            to the ISO 8601 standard
          $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp'
        senderBpn:
          description: The Business Partner Number of the sending party. The value
            MUST be a valid BPN. BPNA and BPNS are not allowed. Applicable constraints
            are defined in the corresponding standard
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnlTrait'
        receiverBpn:
          description: The Business Partner Number of the receiving party. The value
            MUST be a valid BPN. BPNA and BPNS are not allowed. Applicable constraints
            are defined in the corresponding standard.
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnlTrait'
        expectedResponseBy:
          description: Time zone aware timestamp holding the date and time by which
            the sending party expects a certain type of response from the receiving
            party. The meaning and interpretation of the fields's value are context-bound
            and MUST therefore be defined by any business domain or platform capability
            making use of it. The value MUST be formatted according to the ISO 8601
            standard
          $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp'
        relatedMessageId:
          description: Optional. Identifies a message somehow related to the current
            one. Update, Remove and Feedback are correlated to the problem via
            manufacturerProblemId in the content; relatedMessageId MAY additionally
            reference a specific message (e.g. the Create, or the message a Feedback responds to).
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait'
        version:
          description: The unique identifier of the aspect model defining the structure
            and the semantics of the message's header. The version number should reflect
            the versioning schema of aspect models in Catena-X. This is the version of
            the MessageHeaderAspect (3.0.0) and MUST NOT be confused with the API/context version.
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_SemanticVersioningTrait'
      required:
      - messageId
      - context
      - sentDateTime
      - senderBpn
      - receiverBpn
      - version

    urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait:
      type: string
      description: "The fully anonymous Catena-X ID of the serialized part or\
            \ batch, valid for the Catena-X dataspace. \n\nThe provided regular expression ensures that the UUID is composed\
        \ of five groups of characters separated by hyphens, in the form 8-4-4-4-12\
        \ for a total of 36 characters (32 hexadecimal characters and 4 hyphens),\
        \ optionally prefixed by \"urn:uuid:\" to make it an IRI."
      pattern: "(^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)|(^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)"

    urn_samm_io.catenax.shared.message_header_3.0.0_ContextCharacteristic:
      type: string
      description: |-
            Information about the context the message should be considered in.
            The value MUST consist of two parts: an identifier of the context (e.g. business domain, etc.) followed by a version number.
            Both the identifier and the version number MUST correspond to the content of the message.
            If the content of a message is described by an aspect model available in the Catena-X Semantic Hub, then the unique identifier of this semantic model (e.g. urn:samm:io.catenax.<ASPECT-MODEL-NAME>:1.x.x) MUST be used as a value of the context field. This is considered the default case.
            In all other cases the value of the context field MUST follow the pattern <domain>-<subdomain>-<object>:<[major] version> (e.g. TRACE-QM-Alert:1.x.x).
            Versioning only refers to major versions in both default and fallback cases.
            Note: The version of the message's header is specified in the version field.
      example: 'Blocking-BlockNotificationAPI-Create:1.0.0'

    urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp:
      type: string
      pattern: "-?([1-9][0-9]{3,}|0[0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T(([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\\
        .[0-9]+)?|(24:00:00(\\.0+)?))(Z|(\\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))?"
      description: Describes a Property which contains the date and time with an optional
        timezone.
      example: '2024-10-07T10:15+00:00'

    urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnlTrait:
      type: string
      description: "The provided regular expression ensures that the BPNL is composed\
        \ of prefix 'BPNL', 10 digits and two alphanumeric letters."
      pattern: "^BPNL[a-zA-Z0-9]{12}$"

    urn_samm_io.catenax.shared.message_header_3.0.0_SemanticVersioningTrait:
      type: string
      description: Constraint for defining a SemVer version.
      pattern: "^(0|[1-9][0-9]*).(0|[1-9][0-9]*).(0|[1-9][0-9]*)(-(0|[1-9A-Za-z-][0-9A-Za-z-]*)(.[0-9A-Za-z-]+)*)?([0-9A-Za-z-]+(.[0-9A-Za-z-]+)*)?$"
      example: '3.0.0'

    # ═══════════════════════════════════════════════════════════════════════════
    # Content schemas
    # ═══════════════════════════════════════════════════════════════════════════

    NotificationContentCreate:
      type: object
      description: Content payload for creating a new block notification. All parts listed are implicitly blocked (ACTIVE).
      properties:
        manufacturerProblemId:
          $ref: '#/components/schemas/ManufacturerProblemId'
        customerProblemId:
          $ref: '#/components/schemas/CustomerProblemId'
        problemDescription:
          type: string
          maxLength: 1000
          example: "Gear boxes lose oil while driving."
          description: A free text field which provides information why the parts from the provided list must be blocked or sorted out.
        criticality:
          $ref: '#/components/schemas/Criticality'
        proposedUsageDecision:
          $ref: '#/components/schemas/UsageDecision'
        supplierContactPerson:
          $ref: '#/components/schemas/SupplierContactPerson'
        blockInformations:
          $ref: '#/components/schemas/PartBlockingInformationSet'
      required:
      - manufacturerProblemId
      - problemDescription
      - criticality
      - blockInformations

    NotificationContentUpdate:
      type: object
      description: |
        Content payload for updating an existing block notification.
        Parts are added via `partsToAdd` and changed via `partsToUpdate`; cancelling/releasing a part is done with the Remove operation, not here.
        Master-data fields (problemDescription, criticality, proposedUsageDecision, supplierContactPerson) MAY be updated.
        A message with no `partsToAdd`/`partsToUpdate` and only master-data fields signals a master-data-only update.
      properties:
        manufacturerProblemId:
          $ref: '#/components/schemas/ManufacturerProblemId'
        customerProblemId:
          $ref: '#/components/schemas/CustomerProblemId'
        problemDescription:
          type: string
          maxLength: 1000
          example: "Updated problem description text"
          description: Optional updated free-text description of the blocking reason.
        criticality:
          $ref: '#/components/schemas/Criticality'
        proposedUsageDecision:
          $ref: '#/components/schemas/UsageDecision'
        supplierContactPerson:
          $ref: '#/components/schemas/SupplierContactPerson'
        partsToAdd:
          description: Parts to be added to the blocking list. Each item carries the full part blocking information (as in Create). Added parts are implicitly ACTIVE.
          type: array
          items:
            $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_PartBlockingInformationEntity'
          uniqueItems: true
        partsToUpdate:
          description: Parts whose attributes / containment data change. The provided part blocking information fully replaces the stored values (no merge). Block status is NOT changed here — use the Remove operation to cancel a part.
          type: array
          items:
            $ref: '#/components/schemas/PartToUpdate'
          uniqueItems: true
      required:
      - manufacturerProblemId

    NotificationContentRemove:
      type: object
      description: |
        Content payload for the Remove operation. Cancels the listed parts (sets them to CANCELED, "free for production"); if `parts` is omitted, the entire block notification is cancelled. `manufacturerProblemId` is always required; `customerProblemId` is required once it is known to the sender.
      properties:
        manufacturerProblemId:
          $ref: '#/components/schemas/ManufacturerProblemId'
        customerProblemId:
          $ref: '#/components/schemas/CustomerProblemId'
        cancellationReason:
          type: string
          maxLength: 1000
          description: Justification for cancelling the part(s) or the whole notification, kept for the audit trail.
          example: "Root-cause analysis showed the parts conform to specification; blocking withdrawn."
        parts:
          description: Parts to cancel (set to CANCELED). If omitted, the entire block notification is cancelled.
          type: array
          items:
            $ref: '#/components/schemas/PartReference'
          uniqueItems: true
      required:
      - manufacturerProblemId
      - cancellationReason

    NotificationContentFeedback:
      type: object
      description: |
        Content payload for business feedback on exactly one block notification (one problem).
        The `feedbackType` determines which optional fields apply:
        - CUSTOMER_PROBLEM_ID_CREATED: `customerProblemId` is returned.
        - ERROR: `errorCode` and `statusMessage` describe the business-level rejection.
      properties:
        feedbackType:
          $ref: '#/components/schemas/FeedbackType'
        manufacturerProblemId:
          $ref: '#/components/schemas/ManufacturerProblemId'
        customerProblemId:
          $ref: '#/components/schemas/CustomerProblemId'
        itemFeedbacks:
          description: Per-part processing results, used with feedbackType PROCESSING_RESULT. All items belong to the single problem identified above.
          type: array
          items:
            $ref: '#/components/schemas/ItemFeedback'
          uniqueItems: true
        errorCode:
          type: string
          maxLength: 100
          description: A machine-readable error code, used with feedbackType ERROR.
          example: 'ERR_VALIDATION_006'
        statusMessage:
          type: string
          maxLength: 1000
          description: A human-readable description of the rejection, used with feedbackType ERROR.
          example: "Mandatory attribute 'partInstanceId' is missing."
      required:
      - feedbackType
      - manufacturerProblemId

    # ═══════════════════════════════════════════════════════════════════════════
    # Enumerations and supporting schemas
    # ═══════════════════════════════════════════════════════════════════════════

    FeedbackType:
      type: string
      description: |
        The type of business feedback.
        - CUSTOMER_PROBLEM_ID_CREATED: The customer created its quality process and returns the generated customerProblemId.
        - ERROR: Business-level rejection of the referenced notification.
      enum:
      - CUSTOMER_PROBLEM_ID_CREATED
      - ERROR
      example: 'CUSTOMER_PROBLEM_ID_CREATED'

    ProcessingStatus:
      type: string
      description: |
        Customer-side processing result for a single part.
        - BLOCKED: The part was blocked / quarantined.
        - SORTED_OUT: The part was sorted out at goods receipt.
        - NOT_FOUND: The part could not be located.
        - ALREADY_INSTALLED: The part was already built into a product.
        - RELEASED: The part was released after inspection.
      enum:
      - BLOCKED
      - SORTED_OUT
      - NOT_FOUND
      - ALREADY_INSTALLED
      - RELEASED
      example: 'SORTED_OUT'

    ItemFeedback:
      type: object
      description: A single per-part processing result within a PROCESSING_RESULT feedback.
      properties:
        catenaXId:
          description: "The Catena-X ID of the affected part, mirroring the original blockInformations entry."
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait'
        processingStatus:
          $ref: '#/components/schemas/ProcessingStatus'
        processingDateTime:
          description: Timestamp of the processing result.
          $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp'
        comment:
          type: string
          maxLength: 1000
          description: Optional free-text remark.
      required:
      - catenaXId
      - processingStatus

    Criticality:
      type: string
      description: Severity classification of the quality problem.
      enum:
      - LOW
      - MEDIUM
      - HIGH
      - HIGHEST
      example: 'HIGHEST'

    UsageDecision:
      type: string
      description: Supplier recommendation on how to handle the affected parts.
      enum:
      - SCRAPPING
      - REWORK
      - RETURN_TO_SUPPLIER
      - USE_AS_IS
      - PENDING_DECISION
      example: 'SCRAPPING'

    SupplierContactPerson:
      type: object
      description: Contact person at the supplier for clarifications regarding the blocking problem.
      properties:
        firstName:
          type: string
          maxLength: 100
          example: 'Max'
        lastName:
          type: string
          maxLength: 100
          example: 'Mustermann'
        email:
          type: string
          format: email
          example: 'max.mustermann@company.com'
        phone:
          type: string
          maxLength: 50
          description: Optional phone number.
          example: '+49-170-1234567'
      required:
      - firstName
      - lastName
      - email

    ManufacturerProblemId:
      type: string
      description: Stable supplier-side identifier for the blocking problem. The sender MUST generate it on Create and MUST reuse it in all subsequent Update and Remove operations for the same problem.
      example: 'SUP-2026-GB-0451'

    CustomerProblemId:
      type: string
      description: Customer-side identifier of the corresponding quality process. It MAY be omitted or empty in the initial Create operation and becomes mandatory in subsequent Update/Remove operations once returned to the supplier.
      example: 'SN-26-DP3-BC5'

    # ═══════════════════════════════════════════════════════════════════════════
    # Part blocking information schemas
    # ═══════════════════════════════════════════════════════════════════════════

    # Set for Create operation and partsToAdd in Update
    PartBlockingInformationSet:
      description: The set of part blocking information entries. Used in the Create operation and in the `partsToAdd` array of the Update operation.
      type: array
      items:
        $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_PartBlockingInformationEntity'
      uniqueItems: true

    # Entry for partsToUpdate
    PartToUpdate:
      type: object
      description: |
        Part entry for the `partsToUpdate` array of an Update operation.
        `catenaXId` identifies the part; the remaining part blocking information fully replaces
        the stored values (no merge). Block status is NOT changed here — use the Remove operation to cancel a part.
      properties:
        catenaXId:
          description: "The fully anonymous Catena-X ID of the serialized part or batch, valid for the Catena-X dataspace."
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait'
        componentLevelContainment:
          description: Section with blocking information at component level.
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_ComponentLevelContainmentCharacteristic'
        periodAndVolumeLevelContainment:
          description: Section with blocking information at period and volume level.
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_PeriodAndVolumeLevelContainmentCharacteristic'
        locationInTheContainer:
          description: 'Object which contains information regarding the locality of the part within a small load carrier.'
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_LocationInTheContainerCharacteristic'
      required:
      - catenaXId

    # Reference to a single part by Catena-X ID (used in the Remove operation)
    PartReference:
      type: object
      description: Reference to a single part by its Catena-X ID, used in the `parts` array of the Remove operation.
      properties:
        catenaXId:
          description: "The fully anonymous Catena-X ID of the serialized part or batch, valid for the Catena-X dataspace."
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait'
      required:
      - catenaXId

    urn_samm_io.catenax.block_notification_data_2.0.0_PartBlockingInformationEntity:
      description: |
        The entity of the part blocking information set. Identifies exactly one part by its mandatory `catenaXId` and (recommended) its containment data. Listed parts are implicitly ACTIVE; block status is not a wire field - it is derived from the operation (ACTIVE on Create/partsToAdd, CANCELD via Remove)
      type: object
      properties:
        catenaXId:
          description: "The fully anonymous Catena-X ID of the serialized part or\
            \ batch, valid for the Catena-X dataspace."
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait'
        componentLevelContainment:
          description: Section with blocking information at component level (RECOMMENDED).
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_ComponentLevelContainmentCharacteristic'
        periodAndVolumeLevelContainment:
          description: Section with blocking information at period and volume level (RECOMMENDED).
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_PeriodAndVolumeLevelContainmentCharacteristic'
        locationInTheContainer:
          description: 'Object which contains information regarding the locality of
            the part within a small load carrier. '
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_LocationInTheContainerCharacteristic'
      required:
      - catenaXId

    urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnaCharacteristic:
      type: string
      description: "Identifies the respective address of the supplier's location\
            \ from which the corresponding components are delivered. \n\n The provided regular expression ensures that the BPNA is composed\
        \ of prefix 'BPNA', 10 digits and two alphanumeric letters."
      pattern: "^BPNA[a-zA-Z0-9]{12}$"

    urn_samm_io.catenax.block_notification_data_2.0.0_IntegrationLevelCharacteristic:
      type: string
      description: "(E/E component generation (hardware and software) with defined\
            \ functional content and coordinated system communication) [Vehicle electrics/electronics]\t"
      example: 'S18A-19-03-400'

    urn_samm_io.catenax.serial_part_3.0.0_PartIdCharacteristic:
      type: string
      description: |-
            An ID that consists of two different pieces of information but at least always contains a part number:

            Part Number
             identifier of a particular part design (or material used) which unambiguously identifies a part design within a single corporation, sometimes across several corporations

            Change Index (optional)
            The change index corresponds to the identification of a version of a technical object (also in the technical drawing).
            This provides easy-to-understand version management, which allows older variants to be clearly addressed. The first version usually has an index of 0. When changes are made, this is usually increased by 1. The current edition therefore has the highest change index. Alternatively, it is possible to represent the index in ascending order with letters, i.e. A, B, C,... Z, AA, AB, etc.
      example: '884267902'

    urn_samm_io.catenax.serial_part_3.0.0_KeyTrait:
      type: string
      description: Constraint that ensures that the standard keys and custom key prefixes
        can be used.
      pattern: ^(manufacturerId|partInstanceId|batchId|van|customKey:\w+)$

    urn_samm_io.catenax.serial_part_3.0.0_ValueCharacteristic:
      type: string
      description: The value of an identifier.

    urn_samm_io.catenax.serial_part_3.0.0_KeyValueList:
      description: "A list of key value pairs for local identifiers, which are composed\
        \ of a key and a corresponding value."
      type: object
      properties:
        key:
          description: 'The key of a local identifier. '
          $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_KeyTrait'
        value:
          description: The value of an identifier.
          $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_ValueCharacteristic'
      required:
      - key
      - value

    urn_samm_io.catenax.serial_part_3.0.0_LocalIdentifierCharacteristic:
      description: "A local identifier enables identification of a part in a specific\
            \ dataspace, but is not unique in Catena-X dataspace. Multiple local identifiers\
            \ may exist. \n\n A single serialized part may have multiple attributes, that uniquely\
        \ identify a that part in a specific dataspace (e.g. the manufacturer`s dataspace)"
      type: array
      items:
        $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_KeyValueList'
      uniqueItems: true
      example:
        - key: 'manufacturerId'
          value: 'BPNL0123456789ZZ'
        - key: 'partInstanceId'
          value: 'SN12345678'
        - key: 'customKey:componentSerialNumber'
          value: '220115001384267902201978150063581180'

    urn_samm_io.catenax.block_notification_data_2.0.0_ComponentLevelContainmentCharacteristic:
      description: 'The characteristic of the component level containment defined
        as a Object. '
      type: object
      properties:
        manufacturingLocationId:
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnaCharacteristic'
        integrationLevel:
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_IntegrationLevelCharacteristic'
        customerPartId:
          description: The customer's part number for the affected part.
          $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_PartIdCharacteristic'
        manufacturerPartId:
          description: The manufacturer's (supplier's) own part number for the affected part — first-class, symmetric counterpart to customerPartId.
          $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_PartIdCharacteristic'
        localIdentifiers:
          $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_LocalIdentifierCharacteristic'
      required:
      - manufacturingLocationId
      - customerPartId

    urn_samm_io.catenax.shared.quantity_2.0.0_ItemUnitEnumeration:
      type: string
      pattern: "[a-zA-Z]*:[a-zA-Z]+"
      description: Enumeration for common item units.
      enum:
      - unit:piece
      - unit:set
      - unit:pair
      - unit:page
      - unit:cycle
      - unit:kilowattHour
      - unit:gram
      - unit:kilogram
      - unit:tonneMetricTon
      - unit:tonUsOrShortTonUkorus
      - unit:ounceAvoirdupois
      - unit:pound
      - unit:metre
      - unit:centimetre
      - unit:kilometre
      - unit:inch
      - unit:foot
      - unit:yard
      - unit:squareCentimetre
      - unit:squareMetre
      - unit:squareInch
      - unit:squareFoot
      - unit:squareYard
      - unit:cubicCentimetre
      - unit:cubicMetre
      - unit:cubicInch
      - unit:cubicFoot
      - unit:cubicYard
      - unit:litre
      - unit:millilitre
      - unit:hectolitre
      - unit:secondUnitOfTime
      - unit:minuteUnitOfTime
      - unit:hourUnitOfTime
      - unit:day

    urn_samm_io.catenax.shared.quantity_2.0.0_QuantityValueCharacteristic:
      type: number
      description: The quantity value associated with the unit expressed as float.
      example: 20.0

    urn_samm_io.catenax.block_notification_data_2.0.0_QuantityCharacteristic:
      description: 'The characteristic to define the quantity an value of a property. '
      type: object
      properties:
        itemUnit:
          description: "The unit of an item. Common units may be related to mass,\
            \ count, linear, area, volume or misc."
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.quantity_2.0.0_ItemUnitEnumeration'
        quantityValue:
          description: The quantity value associated with the unit.
          $ref: '#/components/schemas/urn_samm_io.catenax.shared.quantity_2.0.0_QuantityValueCharacteristic'
      required:
      - itemUnit
      - quantityValue

    urn_samm_io.catenax.block_notification_data_2.0.0_DeliveryPlaceCharacteristic:
      type: string
      description: "The identification number of the unloading point. An unloading\
            \ point is an important part of logistics, as it describes the location\
            \ where goods can be loaded or unloaded using a means of transport. In\
            \ addition to the address itself, the spatial conditions at the unloading\
            \ point are also important. Each warehouse has its own type of unloading\
            \ point, such as a ramp that is specifically designed for loading and\
            \ unloading goods. These specific conditions are crucial for the efficient\
            \ and secure processing of deliveries.\t"
      example: '22610'

    urn_samm_io.catenax.block_notification_data_2.0.0_DeliveryNoteNumberCharacteristic:
      type: string
      description: "The number of the delivery note that accompanies the delivery\
            \ and shows the description, unit and quantity of goods included in the\
            \ delivery, etc..\t"
      example: '68988545'

    urn_samm_io.catenax.block_notification_data_2.0.0_PackageNumberCharacteristic:
      type: string
      description: "Identification number of the package, the unit of goods and\
            \ packaging material. These can be boxes, pallets, mesh boxes, roll containers\
            \ and other loading equipment."
      example: '12295140916130'

    urn_samm_io.catenax.block_notification_data_2.0.0_OrderNumberCharacteristic:
      type: string
      description: The order number (only for production synchronization requests
            (JIS))
      example: '7334663'

    urn_samm_io.catenax.block_notification_data_2.0.0_PeriodAndVolumeLevelContainmentCharacteristic:
      description: 'The characteristic of the period and volume level containment
        defined as Object. '
      type: object
      properties:
        sizeOfProductionLot:
          description: "A production lot is the combined number of products or manufactured\
            \ parts that are produced in a work process without interruption. There\
            \ is no need to convert production facilities. \t"
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_QuantityCharacteristic'
        deliveryNoteNumber:
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_DeliveryNoteNumberCharacteristic'
        packageNumber:
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_PackageNumberCharacteristic'
        deliveryPlace:
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_DeliveryPlaceCharacteristic'
        deliveryDate:
          description: "The date, on which the supplier handed over the shipment \
            \ to the carrier. Shipping date of the manufacturer."
          $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp'
        numberOfPartsPerDeliveryNote:
          description: The quantity of delivered parts per delivery note.
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_QuantityCharacteristic'
        productionDate:
          $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp'
        numberOfPartsPerPackage:
          description: Number of parts, which are stored in a package.
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_QuantityCharacteristic'
        orderNumber:
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_OrderNumberCharacteristic'
      required:
      - sizeOfProductionLot
      - deliveryNoteNumber
      - packageNumber
      - deliveryPlace
      - deliveryDate
      - numberOfPartsPerDeliveryNote
      - productionDate
      - numberOfPartsPerPackage

    urn_samm_io.catenax.block_notification_data_2.0.0_XPositionCharacteristic:
      type: string
      description: "Position along the X coordinate where the faulty component\
            \ (cell) is located within the small charge carrier.\t"
      example: 'F'

    urn_samm_io.catenax.block_notification_data_2.0.0_YPositionCharacteristic:
      type: string
      description: Position along the Y coordinate where the faulty component
            (cell) is located within the small charge carrier.
      example: '10'

    urn_samm_io.catenax.block_notification_data_2.0.0_SmallLoadCarrierLayerCharacteristic:
      type: string
      description: |-
            The layer within the small load carrier in which the faulty part is located.
            (Ideally if available: UCID = Unique Container ID - ID of the small load carrier in which the faulty part is located)
            Packaging specific for high-voltage battery cells. Other components (e.g. penthouse are not packaged in small load carriers).
      example: '53BUN6555599345283155+000000008'

    urn_samm_io.catenax.block_notification_data_2.0.0_LocationInTheContainerCharacteristic:
      description: The characteristic to define the location in the container defined
        as entity.
      type: object
      properties:
        xPosition:
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_XPositionCharacteristic'
        yPosition:
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_YPositionCharacteristic'
        smallLoadCarrierLayer:
          $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_2.0.0_SmallLoadCarrierLayerCharacteristic'

  # ─────────────────────────────────────────────────────────────────────────────
  # RESPONSES
  # ─────────────────────────────────────────────────────────────────────────────
  responses:
    Successful:
      description: Technical acknowledgement — the block notification message was received and is schema-valid. Carries no business semantics; business outcomes are returned asynchronously via the Feedback operation.
    ClientError:
      description: The block notification could not be processed due to a client error (e.g., malformed request, authentication/authorization failure, semantic error).
    ServerError:
      description: The block notification could not be processed due to a server-side error.

  # ─────────────────────────────────────────────────────────────────────────────
  # REQUEST BODIES
  # ─────────────────────────────────────────────────────────────────────────────
  requestBodies:
    BlockNotificationCreate:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BlockNotificationCreate'
    BlockNotificationUpdate:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BlockNotificationUpdate'
    BlockNotificationRemove:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BlockNotificationRemove'
    BlockNotificationFeedback:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BlockNotificationFeedback'