openapi: 3.0.3 info: title: Early Warning Notification license: name: Apache License v2.0 url: http://apache.org/v2 version: 1.0.0 servers: - url: catenax.io/api/v1 variables: api-version: default: v1 tags: - name: Early Warning Notification API description: 'Api to receive, update and fetch an early warning notification.' paths: /earlywarningnotification/receive: post: tags: - Early Warning notification description: Receives a new early warning notification operationId: receiveEarlyWarningNotification requestBody: content: application/json: schema: $ref: '#/components/schemas/EarlyWarningNotification' responses: "200": description: Early warning notification was received successfully "400": description: Request body was malformed "401": description: Not authorized "403": description: Forbidden "405": description: Method not allowed "404": description: Could not accept the early warning notification, because an early warning notification with that notificationId does not exist "422": description: Could not accept the early warning notification even though the request is syntactically correct. The early warning notification update is not accepted, because of semantic reasons (e.g., status cannot be changed). /earlywarningnotification/update: post: tags: - Early Warning notification description: Updates an early warning notification operationId: updateEarlyWarningNotification requestBody: content: application/json: schema: $ref: '#/components/schemas/EarlyWarningNotification' responses: "200": description: Early warning notification was updated successfully "400": description: Request body was malformed "401": description: Not authorized "403": description: Forbidden "405": description: Method not allowed "404": description: Could not update the early warning notification, because an early warning notification with that notificationId does not exist "422": description: Could not update the early warning notification even though the request is syntactically correct. The early warning notification update is not accepted, because of semantic reasons (e.g., status cannot be changed). components: schemas: StandardNotificationHeader: $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_2.0.0_HeaderCharacteristic' StandardNotificationConnectToRequestHeader: allOf: - $ref: '#/components/schemas/StandardNotificationHeader' 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_org.eclipse.esmf.samm_characteristic_2.1.0_Text: type: string description: "Describes a Property which contains plain text. This is intended\ \ exclusively for human readable strings, not for identifiers, measurement\ \ values, etc." urn_samm_io.catenax.early_warning_notification_1.0.0_Status: type: string enum: - SENT - ACKNOWLEDGED - ACCEPTED - DECLINED - CLOSED description: The status of the quality notification. The following entries are supported and allowed - SENT This status means that the notification has been sent out. This status is shown on the sender side (and not on the receiver side). - ACKNOWLEDGED Defines that a user has confirmed that the notification has been received. This does NOT mean that the user accepted the notification in the sense of an admission of guilt or the like. However, it means that the notification gets processed by the user (or the organization behind). - ACCEPTED The status expresses that the received agrees on the quality investigation/alert. Recommendations, counter actions, and the like can be conveyed in the payload field information. - DECLINED The status expresses that the received does not agree on the quality investigation/alert. Recommendations, counter actions, and the like can be conveyed in the payload field information. - CLOSED This status is set by the initiator of the notification either to regularly close the notification (i.e., after the receiver has set the status to ACCEPTED or DECLINED) or to abort the processing of the notification (e.g., because the notification is not relevant anymore). urn_samm_io.catenax.early_warning_notification_1.0.0_Severity: type: string enum: - MINOR - MAJOR - CRITICAL - LIFE-THREATENING description: The severity of the quality notification describes its criticality. The severity is set by the initiator of a quality notification. The following entries are supported and allowed - MINOR This is the case if the quality issue(s) is/are not affecting any functionalities of the serialized parts/batch e.g., aesthetical issue. - MAJOR This is the case if the quality issue(s) is/are so critical that the functionality of the serialized parts/batch is partially not given. This is also the case if the serialized part / batch is no longer functional, but the missing functionality (a) can be compensated by other parts of a superordinate system or (b) has a relatively low significance / benefit - CRITICAL This is the case if the quality issue(s) is/are so critical that the basic functionality of the serialized parts/batch is no longer given. - LIFE-THREATENING This is the case if the quality issue(s) is/are so critical that it even endangers human lives e.g., the airbag or break is not working. urn_samm_io.catenax.early_warning_notification_1.0.0_Items: description: A unique identifier type: object properties: catenaXId: description: A unique identifier for a part or a vehicle. The identifier relates to a Catena-X digital twin $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' urn_samm_io.catenax.early_warning_notification_1.0.0_AffectedItemsCharacteristic: description: Characteristic for the UIDs defining the affected items type: array items: $ref: '#/components/schemas/urn_samm_io.catenax.early_warning_notification_1.0.0_Items' urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_ResourcePath: type: string format: uri description: The path of a resource. urn_samm_io.catenax.early_warning_notification_1.0.0_ValuesCharacteristic: description: Characteristic for the values in the value list type: array items: type: string urn_samm_io.catenax.early_warning_notification_1.0.0_PopulationFilter: description: Population filter for the early warning data type: object properties: aspectProperty: description: A property from the aspect model referenced by "aspectModel" $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text' aspectModel: description: A reference to an aspect model standardized by Catena-X for the quality use case $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_ResourcePath' rangeFrom: description: 'Start value of a value range for an aspect property ' $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text' rangeTo: description: 'End value of a value range for an aspect property ' $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text' valueList: description: A list of values for the aspect property $ref: '#/components/schemas/urn_samm_io.catenax.early_warning_notification_1.0.0_ValuesCharacteristic' required: - aspectProperty - aspectModel urn_samm_io.catenax.early_warning_notification_1.0.0_PopulationFilterListCharacteristic: description: Characteristic for a List of Population Filters type: array items: $ref: '#/components/schemas/urn_samm_io.catenax.early_warning_notification_1.0.0_PopulationFilter' EarlyWarningNotification: type: object properties: notificationId: description: 'A unique ID for the EW notification ' $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' relatedQualityTaskID: description: An ID to reference an existing early warning project and its data $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text' information: description: Some text describing the detected anomaly in the data $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text' status: description: A status information about the current status of the quality process triggered by this notification. $ref: '#/components/schemas/urn_samm_io.catenax.early_warning_notification_1.0.0_Status' severity: description: A flag indicating the severity of the quality issue $ref: '#/components/schemas/urn_samm_io.catenax.early_warning_notification_1.0.0_Severity' listOfAffectedItems: description: List of unique identifiers to explicitly specify parts or vehicles exhibiting the issue described in the property "Information" $ref: '#/components/schemas/urn_samm_io.catenax.early_warning_notification_1.0.0_AffectedItemsCharacteristic' poulationFilterList: description: A set of Population Filters $ref: '#/components/schemas/urn_samm_io.catenax.early_warning_notification_1.0.0_PopulationFilterListCharacteristic' earlyWarningAttachmentLink: description: This property provides a reference to an EDC asset that will contain a zip file organized according to the specification CX-0092 and the model defined in io.catenax.quality_task_attachment:1.0.0. The zip file will contain additional data describing the early warning case. $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Text' required: - notificationId - relatedQualityTaskID - status - severity - listOfAffectedItems # ----------------------------------------- # Schema: io.catenax.shared.message_header # ----------------------------------------- urn_samm_io.catenax.shared.uuid_1.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.message_header_2.0.0_ContextCharacteristic: type: string enum: - urn:samm:io.catenax.early_warning_notification:1.0.0 description: The context defines the type of quality notification. The context is chosen by the initiator of a quality notification. urn:samm:io.catenax.early_warning_notification:1.0.0 An early-warning-notification is sent to inform the partner in an early warning project about a potential quality issue that was detectected from an analaysis of the mutually exchanged quality data and requests verification by the partner. 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. 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. 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." 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.business_partner_number_1.0.0_BpnlTrait: type: string description: "The provided regular expression ensures that the BPNL is composed\ \ of prefix 'BPNL', 10 digits and two uppercase letters." pattern: "^BPNL[0-9]{8}[a-zA-Z0-9]{4}$" urn_samm_io.catenax.shared.message_header_2.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:2.0.0#MessageHeaderAspect" urn_samm_io.catenax.shared.message_header_2.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. In case of traceability quality notifications this means the following. A UUIDv4 to uniquely identify a quality notification. This unique ID gets generated by the initiator of a quality notification. The sender and receiver of a quality notification use this unique ID to reference a quality notification. $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_1.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. Traceability-QualityNotification-Alert:2.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_2.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_1.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_1.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 In case of early warning notifications this means the following. A UUIDv4 to uniquely identify a related early warning notification. This field is not about mapping the internal references between early warning notifications. This field should only reference the early warning notifications that (a) the recipient can basically understand in his business context and (b) that are of concern to the recipient That means, that in most instances, the sender and receiver of both early warning notifications (i.e., the sent one and the referenced one) are the same. Example During an Early Warning Project an Early Warning Notification is created and referencing to the Early Warning Project. This is followed by another QM-Investigation that is referencing to the same quality issue. $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_1.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_2.0.0_SemanticVersioningTrait' required: - messageId - context - sentDateTime - senderBpn - receiverBpn - version