openapi: 3.0.1 info: title: Catena-X Unique ID Push Notification description: API documentation for Catena-X Unique ID push notifications license: name: Apache License v2.0 url: http://apache.org/v2 version: 2.0.0 servers: - url: / tags: - name: Catena-X Unique ID Push Notification description: 'API to receive Unique ID push notifications for Catena-X.' paths: /uniqueidpush/connect-to-parent: post: tags: - Unique ID Push Connect-to-Parent Notification description: Receives a Unique ID Push notification to connect a digital twin with its parent digital twin (bottom-up notification) operationId: receiveUniqueIdPushConnectToParentNotification requestBody: content: application/json: schema: $ref: '#/components/schemas/UniqueIdPushNotificationConnectToParentRequestBody' responses: "201": description: Notification was received successfully "400": description: Request body was malformed "401": description: Not authorized "403": description: Forbidden "405": description: Method not allowed "409": description: Could not accept the send notification, because a notification with that messageId already exists "422": description: Could not accept the send notification even though it is syntactically correct. The notification is not accepted, because of semantic reasons (e.g., an item is not known by the receiver). components: schemas: NotificationHeader: $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic' UniqueIdPushNotificationConnectToParentRequestBody: required: - header - content type: object properties: header: $ref: '#/components/schemas/NotificationHeader' content: $ref: '#/components/schemas/UniqueIdPushNotificationConnectToParentPayload' UniqueIdPushNotificationConnectToParentPayload: type: object required: - digitalTwinType - listOfItems properties: digitalTwinType: $ref: '#/components/schemas/DigitalTwinType' information: type: string maxLength: 1000 example: "Update of serialized parts, batches, and JIS parts for which digital twins were created." listOfItems: type: array items: oneOf: - $ref: '#/components/schemas/SerializedPartItem' - $ref: '#/components/schemas/BatchItem' - $ref: '#/components/schemas/JISItem' DigitalTwinType: type: string enum: - PartType, PartInstance example: PartInstance description: The classification defines the type of the Unique ID push notification. PartItem: type: object required: - manufacturerId - manufacturerPartId - catenaXId properties: manufacturerId: type: string example: "BPNL00000003BW3S" description: The Business Partner Number (BPNL) of the manufacturer of the serialized part, i.e., the companies main entry. manufacturerPartId: type: string example: "8840838-04" description: The ID of the type/catalog part (of which the serialized part is an instance of) from the manufacturer. customerPartId: type: string example: "AAX178378" description: The ID of the type/catalog part (of which the serialized part is an instance of) from the customer. SerializedPartItem: allOf: - $ref: '#/components/schemas/PartItem' - type: object required: - partInstanceId properties: partInstanceId: type: string example: "NO-009284492099792129568369" description: The serial number of the serialized part from the manufacturer. We assume here that the customer does not have or create its own serial number for a part, but just used the manufacturer's serial number. - $ref: '#/components/schemas/CatenaXIdItem' BatchItem: allOf: - $ref: '#/components/schemas/PartItem' - type: object required: - batchId properties: batchId: type: string example: "NO-009284492099792129568369" description: The serial number of the batch from the manufacturer. We assume here that the customer does not have or create its own serial number for a batch, but just used the manufacturer's serial number.' - $ref: '#/components/schemas/CatenaXIdItem' JISItem: allOf: - $ref: '#/components/schemas/PartItem' - type: object required: - jisNumber properties: jisNumber: type: string example: "894651684" description: A number that is used to identify the call-off that can be assumed unique within the specific just-in-sequence process. This is typically not the sequence number, but the call-off number. jisCallDate: type: string example: "2022-01-24T09:13:34" description: The date of the just-in-sequence call-off as stated on the call-off document itself. The value must be compliant to ISO 8601. parentOrderNumber: type: string example: "OEM-A-F8LM95T92WJ9KNDD3HA5P" description: A number identifying the just-in-sequence- part's destination parent part. The parent part is typically known upfront to the supplier for just-in-sequence parts. - $ref: '#/components/schemas/CatenaXIdItem' CatenaXIdItem: type: object required: - catenaXId properties: catenaXId: $ref: '#/components/schemas/CatenaXId' CatenaXId: type: string example: "urn:uuid:d32d3b55-d222-41e9-8d19-554af53124dd" description: Catena-X ID for a part instance, e.g., a serial part or a batch. # ----------------------------------------- # Schemas for Eclipse data types and shared aspect models # ----------------------------------------- urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Boolean: type: boolean description: Represents a boolean value (i.e. a "flag"). 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: "2007-08-31T16:47+00:00" urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait: type: string description: "The 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.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.quantity_2.0.0_ItemQuantityCharacteristic: description: "Characteristic for measurements of an item (mass, count, linear,\ \ area, volume, misc)." type: object properties: value: description: The quantity value associated with the unit. $ref: '#/components/schemas/urn_samm_io.catenax.shared.quantity_2.0.0_QuantityValueCharacteristic' unit: 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' required: - value - unit 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. # ----------------------------------------- # Schema: urn:samm:io.catenax.shared.message_header:3.0.0#MessageHeaderAspect # ----------------------------------------- urn_samm_io.catenax.shared.message_header_3.0.0_ContextCharacteristic: type: string description: Defining a string value for the context example: "IndustryCore-UniqueIDPush-ConnectToParent:2.0.0" 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: "urn:samm:io.catenax.shared.message_header:3.0.0#MessageHeaderAspect" 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: 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.: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 --:<[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. $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: Unique ID identifying a message somehow related to the current one $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. $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_SemanticVersioningTrait' required: - messageId - context - sentDateTime - senderBpn - receiverBpn - version