Configure tag dictionaries

Tag dictionaries tell Tara which tags belong to the same party, what each value means, and which values are not entities. Tara uses this information to populate the screened data for each hit, such as the party's name, address, country, and identifiers.

Tara selects the parser based on the message's content format and type, and then selects the corresponding dictionary automatically. Dictionaries are stored in S3 at doc-upload/payment_sanctions_screening/{version}/tag-dictionary/. The following dictionaries are used:

• pss_fuf_tags_list.csv: Fircosoft Unified Format (FUF) messages

• pss_swift_tags_list.csv: SWIFT MT and SWIFT ADK messages

• pss_iso20022_tags_list.csv: ISO 20022 messages, including PACS messages

• pss_suffix_tags_list.csv: fallback typing and grouping by tag-name suffix for FUF tags absent from the main FUF dictionary

The filenames are fixed. To add mappings, update the existing file; introducing another dictionary filename requires a code change. Out-of-the-box dictionaries contain a limited set of entries and must be extended for customer formats as needed.

note

The pss_de_analytics.csv file contains data enrichment call analytics for OpenCorporates and Geocoder. It is not a tag dictionary.

Tag dictionaries are processed as follows:

1. The parser splits the message into tag-value pairs and looks up each tag in its dictionary.
2. The entityname column groups related tags into parties, and the type column identifies the meaning of each value. The description column is for documentation only.
3. For each hit, Tara sets tagType and populates screenedData from the hit tag and the related party attributes.
4. The resulting data is available to the ML model, rules, CLDS, and reports.

If neither the parser nor the dictionary can identify a tag, the tag is generally handled as FREETEXT. FUF messages can also use suffix inference, and ISO 20022 messages can use the parent element's type. Empty tagContent is invalid input because an empty value cannot have a hit.

Format dictionary files

The main dictionaries use UTF-8, comma-separated values, and one required header row with the following five columns:

msgtype,attrname,entityname,type,description
GDS,DBT_NAME,Debtor_DBT,Name,Counterparty Name
GDS,DBT_ADDR,Debtor_DBT,Address,Counterparty Address
GDS,DBT_CITY,Debtor_DBT,City,Counterparty City
GDS,DBT_CTRY,Debtor_DBT,Countrycode,Counterparty Country
GDS,DBT_ID,Debtor_DBT,Code,All ID related fields

Column	Requirement	Description
msgtype	Required column; filtering is optional.	Message type to which the row applies. See Define message type scope.
attrname	Required.	Tag name as it appears in the message; the lookup key.
entityname	Required in main dictionaries.	Party grouping key. Leave it empty in the suffix dictionary.
type	Required.	Attribute type that determines how the value contributes to screened data. See Assign attribute types.
description	Optional value.	Human-readable explanation; not used during parsing.

Use RFC 4180 quoting: enclose values that contain commas in double quotes, and double any embedded quotation marks. The suffix dictionary has its own format requirements.

The following lookup rules apply:

• Tag-name matching is case-insensitive; no other normalization is applied.
• Cell values are not trimmed, so stray spaces matter. For example, Address with a trailing space does not match Address. Remove leading and trailing spaces from every cell.
• Keep attrname unique within each file, including across message types. If a tag appears more than once, the first row wins and later rows are silently ignored.

Define message type scope

In the main dictionaries, set msgtype to one of the following supported message type names: SWF, GDS, ACH, FED, BBG, CAM, IAT, MEX, RSGLB, RSUSA, EGIFTS, CHIPS, or ISO_20022. Matching is exact and case-sensitive. When the message type matches, Tara uses the matching rows of the dictionary.

Note the following behavior:

• PAYMENT_TRANSFER means no filtering: every row in the file applies.
• Any unrecognized value also means no filtering. A message whose type is not one of the supported names falls back to PAYMENT_TRANSFER, so the whole file is in scope regardless of the msgtype column.

As a result, if a dictionary uses msgtype values that are not on the list, the column has no effect and every row applies to every message. This causes problems only when the same attrname appears under two message types with different entityname or type values. In that case, the first row in the file wins.

The suffix dictionary is an exception: it accepts ALL and matches message types case-insensitively after trimming.

Assign attribute types

An attribute type determines both the screened data that a value supplies and the hit's tagType; these values are not always the same. Dictionary type values are case-insensitive. The dictionaries support the following attribute types:

Dictionary type	Screened data contribution	Hit tagType
Name	Name.	NAME
Individual, Company, Vessel	Name and entity type: person, organization, or vessel.	NAME
NameAddress	Name and address.	NAMEADDRESS
Address	Address.	ADDRESS
City, Citycode	City.	ADDRESS
State	State.	ADDRESS
Zip, Postalcode	Postal code.	ADDRESS
Country, Countrycode	Country.	COUNTRY
ID, Code	Identifier or code map.	ID
DOB	Date of birth. Values from multiple DOB tags are combined as pipe-separated values.	FREETEXT, NONENTITY
Amount, Currency, Number, Date	None; these values are deliberately not entities.	FREETEXT, NONENTITY
Freetext	No structured field from the value itself; retains party membership.	FREETEXT

caution

Unrecognized types are silently converted to Freetext when loaded. The original type text is discarded, with no error or warning. A typo such as Adress or Contry produces a tag that contributes nothing to screening. To detect these mistakes, check the spelling in the CSV rather than relying on logs.

Keep intentional Freetext rows. They retain the tag's party membership, so a free-text hit can inherit the party's city and country. In the FUF dictionary, an explicit Freetext row also prevents suffix inference from assigning another type. Removing the rows can lose that location context. A Freetext attribute does not overwrite the tag type assigned by a sibling tag.

All tag types are assigned while the message content is parsed. Amount, currency, number, date, and DOB tags report NONENTITY as both the tag type and the screened entity type.

Resolve tag type without message content

If a request contains no message content, Tara still looks up the hit's tag name in the tag dictionaries, so the hit gets a tag type and screened data. ID and code tags populate the screened data ID.

If the tag content fully matches one of the sanctioned names, Tara sets the screened name to the tag content and the screened type to the sanctioned type. These values are merged into the existing screened data, so a supplied ID, code map, address, country, DOB, and type are preserved.

If built-in parsers cannot extract the relevant screened data, Tara uses the Named Entity Recognition (NER) model in the NER Business Process step:

• For FREETEXT hits, the NER model labels tokens as IND, ORG, LOC, or OTHER and calculates a predicted name using the hit text or sanctioned name.
• For NAME hits, the model treats the tag content as an entity name.
• For NAMEADDRESS or ADDRESS hits, the model finds and parses an address to determine a country.

Dictionary-derived data and later NER results are separate processing stages.

Group tags into parties

Rows with the same entityname form one party, so a hit on one tag can use the values of other tags in the same group.

For example, consider the following FUF content:

[DBT_NAME     ] ACME TRADING LTD
[DBT_ADDR     ] 10 HIGH STREET
[DBT_CITY     ] LONDON
[DBT_CTRY     ] GB
[DBT_CTD      ] CONTACT MRS SMITH
[CDT_NAME     ] GLOBEX SA

Define the debtor and creditor in separate groups:

msgtype,attrname,entityname,type,description
GDS,DBT_NAME,Debtor_DBT,Name,Counterparty Name
GDS,DBT_ADDR,Debtor_DBT,Address,Counterparty Address
GDS,DBT_CITY,Debtor_DBT,City,Counterparty City
GDS,DBT_CTRY,Debtor_DBT,Countrycode,Counterparty Country
GDS,DBT_CTD,Debtor_DBT,Freetext,Contact Details
GDS,CDT_NAME,Creditor_CDT,Name,Counterparty Name

The parser creates two parties: Debtor_DBT with the five DBT_ tags, and Creditor_CDT with CDT_NAME. A hit on DBT_NAME uses the address, city, and country from other rows in the Debtor_DBT group and produces the following data:

tagType              NAME
screenedData.name    ACME TRADING LTD
screenedData.address 10 HIGH STREET
screenedData.city    LONDON
screenedData.country GB
screenedData.type    NAME

A hit on DBT_CTD has tagType set to FREETEXT and inherits screenedData.city = LONDON and screenedData.country = GB. At this parsing stage, the free-text value does not supply a screened name. Removing its dictionary row loses its explicit debtor grouping and the associated location context.

The screened name comes from the tag that was hit, and the address, city, and country come from the other tags in the same party. This makes entityname the most important column for screening quality: a hit is screened together with everything else in its party, so the adjudicator sees the whole party rather than one isolated field. If a party has several name or location tags, a sibling tag cannot supply the name, city, state, or postal code. FUF parties are grouped by both entity name and message type, so rows describing different message formats are not combined into one party.

When grouping tags, follow these guidelines:

• Keep different parties in different groups. Sharing a group can cause a hit on one party to use another party's country.
• Keep the related attributes of one party together. Splitting them across groups can leave a name hit without its address or country.
• Use the naming convention Party_Label_PREFIX, with underscores instead of spaces. As a rule of thumb, use one tag prefix per entity group, such as Assignor_Agent_XARG, Assignor_Agent_YARG, and Creditor_CDT.
• Within an entity group, keep attribute types unique to avoid collisions during parsing and adjudication.

Institution and branch fields describe different locations and need separate explicit groups, even when they have the same role. For example:

Tags	Entity group	Location
XARG_NAME, XARG_ADDR, XARG_CITY	Assignor_Agent_XARG	Institution (FinInstnId in ISO 20022)
XARG_NAM1, XARG_ADR1, XARG_CIT1	Assignor_Agent_XARG1	Branch (BrnchId in ISO 20022)

The branch's 1 appears in the field part of the tag, as in _ID1, _NAM1, or _ADR1. Separate groups prevent a branch hit from using the head office's location. These explicit mappings are distinct from the fallback rules for numbered FUF tags.

Parse FUF tags by suffix

FUF messages can contain tags whose purpose is indicated by the tag name but that are not defined in pss_fuf_tags_list.csv, such as PAR_NAME, PAR_ADDR, PAR_CITY, PPRM_NAME, LEGL_ENTNM, BEN_NAME, and ORGR_ADDR. By default, an undefined tag is handled as an independent FREETEXT entity, so related tags are not grouped and the corresponding screenedData fields remain empty.

For undefined FUF tags, Tara can use pss_suffix_tags_list.csv to do the following:

• Infer the tag type from a recognized suffix. For example, _NAME maps to Name, and _ADDR maps to Address.
• Infer the entity group from the tag prefix. For example, PAR_NAME and PAR_ADDR share the PAR prefix and are grouped into one entity.

This allows Tara to populate related screenedData fields and provide more complete data for name matching, address matching, geocoder enrichment, rules evaluation, reporting, and blacklisted country detection.

Suffix-based parsing applies only to FUF messages. It does not affect SWIFT, ISO 20022, or SWIFT ADK parsing. It also does not override entries in the static FUF tag dictionary or change the hit hash used by CLDS and decision reapplication.

Suffix dictionary

The pss_suffix_tags_list.csv file is stored with the other tag dictionaries at doc-upload/payment_sanctions_screening/{version}/tag-dictionary/. It uses the same columns as the main dictionaries:

msgtype	attrname	entityname	type	description
ALL	_ENTNM		Name	Entity name, for example, LEGL_ENTNM
ALL	_NAME		Name	Party name, for example, PAR_NAME or PPRM_NAME
ALL	_ADDR		Address	Address line, for example, PAR_ADDR
ALL	_ADDRS		Address	Address line, for example, OPR_ADDRS1
ALL	_CITY		City	City, for example, PAR_CITY
ALL	_ST		State	State or province, for example, PAR_ST
ALL	_ZIP		Zip	Postal code, for example, PAR_ZIP
ALL	_DOB		DOB	Date of birth, for example, PAR_DOB
ALL	_CTRY		Country	Country, for example, PAR_CTRY
ALL	_CUNRY		Country	Country, for example, OPNR_CUNRY

The following rules apply to the suffix dictionary:

• Use CRLF line endings and unquoted values. Do not include commas in description, because values cannot be quoted.
• Set msgtype to ALL to apply a suffix to every FUF message type. To restrict a suffix to one message type, specify that type, for example, GDS. Suffix message type matching is case-insensitive after trimming.
• Start each attrname value with an underscore (_). This prevents a suffix from matching in the middle of a tag name.
• Leave entityname empty. Tara derives the entity group from the tag prefix.
• Set type to a valid attribute type, such as Name, Address, City, State, Zip, DOB, or Country. An unknown value is handled as FREETEXT.
• If more than one suffix matches, Tara uses the longest suffix. For example, _ENTNM takes precedence over a shorter _NM suffix, and _ADDRS takes precedence over _ADDR.
• If the suffix dictionary is absent or empty, suffix-based parsing is disabled.

To add a suffix, see Add suffix pattern.

Tag inference and grouping

Suffix-based parsing applies only to tags that are not already defined in pss_fuf_tags_list.csv. For each undefined tag, Tara performs the following steps:

1. Removes trailing digits from the tag name and retains them as an index.
2. Matches the longest configured suffix and assigns its type.
3. Uses the remaining part of the tag name as the entity prefix.

For example, Tara processes PAR_ADDR2 as follows:

Tag:       PAR_ADDR2
Base tag:  PAR_ADDR
Index:     2
Suffix:    _ADDR
Type:      Address
Prefix:    PAR

If Tara cannot infer a tag because the tag has no underscore separator, has an unknown suffix, or has an empty prefix, the tag remains FREETEXT.

Inferred tags with the same prefix are grouped into one entity, subject to the numbered-tag rules. Their inferred types determine which screenedData fields are populated. For example:

[PAR_NAME  EXAMPLE PARTY]
[PAR_ADDR  100 EXAMPLE STREET]
[PAR_CITY  EXAMPLE CITY]
[PAR_ST    EX]
[PAR_ZIP   00000]
[PAR_DOB   1970-01-01]

A hit on PAR_NAME produces the following parsed values:

Field	Value
tagType	NAME
screenedData.name	EXAMPLE PARTY
screenedData.address	100 EXAMPLE STREET
screenedData.city	EXAMPLE CITY
screenedData.state	EX
screenedData.postal	00000
screenedData.dob	1970-01-01

info

An entry in the static FUF tag dictionary always takes precedence over suffix inference. For example, if PAR_NAME is added to pss_fuf_tags_list.csv, Tara uses that entry instead of the _NAME suffix. This also applies to explicit Freetext entries: they preserve the configured party grouping and block suffix inference.

Numbered tags

Trailing numbers can represent either party identifiers or line numbers. Tara treats the numbers as party identifiers only when a prefix has more than one numbered _NAME tag.

For example, the following tags represent two parties:

[PAR_NAME1  EXAMPLE PARTY ONE]
[PAR_ADDR1  100 EXAMPLE STREET]
[PAR_CITY1  EXAMPLE CITY ONE]
[PAR_NAME2  EXAMPLE PARTY TWO]
[PAR_ADDR2  200 EXAMPLE ROAD]
[PAR_CITY2  EXAMPLE CITY TWO]

PAR_NAME1, PAR_ADDR1, and PAR_CITY1 are grouped as PAR#1, while the tags ending in 2 are grouped as PAR#2. A hit on PAR_NAME1 includes only the values from PAR#1.

If there is only one unnumbered name tag, trailing numbers on address tags are treated as line numbers. In the following example, all address lines belong to the same entity:

[CP_NAME   EXAMPLE COMPANY]
[CP_ADDR1  100 EXAMPLE ROAD]
[CP_ADDR2  SUITE 400]
[CP_ADDR3  BUILDING C]
[CP_CITY   EXAMPLE CITY]

A hit on CP_NAME produces one entity, and the numbered address lines are combined into a single screened address:

Field	Value
screenedData.name	EXAMPLE COMPANY
screenedData.address	100 EXAMPLE ROAD SUITE 400 BUILDING C
screenedData.city	EXAMPLE CITY

Common tag patterns

The following FUF tag patterns are commonly typed and grouped by suffix-based parsing when they are absent from the static dictionary:

Tags	Prefix group	Typical use
PAR_NAME, PAR_ADDR, PAR_CITY, PAR_ST, PAR_ZIP, PAR_DOB	PAR#	Party
PPRM_NAME, PPRM_ADDR, PPRM_CITY, PPRM_ST, PPRM_ZIP	PPRM#	Primary parameter
BEN_NAME, BEN_ADDR	BEN#	Beneficiary
ORGR_NAME, ORGR_ADDR	ORGR#	Originator
TRST_NAME	TRST#	Trust
LEGL_ENTNM	LEGL#	Legal entity

Limitations

Suffix-based parsing has the following limitations:

• Tags such as [PAR_NAME 01] and [PAR_NAME 02] cannot be separated by party because the FUF parser groups them under the base name PAR_NAME.
• If the message contains PAR_NAME1, PAR_NAME2, and PAR_ADDR1 through PAR_ADDR3, PAR#3 is an address-only group. Tara does not merge it with another party, which prevents data from different parties from being combined.
• If hit.tagName is truncated, for example, PAR_NAM instead of PAR_NAME, Tara cannot match the tag to the inferred entity.

Update tag dictionaries

Update tag dictionaries to onboard a customer message format, add party attributes, or correct missing or incorrectly grouped screened data. For the file structure, lookup rules, message type scope, and supported types, see the sections above.

Edit and deploy dictionary

1. In S3, select the existing dictionary for the message format from doc-upload/payment_sanctions_screening/{version}/tag-dictionary/. Use the version directory for the installed bundle.
2. Edit the CSV, retaining its filename and five-column header. Use the main dictionary for explicit party or type mappings. For consistently named families of otherwise undefined FUF tags, use the suffix dictionary.
3. Complete the validation checklist.
4. Replace the corresponding file in the versioned S3 directory. If dictionaries are delivered through your bundle deployment, ensure that the deployment contains the edited file.
5. Restart the affected worker so that it reloads the dictionary. Workers cache dictionaries in memory by filename, so replacing the S3 object alone does not refresh a running worker's cached copy.
6. Process a representative message and inspect the hit's tagType and screenedData. Check a name hit, a free-text hit, and, where applicable, separate institution and branch hits. Confirm that each hit receives only its own party's location data.

Add new party

Add one row per tag, using a common entity name for the party:

msgtype,attrname,entityname,type,description
GDS,UDR_ID,Ultimate_Debtor_UDR,Code,All ID related fields
GDS,UDR_PTY,Ultimate_Debtor_UDR,NameAddress,Full Counterparty Information
GDS,UDR_NAME,Ultimate_Debtor_UDR,Name,Counterparty Name
GDS,UDR_ADDR,Ultimate_Debtor_UDR,Address,Counterparty Address
GDS,UDR_CITY,Ultimate_Debtor_UDR,City,Counterparty City
GDS,UDR_CTRY,Ultimate_Debtor_UDR,Countrycode,Counterparty Country

If the party has branch fields, append them with a separate entity name:

GDS,UDR_NAM1,Ultimate_Debtor_UDR1,Name,Branch Related-Counterparty Name
GDS,UDR_ADR1,Ultimate_Debtor_UDR1,Address,Branch Related-Counterparty Address

Add suffix pattern

To add a new FUF tag name pattern, do the following:

1. Add a row to pss_suffix_tags_list.csv with the suffix, type, and message type scope, following the suffix dictionary rules.
2. Deploy the updated tag-dictionary folder to S3 and restart the affected worker to reload its cached dictionary. See Edit and deploy dictionary.

No code changes are required to add a suffix.

Validate dictionary changes

Before deploying the edited file, check the following:

• Use UTF-8, comma-separated values, one header row, and the documented quoting requirements for the selected dictionary.
• Use only supported attribute types. Unknown types silently become Freetext.
• Check cell values for typos, and remove leading and trailing spaces from every cell. Values are not trimmed.
• Keep attrname unique throughout the file, ignoring case. Later duplicates are silently ignored, even if intended for another message type.
• Use one tag prefix per entity group as a rule of thumb, and keep the attributes of each party together.
• Give institution and branch fields separate entity names.
• Use underscores rather than spaces in entity names, following the Party_Label_PREFIX convention.
• Keep attribute types unique within each entity group to prevent conflicting values.
• Use only supported message type names in msgtype, with exact case. Any other value turns filtering off for the file. The suffix dictionary also supports ALL.
• Preserve intentional Freetext mappings that keep location context or prevent suffix inference.

Troubleshoot dictionary changes

A missing, empty, or unreadable main dictionary, or an unavailable S3 service, is not fatal. The worker logs Tag dictionary '<name>' is empty. Parsing will use FREETEXT types. and retries on the next call. Until loading succeeds, dictionary-based parsing falls back to free text. An absent or empty suffix dictionary disables suffix inference.

Symptom	Check and corrective action
A hit has no screened name, address, or country.	Check for a missing tag mapping, a misspelled type that became Freetext, or leading or trailing spaces in a cell. Confirm that the relevant attributes are in the same party group.
A hit has the wrong country.	Check whether different parties share one entityname, and separate their groups.
A branch hit uses the head office address.	Give the branch fields their own entityname.
Rows intended for one message type apply to all messages.	Check that msgtype uses one of the supported message type names with exact case. If the value is not recognized, filtering is turned off and every row applies.
An edit has no effect.	Check the S3 version directory and the deployed file, confirm that the bundle was redeployed if your deployment process requires it, and restart workers holding cached copies.
Every tag becomes free text.	Check for an empty or unreadable dictionary and the worker's is empty warning. Restore a readable file and verify that loading succeeds.