How to handle references when more than 2 parties in a use case?

[larsolofsson]

An example of a use case with 3 parties

• Supplier is responsible for providing the product.
• Logistics Supplier A is responsible for distributing the products having the business role of a Forwarder. The Shipment Number is created by the Logistics Supplier A
• Logistics Supplier B is responsible for the warehouse from where the products are dispatched having the business role of a Warehouse Operator (or Storage Operator). Logistics Supplier B is also responsible for loading of the products.

A party can have many business roles.

Logistics Supplier B needs to get the Shipment Number created by Logistics Supplier A.

The Supplier communicates with Logistics Supplier A and Logistics Supplier B via API:s
For example, A Loading Instruction created by Logistics Supplier A with a reference to the Shipment Number is sent to the Supplier. The Supplier needs to send this information to Logistics Supplier B as a Loading Instruction created by the Supplier with a reference to the ShipmentNumber created by the Logistics Supplier A.

After loading Logistics Supplier B sends a Delivery Note to the Supplier with references to the Loading Instruction created by the Supplier and the ShipmentNumber created by the Logistics Supplier A. The Supplier needs to send this information to Logistics Supplier A as a Delivery Note created by the Supplier with references to the Loading Instruction created by the Logistics Supplier A and to the ShipmentNumber created by the Logistics Supplier A.

So far in existing use cases having only 2 parties, references are given in properties, e.g. deliveryInstructionNumber, deliveryInstructionSequenceNumber and deliveryInstructionSequenceLineItemNumber.

I think that papiNet should have a more general and flexible reference construct similar to the reference construct in the XML standard using assigned by business roles and agencies. But without a requirement to specify the parties of the business roles. Related properties to a reference type should be possible to be specified, e.g. deliveryInstructionSequenceNumber, deliveryInstructionSequenceLineItemNumber and dateTime are related to reference type deliveryInstructionNumber. References by other means than API properties should also be possible to be specified.

API endpoints are still specified in logistics with 2 parties Supplier and Logistics Supplier.

Proposed reference construct

  references:
    type: array
    minItems: 1
    items:
      type: object
      unevaluatedProperties: false
      required:
        - type
        - assignedBy
      anyOf:
        - required:
            - id
        - required:
            - identifier
      properties:
        type:
          type: string
          enum:
            - DeliveryNoteNumber
            - LoadingInstructionNumber
            - ShipmentNumber
        assignedBy:
          description: The business role of the assigning party.
          type: string
          enum:
            - Forwarder
            - Supplier
            - WarehouseOperator
        id:
          type: string
          format: uuid
        identifier:
          type: object
          unevaluatedProperties: false
          required:
            - value
            - assignedByIdentifierBySupplier
          properties:
            value:
              type: string
              minLength: 1
            assignedByIdentifierBySupplier:
              type: string
              minLength: 1
              description: The identifier of the assigning party assigned by the _Supplier_.
        dateTime:
          type: string
          format: date-time
        sequenceNumber:
          type: integer
          minimum: 0
        lineItemNumber:
          type: integer
          minimum: 0

[PetterThy]

Hi,

1. I have read this though together with Bo-Göran and we don't fully understand the need for below sentence. From my point of view process stops here and we, as a supplier, do not provide Delivery Note to Supplier A that has arrange transport.

The Supplier needs to send this information to Logistics Supplier A as a Delivery Note created by the Supplier with references to the Loading Instruction created by the Logistics Supplier A and to the ShipmentNumber created by the Logistics Supplier A.

2. assignedByidentifierBySupplier should be adjusted to - assignedByIdentifierBySupplier if we should have it. Here I need to understand the full picture and benefit of introducing this new identifier. Is the "assigning party" = logistics supplier in this example?

[larsolofsson]

1. Logistics Supplier A is responsible for distributing a certain quantity of products by issueing Loading Instructions. I think they should have a feed back about how much has been loaded, so they can check that everything has been loaded according to the Delivery Instruction received from the Supplier. Parties issueing a Loading Instructions normally receive a Delivery Note as a confimation what has been loaded.
   Logistics Supplier A might also what to send an electronic Delivery Note to the Carrier.

I think papiNet should include this Delivery Note in the use case even though it is not sent by StoraEnso.

2. Yes, assignedByidentifierBySupplier should be adjusted to - assignedByIdentifierBySupplier.
   assignedByIdentifierBySupplier is needed for having a unique identifier of the reference, when having more than 2 parties in use case.

[larsolofsson]

A Json example from schema with the above array reference construct.

{
	"references": [
		{
			"type": "ShipmentNumber",
			"assignedBy": "Forwarder",
			"identifier": {
				"value": "SN20260604-001",
				"assignedByIdentifierBySupplier": "abcd"
			}
		},
		{
			"type": "LoadingInstructionNumber",
			"assignedBy": "Forwarder",
			"identifier": {
				"value": "LI20260604-002",
				"assignedByIdentifierBySupplier": "abcd"
			},
			"dateTime": "2026-06-04T09:30:47.0",
			"sequenceNumber": 1,
			"lineItemNumber": 2
		}
	]
}

[larsolofsson]

A reference construct without an array as discussed as an option at CWG meeting.

# The schema properties need to be repeated for each reference type and assignedBy when the same endpoint is used by several parties
# For example, having 3 reference types and 3 assignedBy, than the schema properties need to be repated 9 times.
#
type: object
unevaluatedProperties: false
properties:
  shipmentNumberByForwarder:
    type: object
    unevaluatedProperties: false
    anyOf:
      - required:
          - id
      - required:
          - identifier
    properties:
      id:
        type: string
        format: uuid
      identifier:
        type: object
        unevaluatedProperties: false
        required:
          - value
          - assignedByIdentifierBySupplier
        properties:
          value:
            type: string
            minLength: 1
          assignedByIdentifierBySupplier:
            type: string
            minLength: 1
            description: The identifier of the assigning party assigned by the _Supplier_.
      dateTime:
        type: string
        format: date-time
      sequenceNumber:
        type: integer
        minimum: 0
      lineItemNumber:
        type: integer
        minimum: 0
  shipmentNumberBySupplier:
    type: object
    unevaluatedProperties: false
    anyOf:
      - required:
          - id
      - required:
          - identifier
    properties:
      id:
        type: string
        format: uuid
      identifier:
        type: object
        unevaluatedProperties: false
        required:
          - value
          - assignedByIdentifierBySupplier
        properties:
          value:
            type: string
            minLength: 1
          assignedByIdentifierBySupplier:
            type: string
            minLength: 1
            description: The identifier of the assigning party assigned by the _Supplier_.
      dateTime:
        type: string
        format: date-time
      sequenceNumber:
        type: integer
        minimum: 0
      lineItemNumber:
        type: integer
        minimum: 0
  loadingInstructionByForwarder:
    type: object
    unevaluatedProperties: false
    anyOf:
      - required:
          - id
      - required:
          - identifier
    properties:
      id:
        type: string
        format: uuid
      identifier:
        type: object
        unevaluatedProperties: false
        required:
          - value
          - assignedByIdentifierBySupplier
        properties:
          value:
            type: string
            minLength: 1
          assignedByIdentifierBySupplier:
            type: string
            minLength: 1
            description: The identifier of the assigning party assigned by the _Supplier_.
      dateTime:
        type: string
        format: date-time
      sequenceNumber:
        type: integer
        minimum: 0
      lineItemNumber:
        type: integer
        minimum: 0
  loadingInstructionBySupplier:
    type: object
    unevaluatedProperties: false
    anyOf:
      - required:
          - id
      - required:
          - identifier
    properties:
      id:
        type: string
        format: uuid
      identifier:
        type: object
        unevaluatedProperties: false
        required:
          - value
          - assignedByIdentifierBySupplier
        properties:
          value:
            type: string
            minLength: 1
          assignedByIdentifierBySupplier:
            type: string
            minLength: 1
            description: The identifier of the assigning party assigned by the _Supplier_.
      dateTime:
        type: string
        format: date-time
      sequenceNumber:
        type: integer
        minimum: 0
      lineItemNumber:
        type: integer
        minimum: 0
  # The schema properties need to be repeated for each reference type and assignedBy

A Json example based on this schema

{
	"shipmentNumberByForwarder": {
		"identifier": {
			"value": "SN20260604-001",
			"assignedByIdentifierBySupplier": "abcd"
		}
	},
	"loadingInstructionByForwarder": {
		"identifier": {
			"value": "LI20260604-002",
			"assignedByIdentifierBySupplier": "abcd"
		},
		"dateTime": "2026-06-04T09:30:47.0",
		"sequenceNumber": 1,
		"lineItemNumber": 2
	}
}

[larsolofsson]

CWG decided on 2026-06-10 to use the references construct.