openapi: 3.0.1 info: title: Catena-X Digital Twin Event Notification API Specification description: The full specification for the Catena-X Digital Twin Event Notification API (including Unique ID Push) license: name: Apache License v2.0 url: http://apache.org/v2 version: 3.0.0 tags: - name: Digital Twin Event API description: "API for Catena-X Digital Twin Event Notifications (including Unique ID Push)" paths: /connect-to-parent: post: tags: - Digital Twin description: Receives a Unique ID Push notification to connect a digital twin with its parent digital twin (bottom-up notification) operationId: ConnectToParent requestBody: content: application/json: schema: $ref: "#/components/schemas/UniqueIdPushConnectToParentRequestBody" responses: "200": $ref: "#/components/responses/OK" "400": $ref: "#/components/responses/BadRequest" "404": $ref: "#/components/responses/NotFound" /connect-to-child: post: tags: - Digital Twin description: Receives a Unique ID Push notification to connect a digital twin with its child digital twin (top-down notification) operationId: ConnectToChild requestBody: content: application/json: schema: $ref: '#/components/schemas/UniqueIdPushConnectToChildRequestBody' responses: "200": $ref: "#/components/responses/OK" "400": $ref: "#/components/responses/BadRequest" "404": $ref: "#/components/responses/NotFound" /submodel-update: post: tags: - Submodel description: Receives a notification when an submodel of a digital twin was updated (create, update, delete) operationId: SubmodelUpdate requestBody: content: application/json: schema: $ref: "#/components/schemas/SubmodelUpdateRequestBody" responses: "200": $ref: "#/components/responses/OK" "400": $ref: "#/components/responses/BadRequest" "404": $ref: "#/components/responses/NotFound" /feedback: post: tags: - Feedback description: Receive feedback about the processing of a Digital Twin Event notification operationId: Feedback requestBody: content: application/json: schema: $ref: "#/components/schemas/FeedbackRequestSchema" responses: "200": $ref: "#/components/responses/OK" "400": $ref: "#/components/responses/BadRequest" "404": $ref: "#/components/responses/NotFound" components: responses: OK: description: OK BadRequest: description: Bad Request NotFound: description: Not Found schemas: NotificationHeader: $ref: "#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic" UniqueIdPushConnectToParentRequestBody: required: - header - content type: object properties: header: $ref: "#/components/schemas/NotificationHeader" content: $ref: "#/components/schemas/UniqueIdPushConnectToParentPayload" UniqueIdPushConnectToChildRequestBody: required: - header - content type: object properties: header: $ref: '#/components/schemas/NotificationHeader' content: $ref: '#/components/schemas/UniqueIdPushConnectToChildPayload' SubmodelUpdateRequestBody: required: - header - content type: object properties: header: $ref: '#/components/schemas/NotificationHeader' content: $ref: '#/components/schemas/SubmodelUpdatePayload' UniqueIdPushConnectToParentPayload: 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" UniqueIdPushConnectToChildPayload: type: object required: - digitalTwinType - listOfItems properties: digitalTwinType: $ref: '#/components/schemas/DigitalTwinType' information: type: string maxLength: 1000 example: "Update about the parts into which a supplier's serialized parts, batches, and JIS parts were built into." listOfItems: type: array items: oneOf: - $ref: '#/components/schemas/SingleLevelUsageAsBuilt' - $ref: '#/components/schemas/SingleLevelUsageAsPlanned' SubmodelUpdatePayload: type: object required: - listOfEvents properties: information: type: string maxLength: 1000 example: "List of events about the creation, update, or deletion of submodels of digital twins." listOfEvents: type: array items: oneOf: - $ref: "#/components/schemas/SubmodelEvent" SubmodelEvent: allOf: - type: object required: - eventType properties: eventType: type: string maxLength: 2048 example: "CreateSubmodel" description: CreateSubmodel, UpdateSubmodel, or DeleteSubmodel. - $ref: "#/components/schemas/CatenaXIdItem" - type: object required: - submodelSemanticId properties: submodelSemanticId: type: string maxLength: 2048 example: "urn:bamm:io.catenax.serial_part:3.0.0#SerialPart" description: semantic ID of the submodel that was updated FeedbackRequestSchema: type: object required: - header - content properties: header: $ref: "#/components/schemas/NotificationHeader" content: $ref: "#/components/schemas/FeedbackPayload" FeedbackPayload: type: object required: - status - listOfItems properties: status: $ref: "#/components/schemas/FeedbackStatus" statusMessage: type: string maxLength: 2048 example: "Errors occured in processing the digital twin event" description: Details about the error (or success) - e.g. why the digital twin event could not be processed. listOfItems: type: array items: oneOf: - $ref: "#/components/schemas/ItemFeedback" 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. ItemFeedback: type: object required: - catenaXId - status - errorMessage properties: catenaXId: $ref: "#/components/schemas/CatenaXId" status: type: string enum: - OK - ERROR example: "ERROR" description: The status of the processing of a single digital twin event. The following entries are supported and allowed - OK The digital twin event for a part was processed without any errors. - ERROR The digital twin event for a part could not be processed. Details about the error are given in the statusMessage field. statusMessage: type: string maxLength: 2048 example: "The digital twin event for part could not be processed: ." description: Details about the error why a part could not be processed. FeedbackStatus: type: string enum: - OK - ERROR example: OK description: The status of the processing of a digital twin event. The following entries are supported and allowed - OK The digital twin event was processed without any errors. - ERROR The digital twin event could not be processed. # ----------------------------------------- # 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-DigitalTwinEvent-:3.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: "3.0.0" 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 # ----------------------------------------- # Schema: urn:samm:io.catenax.single_level_usage_as_built:3.0.0#SingleLevelUsageAsBuilt # ----------------------------------------- urn_samm_io.catenax.single_level_usage_as_built_3.0.0_DateTimeTrait: type: string description: Regular Expression to enable UTC and Timezone formats and the possibility to exclude time information. 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))?)?$" example: "2007-08-31T16:47" urn_samm_io.catenax.single_level_usage_as_built_3.0.0_ParentData: description: Catena-X ID and meta data of the parent item. type: object properties: quantity: description: Quantity of which the child part is assembled into the parent part. In general it is '1' for serialized parts. $ref: '#/components/schemas/urn_samm_io.catenax.shared.quantity_2.0.0_ItemQuantityCharacteristic' createdOn: description: "Timestamp when the relation between the parent part and the\ \ child part was created, e.g. when the given child part was assembled\ \ into the parent part." $ref: '#/components/schemas/urn_samm_io.catenax.single_level_usage_as_built_3.0.0_DateTimeTrait' lastModifiedOn: description: Timestamp when the assembly or usage relationship between parent part and child part was last modified. $ref: '#/components/schemas/urn_samm_io.catenax.single_level_usage_as_built_3.0.0_DateTimeTrait' isOnlyPotentialParent: description: | Expresses the certainty whether the part has been used as component or input material in the produced item. If the value is false, it can be assumed that the part has been used. If the value is true, there are alternatives for that part, and it is unknown if this part item or an alternative part item has been used. This is the case when, e.g. the same item is supplied by two suppliers, and the item is only tracked by a customer part ID during assembly. Thus, these items cannot be differentiated from each other. $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Boolean' businessPartner: description: The supplier of the given child item. $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnlTrait' catenaXId: description: "The Catena-X ID of the given part (e.g. the component), valid\ \ for the Catena-X dataspace." $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' required: - createdOn - isOnlyPotentialParent - businessPartner - catenaXId urn_samm_io.catenax.single_level_usage_as_built_3.0.0_SetOfParentItemsCharacteristic: description: Set of parent items the given child object is assembled in (one structural level up). type: array items: $ref: '#/components/schemas/urn_samm_io.catenax.single_level_usage_as_built_3.0.0_ParentData' uniqueItems: true SingleLevelUsageAsBuilt: description: "The aspect provides the information in which parent part(s)/product(s)the\ \ given item is assembled in. Could be a 1:1 relationship in terms of an e.g.\ \ a brake component or 1:n for e.g. coatings. The parent item must refer to\ \ an object from as-built lifecycle phase, i.e. a batch or a serialized part." type: object properties: catenaXId: description: "The Catena-X ID of the given part (e.g. the component), valid\ \ for the Catena-X dataspace." $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' parentItems: description: |- Set of parent items, in which the given child object is assembled in (one structural level up). For serialized items the list should contain only one parent item. As different subsets of a batch might be used by a customer in different items this is a list. $ref: '#/components/schemas/urn_samm_io.catenax.single_level_usage_as_built_3.0.0_SetOfParentItemsCharacteristic' required: - catenaXId - parentItems # ----------------------------------------- # Schema: urn:samm:io.catenax.single_level_usage_as_planned:2.0.0#SingleLevelUsageAsPlanned # ----------------------------------------- urn_samm_io.catenax.single_level_usage_as_planned_2.0.0_DateTimeTrait: type: string description: Regular Expression to enable UTC and Timezone formats and the possibility to exclude time information. 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))?)?$" example: "2007-08-31T16:47+00:00" urn_samm_io.catenax.single_level_usage_as_planned_2.0.0_ValidityPeriodCharacteristic: description: Characteristic for a validity period defined by an (optional)start and an (optional)end timestamp. type: object properties: validFrom: description: Start date of validity period. $ref: '#/components/schemas/urn_samm_io.catenax.single_level_usage_as_planned_2.0.0_DateTimeTrait' validTo: description: End date of validity period. $ref: '#/components/schemas/urn_samm_io.catenax.single_level_usage_as_planned_2.0.0_DateTimeTrait' urn_samm_io.catenax.single_level_usage_as_planned_2.0.0_ParentData: description: Catena-X ID and meta data of the parent part. type: object properties: createdOn: description: Timestamp when the relation between the parent part and the child part was created. $ref: '#/components/schemas/urn_samm_io.catenax.single_level_usage_as_planned_2.0.0_DateTimeTrait' quantity: description: Quantity of which the child part will be assembled into or used in the parent part. $ref: '#/components/schemas/urn_samm_io.catenax.shared.quantity_2.0.0_ItemQuantityCharacteristic' lastModifiedOn: description: Timestamp when the assembly or usage relationship between parent part and child part was last modified. $ref: '#/components/schemas/urn_samm_io.catenax.single_level_usage_as_planned_2.0.0_DateTimeTrait' validityPeriod: description: |- The period of time during which the parent-child relation is valid. This relates to whether a child part can be built into or used in the production of the parent part at a given time. If no validity period is given the relation is considered valid at any point in time. $ref: '#/components/schemas/urn_samm_io.catenax.single_level_usage_as_planned_2.0.0_ValidityPeriodCharacteristic' businessPartner: description: The supplier of the given child item. $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnlTrait' catenaXId: description: "The Catena-X ID of the given part (e.g. the component), valid\ \ for the Catena-X dataspace." $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' required: - createdOn - quantity - businessPartner - catenaXId urn_samm_io.catenax.single_level_usage_as_planned_2.0.0_SetOfParentItemsCharacteristic: description: Set of parent items the given child object will be assembled into or used (one structural level up). type: array items: $ref: '#/components/schemas/urn_samm_io.catenax.single_level_usage_as_planned_2.0.0_ParentData' uniqueItems: true SingleLevelUsageAsPlanned: description: |- The aspect provides the information in which parent part(s)/product(s)the given item is to be assembled into or used. This could be a 1:1 relationship in terms of a e.g. a brake component or 1:n for e.g. coatings. The given item as well as the parent item must refer to an object from the as-planned lifecycle phase. If multiple versions of parent parts exist that the child part can be assembled into or used, all versions of the parent part are included in the usage list. type: object properties: catenaXId: description: "The Catena-X ID of the given part (e.g. the component), valid\ \ for the Catena-X dataspace." $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' parentItems: description: "Set of parent parts, in which the given child object will\ \ be assembled into or used (one structural level up)." $ref: '#/components/schemas/urn_samm_io.catenax.single_level_usage_as_planned_2.0.0_SetOfParentItemsCharacteristic' required: - catenaXId - parentItems