Release 2027 · Schema version 001.05 · Active

SIVI message 5 (00541): Trade instruction (VB-PUO)

With the trade instruction the PUO places net buy and sell orders at the highest fund level: participant mutations have already been translated into net transactions per investment fund. Switches between funds are delivered as two coupled orders. The message contains only what the executing party needs; the underlying sub-ordering is done by the fund provider.

Sender

Pension administrator (PUO)

Receiver

Investment administrator (BA). The party that processes the order can be a broker, transfer agent or order desk; that does not change the data exchange (manual sections 4.2, 4.3.5)

Timing

In the FPR monthly cycle at T-4; ad hoc otherwise

Arrangement

FPR: orders (messages 5 and 6)

afdDefinitionName

VBPUO-001.00-Bericht_5._Orderopdracht_(00541)

Message structure

Entities with cardinality [min..max] and number of attributes; click for the entity page.

chunking.default[0..1] · 4 attr.
commonFunctional.default[1..1] · 4 attr.
commonTechnical.default[1..1] · 3 attr.
- party.receiver[1..1] · 3 attr.
- party.sender[1..1] · 4 attr.
  - party.contact[0..9] · 2 attr.
document.default[0..99] · 3 attr.
party.pensionProvider[1..1] · 3 attr.
- pension.scheme[1..999] · 3 attr.
  - financialInformation.reportingPeriod[1..1] · 1 attr.
  - investment.investmentDetails[1..999] · 3 attr.
    - financialTransaction.trade[1..99] · 7 attr.

Attributes (40)

Entity	Attribute	Type	V/O	Code list	Description
chunking.default	currentChunkId	string · max 70	V		Unique reference (id) of the current chunk.
chunking.default	chunkSequenceNumber	integer	V		Sequence number of the current chunk.
chunking.default	totalNumberOfChunks	integer	V		Total number of chunks the message has been split into.
chunking.default	chunkFragmentPaths	array[string]	V		Array of JMESPath references to the message fragments used within the current chunk.
commonFunctional.default	afdDefinitionVersion	string · max 80	V	001.05	Version of the AFD-definition.
commonFunctional.default	afdDefinitionName	string · max 80	V	VBPUO-001.00-Bericht_5._Orderopdracht_(00541)	Name of the AFD-definition.
commonFunctional.default	originalMessageId	string · max 70	O		The messageId of the original message, which is replaced by this message.
commonFunctional.default	function	string	V	ADNFUN	Message function
commonTechnical.default	creationDateTime	string · format date-time	V		Date and time (as timestamp) when the message was created.
commonTechnical.default	testMessage	boolean	O		Indication whether the message is a test message.
commonTechnical.default	messageId	string · max 70	V		Unique identification of the message. (AFD 2.0 only)
party.receiver	refKey	string · max 70	V		Unique reference key assigned to an entity.
party.receiver	organizationName	string · max 60	V		Name of professional or branch organization.
party.receiver	rsinNumber	string · max 9	O		Governmental identification number for legal entities and associations. (AFD 2.0 only)
party.sender	refKey	string · max 70	V		Unique reference key assigned to an entity.
party.sender	applicationSenderName	string · max 60	O		Name of the application that sends the data.
party.sender	organizationName	string · max 60	V		Name of professional or branch organization.
party.sender	rsinNumber	string · max 9	O		Governmental identification number for legal entities and associations. (AFD 2.0 only)
party.contact	emailWork	string · max 60	V		Work email address.
party.contact	workPhoneNumber	string · max 60	V		Work telephone number.
document.default	refKey	string · max 70	V		Unique reference key assigned to an entity.
document.default	fileName	string · max 60	V		Name of the file under which the attachment can be saved.
document.default	fileExtension	string	V	pdf \| csv \| txt	Extension of the file under which the attachment can be saved. For example "pdf", "doc", etc.
party.pensionProvider	organizationName	string · max 60	V		Name of professional or branch organization.
party.pensionProvider	rsinNumber	string · max 9	O		Governmental identification number for legal entities and associations. (AFD 2.0 only)
party.pensionProvider	puvCode	string	V	AFDIDP	Pension provider
pension.scheme	refKey	string · max 70	V		Unique reference key assigned to an entity.
pension.scheme	pensionSchemeName	string · max 60	V		Name of the pension scheme.
pension.scheme	tradingPortfolioId	string · max 10	V		Custodian's trading portfolio ID (custody and management of financial assets).
financialInformation.reportingPeriod	instructionDate	string · format date	V		Instruction date (date of the order sent by the pension administration organization).
investment.investmentDetails	refKey	string · max 70	V		Unique reference key assigned to an entity.
investment.investmentDetails	description	string · max 60	V		Description.
investment.investmentDetails	currencyType	string	V	ISOVAL	Currency
financialTransaction.trade	refKey	string · max 70	V		Unique reference key assigned to an entity.
financialTransaction.trade	financialInformationRef	array[string]	O		Verwijs hier bij switchfrom/switchto naar de refKey van de andere switch-leg ten behoeve van verbandscontrole.
financialTransaction.trade	tradeDate	string · format date	V		Desired trade date.
financialTransaction.trade	tradeAmount	number · multipleOf 0.01	O		Positief bedrag van de transactie in de valuta waarin de belegging luidt; richting volgt uit buySellId
financialTransaction.trade	tradeQuantity	number · multipleOf 0.000001	O		Positief aantal te verhandelen stukken (units) van de transactie; richting volgt uit buySellId
financialTransaction.trade	switchType	string	O	AFDSWI	Type switch; one-day of sequential
financialTransaction.trade	buySellId	string	V	sell \| buy \| switchfrom \| switchto	Aan-, verkoop- of switchrichtingindicator

Sample message

✓ Validated against schema VBPUO-001.05 · 2026-10-14

Sample source: SIVI voorbeeldbericht (Voorbeeldbericht_5-buy). Values are fictitious.

{
  "commonFunctional": [
    {
      "entityType": "default",
      "function": "01",
      "afdDefinitionName": "VBPUO-001.00-Bericht_5._Orderopdracht_(00541)",
      "afdDefinitionVersion": "001.05",
      "originalMessageId": "20240529 1532"
    }
  ],
  "commonTechnical": [
    {
      "entityType": "default",
      "messageId": "67890",
      "creationDateTime": "2024-10-07T10:00:00Z",
      "testMessage": false,
      "party": [
        {
          "entityType": "receiver",
          "refKey": "recv001",
          "rsinNumber": "123456789",
          "organizationName": "Pension Fund A"
        },
        {
          "entityType": "sender",
          "rsinNumber": "876543219",
          "organizationName": "Investment Firm B",
          "refKey": "send001",
          "applicationSenderName": "InvestAppV1"
        }
      ]
    }
  ],
  "party": [
    {
      "entityType": "pensionProvider",
      "puvCode": "U0003",
      "rsinNumber": "112233449",
      "organizationName": "St. Pf. Openbare Bibliotheken",
      "pension": [
        {
          "entityType": "scheme",
          "refKey": "schemeXYZ",
          "pensionSchemeName": "Investment Scheme A",
          "tradingPortfolioId": "Trade123",
          "financialInformation": [
            {
              "entityType": "reportingPeriod",
              "instructionDate": "2024-01-02"
            }
          ],
          "investment": [
            {
              "entityType": "investmentDetails",
              "refKey": "inv001",
              "description": "Equity Fund",
              "currencyType": "EUR",
              "financialTransaction": [
                {
                  "entityType": "trade",
                  "refKey": "trade123",
                  "buySellId": "buy",
                  "tradeDate": "2024-01-03",
                  "tradeAmount": 10000
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "document": []
}

Variant: Voorbeeldbericht_5-buy-sell

{
  "commonFunctional": [
    {
      "entityType": "default",
      "function": "01",
      "afdDefinitionName": "VBPUO-001.00-Bericht_5._Orderopdracht_(00541)",
      "afdDefinitionVersion": "001.05",
      "originalMessageId": "20240529 1532"
    }
  ],
  "commonTechnical": [
    {
      "entityType": "default",
      "messageId": "67890",
      "creationDateTime": "2023-12-30T12:00:00Z",
      "testMessage": false,
      "party": [
        {
          "entityType": "receiver",
          "refKey": "recv001",
          "rsinNumber": "123456789",
          "organizationName": "Pension Fund A"
        },
        {
          "entityType": "sender",
          "rsinNumber": "876543219",
          "organizationName": "Investment Firm B",
          "refKey": "send001",
          "applicationSenderName": "InvestAppV1"
        }
      ]
    }
  ],
  "party": [
    {
      "entityType": "pensionProvider",
      "rsinNumber": "112233449",
      "puvCode": "U0003",
      "organizationName": "St. Pf. Openbare Bibliotheken",
      "pension": [
        {
          "entityType": "scheme",
          "refKey": "schemeXYZ",
          "pensionSchemeName": "Investment Scheme A",
          "tradingPortfolioId": "Trade123",
          "financialInformation": [
            {
              "entityType": "reportingPeriod",
              "instructionDate": "2024-01-02"
            }
          ],
          "investment": [
            {
              "entityType": "investmentDetails",
              "refKey": "inv001",
              "description": "Equity Fund",
              "currencyType": "EUR",
              "financialTransaction": [
                {
                  "entityType": "trade",
                  "refKey": "trade123",
                  "buySellId": "buy",
                  "tradeDate": "2024-01-03",
                  "tradeAmount": 10000
                },
                {
                  "entityType": "trade",
                  "refKey": "trade124",
                  "buySellId": "sell",
                  "tradeDate": "2024-01-04",
                  "tradeQuantity": 50
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "document": []
}

Variant: Voorbeeldbericht_5-buy-sell-switch

{
  "commonFunctional": [
    {
      "entityType": "default",
      "function": "01",
      "afdDefinitionName": "VBPUO-001.00-Bericht_5._Orderopdracht_(00541)",
      "afdDefinitionVersion": "001.05",
      "originalMessageId": "20240529 1532"
    }
  ],
  "commonTechnical": [
    {
      "entityType": "default",
      "messageId": "67890",
      "creationDateTime": "2024-10-07T10:00:00Z",
      "testMessage": false,
      "party": [
        {
          "entityType": "receiver",
          "refKey": "recv001",
          "rsinNumber": "123456789",
          "organizationName": "Pension Fund A"
        },
        {
          "entityType": "sender",
          "rsinNumber": "876543219",
          "organizationName": "Investment Firm B",
          "refKey": "send001",
          "applicationSenderName": "InvestAppV1"
        }
      ]
    }
  ],
  "party": [
    {
      "entityType": "pensionProvider",
      "puvCode": "U0003",
      "rsinNumber": "112233449",
      "organizationName": "St. Pf. Openbare Bibliotheken",
      "pension": [
        {
          "entityType": "scheme",
          "refKey": "schemeXYZ",
          "pensionSchemeName": "Investment Scheme A",
          "tradingPortfolioId": "Trade123",
          "financialInformation": [
            {
              "entityType": "reportingPeriod",
              "instructionDate": "2024-01-02"
            }
          ],
          "investment": [
            {
              "entityType": "investmentDetails",
              "refKey": "inv001",
              "description": "Equity Fund",
              "currencyType": "EUR",
              "financialTransaction": [
                {
                  "entityType": "trade",
                  "refKey": "trade123",
                  "buySellId": "buy",
                  "tradeDate": "2024-01-03",
                  "tradeAmount": 10000
                },
                {
                  "entityType": "trade",
                  "refKey": "trade124",
                  "buySellId": "sell",
                  "tradeDate": "2024-01-04",
                  "tradeQuantity": 50
                }
              ]
            }
          ]
        },
        {
          "entityType": "scheme",
          "refKey": "schemeABC",
          "pensionSchemeName": "Retirement Plan B",
          "tradingPortfolioId": "Trade456",
          "financialInformation": [
            {
              "entityType": "reportingPeriod",
              "instructionDate": "2024-01-05"
            }
          ],
          "investment": [
            {
              "entityType": "investmentDetails",
              "refKey": "inv002",
              "description": "Accumulation phase fund",
              "currencyType": "EUR",
              "financialTransaction": [
                {
                  "entityType": "trade",
                  "refKey": "trade125",
                  "buySellId": "switchfrom",
                  "tradeDate": "2024-01-06",
                  "switchType": "1",
                  "financialInformationRef": [
                    "trade126",
                    "inv003"
                  ],
                  "tradeQuantity": 20
                }
              ]
            },
            {
              "entityType": "investmentDetails",
              "refKey": "inv003",
              "description": "CVP fund",
              "currencyType": "EUR",
              "financialTransaction": [
                {
                  "entityType": "trade",
                  "refKey": "trade126",
                  "buySellId": "switchto",
                  "tradeDate": "2024-01-06",
                  "financialInformationRef": [
                    "trade125",
                    "inv002"
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "document": []
}

Rules and consistency checks

Since Release 2027 exactly one of tradeAmount (amount) and tradeQuantity (quantity) is filled per order; filling both is not allowed (manual section 6.3.2, issue #116). An instruction with an amount component and a quantity component becomes two separate trade records. Both empty is allowed only on the order of a switch that does not steer; that can be the switchfrom or the switchto order.
A switch consists of two orders: buySellId = switchfrom and buySellId = switchto. They refer to each other via financialInformationRef, which holds the refKey of the other order. Per switch pair exactly one order carries an amount or a quantity; the other carries neither (manual section 6.3.2). tradeAmount and tradeQuantity are always positive (section 4.3.5).
switchType (code list AFDSWI) indicates whether the switch is executed sequentially (code 1) or on one day (code 2). The schema refers to the code-list file next to the schema for this, not to sivi.org.
investment.investmentDetails identifies the fund (refKey, description, currencyType); the identifier convention (for example ISIN) is agreed bilaterally.

Pitfalls

Older implementations still use buySellId = switch (Release 2026); Release 2027 only knows switchfrom and switchto. A receiver on 2027 rejects an old switch.
A negative amount to indicate a sale is wrong: direction is in buySellId, not in the sign.
A validator that does not find the code-list file next to the schema (switchType refers to …-afdCodelists.json, not to sivi.org) cannot compile the schema of the final Release 2027. Register that file next to the code lists of sivi.org.

Errors and fixes

messageId missing, empty or longer than 70 charactersSchema error on commonTechnical/0/messageId: 'must have required property' or 'must NOT have more than 70 characters'.
Duplicate messageId after acceptance (HTTP 400 with feedback)The receiver answers HTTP 400 with a feedback message (statusType 0) to a message that looks correct in content.
afdDefinitionName incorrect (a fixed value since the final Release 2027)Schema error 'must be equal to constant' on afdDefinitionName; the WTP Data Lab validator names the expected value. Typical of a message built on the July 2026 pre-release: it states the right version 001.05 and still fails.
afdDefinitionVersion incorrect (001.04 versus 001.05)Schema error 'must be equal to one of the allowed values' on afdDefinitionVersion, or the receiver validates against the wrong schema and reports unknown fields.
tradeAmount and tradeQuantity both filled or both empty (message 5)The receiver rejects the order functionally (feedback statusType 0) or executes an unintended quantity.
switchfrom without switchto, or financialInformationRef missingThe receiver cannot form the switch pair and rejects the order.
switchType invalid (AFDSWI)Schema error on switchType.
buySellId invalidSchema error 'must be equal to one of the allowed values' on buySellId.
tradeAmount or tradeQuantity negativeSchema-valid, but the receiver interprets the sign differently from the intention.
Schema draft mismatch: definitions versus $defs, draft 2019-09 versus 2020-12The validator reports 'can't resolve reference', MissingRefError or 'no schema with key or ref' when loading the schema, before the message is tested.

Frequently asked questions

What happens if an order cannot be executed (unknown fund, invalid combination)?

The receiver sends a feedback message with statusType 0 (rejected) and a classified errorCode. The PUO then sends a corrected order with a new messageId.

Can I serve several funds in one message?

Yes: the message carries the investmentDetails of the fund per transaction; several transactions in one message are allowed.

Change history

v1.2.0 (November 2024): numberOfUnits added.
v1.4.0 (Release 2027): switch replaced by switchfrom/switchto with positive amounts; JSON Schema 2020-12.
Final Release 2027 (12 October 2026): order rules in the new section 6.3.2, one order steers per switch pair; switchType with codes 1 and 2 via the code-list file. SIVI's pre-release samples filled amount and quantity together, the final ones follow the rule (issue #116).

Schema file: VBPUO-001.00-Bericht_5._Orderopdracht_(00541).json · JSON-schema (001.05) · code-list file for this schema · GitHub