Reading an ISO 20022 Usage Guideline: The Four Layers That Decide Your Field Rules

The same pacs.008 field can be optional in the ISO 20022 base standard, mandatory under the scheme’s usage guideline, prohibited by a bilateral agreement with your correspondent, and missing entirely from your source database. Four layers, and only the net of all four tells a developer what to build. Producing that net, element by element, is the analyst’s job on any ISO 20022 implementation.

Most ISO 20022 confusion is a layering problem wearing a costume. A tester raises a defect because the message rejects a field the specification says is optional. A developer insists the schema allows something the scheme forbids. A correspondent asks for a field nobody can source. All three are the same question asked at different levels: which rule wins?

The answer is that the rules stack, each one narrowing the last, and the effective rule is the tightest constraint in the stack. Once you see that, the arguments stop. This sits directly on top of ISO 20022 as an architecture: the model gives you the vocabulary, and the guideline layer is where a real implementation actually lives. The requirements craft this depends on is the subject of From Vague BR to Functional Requirements.

What are the four layers?

Layer 1, the ISO 20022 base message definition. The message as published by ISO, expressed as an XSD schema, for example pacs.008.001.13. It is deliberately permissive because it must serve every market on earth: a domestic instant payment scheme and a cross-border correspondent chain use the same base message. Almost everything is optional here, which is exactly why reading only this layer misleads people into thinking ISO 20022 has few rules.

Layer 2, the scheme usage guideline. The market practice restriction for one rail: CBPR+ for cross-border payments over SWIFT, or the equivalent published by a domestic real-time scheme, a regional clearing system, or a central bank platform. This layer does the heavy lifting. It makes elements mandatory, removes elements outright, cuts code lists down to the codes the scheme actually processes, restricts character sets, and adds textual rules the schema cannot express.

Layer 3, the bilateral or community agreement. What you and a specific counterparty have agreed beyond the scheme, or what a market community adds on top. A correspondent who cannot process structured remittance information, an agreement to always populate a purpose code, a service level that requires a particular charge bearer. This layer is frequently undocumented and lives in an email thread, which is a finding worth raising the moment you discover it.

Layer 4, your implementation. What your system actually sends and accepts today. Not what the design says, what the code does. The field your source system truncates at 35 characters because it was modelled on MT. The element your parser ignores. This layer is discovered by testing, not by reading.

The direction only ever goes one way. Each layer may narrow the one above it and may never widen it. A guideline cannot make a base-mandatory element optional, cannot lengthen a field, and cannot invent a code the base standard does not define. When it looks like one has, check the message version, because you are almost certainly comparing two different ones.

What does a restriction actually look like?

Guidelines express restrictions in a small vocabulary, and knowing it turns a hundred page document into something you can skim.

Restriction	Means	Example
Cardinality change	[0..1] becomes [1..1]	An optional element becomes mandatory for this scheme
Removed or Not used	The element must not be present	A party or block the scheme does not process
Multiplicity reduction	[0..n] becomes [0..1]	Unstructured remittance limited to a single occurrence
Code list restriction	A subset of the base enumeration	Only the charge bearer codes this rail settles
Fixed value	The element must carry one value	A fixed service level or local instrument code
Format restriction	A tighter pattern or character set	Latin subset only, no accented characters
Textual rule	A condition the schema cannot express	If one element is present, another becomes mandatory

That last row is where the real work is, and it is the row that explains most production rejections. A schema can say an element is optional; only a textual rule can say it is mandatory when the debtor agent and creditor agent are in different countries. Rules like that are enforced by the scheme’s validator, not by your XSD, which is why a schema-valid message still gets rejected.

For a payments analyst the practical reading order is: cardinality changes first, because they change what you must source; then removals, because they change what you must suppress; then textual rules, because they are the test cases nobody writes; then code lists and formats, which are usually a lookup table.

What is the deliverable? The net rule matrix

One artifact answers the question every developer, tester, and counterparty will otherwise ask separately. One row per element you populate or consume, one column per layer, and a final column for the effective rule.

Element	ISO base	Scheme guideline	Bilateral	Our system	Net rule
Dbtr/Nm	[0..1], 140 chars	[1..1], 140 chars	none	35 chars from CIF	Mandatory, but we can only source 35. Gap.
Dbtr/PstlAdr/Ctry	[0..1], ISO 3166	[1..1] for cross-border	none	Present, sometimes null	Mandatory. Null handling required.
Dbtr/PstlAdr/AdrLine	[0..7], 70 chars	Restricted, see address rules	none	4 lines of 35	Constrained by the address mandate.
RmtInf/Ustrd	[0..n], 140 chars	[0..1]	Correspondent cannot process Strd	140 chars	One occurrence, 140 chars, unstructured only.
PmtId/UETR	[0..1]	[1..1]	none	Generated at submission	Mandatory. Immutability test required.
ChrgBr	[0..1], full code list	[1..1], subset	Always SHAR	Configurable	Mandatory, fixed to SHAR for this counterparty.

Three things this matrix does that prose cannot.

It makes gaps visible as data. Row one is a genuine finding: the scheme demands a field of up to 140 characters and your customer information file holds 35. That is a data sourcing project, and it is far cheaper discovered in analysis than in system integration testing. It is also the entry point to the wider truncation problem.

It collapses four documents into one answer. The developer does not read the guideline, the bilateral email, and the source system data dictionary. They read the net column.

It generates the tests. Every effective rule yields at least one positive case and one negative case: mandatory means test it present and test it absent, fixed value means test the value and test a different value, restricted code list means test an in-list code and an out-of-list code. That derivation is mechanical, which is why the matrix is the input to a pacs.008 test suite rather than a document that sits beside one. The template structures for artifacts like this are in Real-World BA Deliverables.

Why does the message version matter so much?

Because a usage guideline pins one, and the pinned version is part of the contract.

pacs.008.001.08 and pacs.008.001.13 are different messages. Elements are added between versions, cardinalities change, and structures are reorganised. The namespace in your XML declares which one you are sending, so a message built to the wrong version is rejected before any business rule is evaluated. Two consequences follow that programmes routinely miss.

Your evidence has a version. A field rule you confirmed by reading a guideline last year may not hold in the version the scheme has since moved to. When you record a rule in the matrix, record the guideline and version it came from, the same way you would cite a source in any functional specification.

Coexistence means two contracts at once. During a scheme’s migration window you may need to send one version to one counterparty and another elsewhere, which means the net rule matrix has a version dimension, and your test suite needs a run per version. Teams that treat the version as a deployment detail discover this during dress rehearsal.

Who actually owns the answer?

Half the time lost on these questions is spent asking the wrong party, so it is worth being explicit about who can answer what.

Question	Ask
What does this element mean in the data model?	The ISO message definition and the base standard
Is it mandatory on this rail?	The scheme usage guideline, current version
Which codes will actually be processed?	The scheme guideline’s restricted code list
Will our correspondent do anything sensible with it?	The counterparty, in writing
Can we source it?	The source system owner and the data dictionary
What do we send today?	A captured production or pre-production message

The last row is the one analysts skip and should not. A single captured message from your own outbound flow settles more arguments than a week of document reading, because it is evidence of layer four rather than an assertion about it. Get one early, keep it in your reference notes, and redact the identifiers before it goes anywhere near a shared page.

The fourth row deserves the same insistence on evidence. “Our correspondent supports structured remittance” is a claim until somebody has sent one and seen what came out the other end, and the difference between the claim and the test is the entire truncation ledger.

How does this change the way you write requirements?

It changes what a requirement is about. On a domestic system a functional requirement describes behaviour you are choosing. On an ISO 20022 implementation most field-level requirements describe behaviour you are being told, and your job is to state it precisely, cite it, and identify where you cannot comply.

That gives a useful shape for a message population requirement:

REQ-114. Dbtr/Nm shall be populated with the debtor’s legal name, mandatory, maximum 140 characters. Source: CBPR+ pacs.008 usage guideline, cardinality restricted to [1..1]. Constraint: the customer information file stores 35 characters, so values are complete only for names within that length. Where the source value is absent, the payment shall be rejected at submission with an internal validation error rather than sent for scheme rejection.

Four parts, and each earns its place. The rule. The citation, so the next analyst can verify it without repeating the research. The known constraint, stated rather than hidden. And the behaviour when the rule cannot be met, which is the part that gets forgotten and then becomes an incident, because “reject at submission” and “let the scheme reject it” are wildly different operational outcomes: one is a message to a customer in seconds, the other is a payment repair queue and a service level breach.

That last clause is also where a non-functional requirement usually hides. Rejecting locally requires the validation to run at submission time, which is a latency budget and a deployment dependency, not just a rule.

The takeaway

Four layers decide an ISO 20022 field rule, and each may only narrow the one above it: the ISO base message definition, the scheme usage guideline, any bilateral agreement with a counterparty, and what your own system actually does. The effective rule is the tightest constraint in the stack, and no single document contains it.

Build the net rule matrix, one row per element with a column per layer and an effective rule, because it makes data sourcing gaps visible, gives developers one place to look, and generates test cases mechanically. Pin the message version on every rule you record, since guidelines are written against a specific one. Remember that schema validity is not scheme acceptance, because the restrictions that matter most are textual rules an XSD cannot express. And settle layer four with a captured message rather than a document, because what your system actually sends is evidence, and everything else is a claim.

Start with From Vague BR to Functional Requirements for turning rules into buildable specifications, and Real-World BA Deliverables for the matrix and specification templates, or browse everything at The Tech BA Toolkit.

Ahmed is a Senior Technical Business Analyst with 10+ years in banking and payments. He builds practical guides and tools for analysts at The Tech BA Toolkit.

Tags: ISO 20022, Requirements, Functional Analysis, Payments, Banking