Matching Rules

Last modified 14 Mar 2024 12:46 +01:00
Table of Contents

Matching rules are short expressions that can normalize and match attribute values. Attributes values are normally compared literally, e.g. strings are compared as they come from the resource in a case-sensitive manner. But this is not appropriate for all resources. Some resources use case-insensitive attributes, attributes that can have several equivalent representations (such as URL or LDAP DN) and so on. While this is usually not a problem for ordinary attributes it can be problematic when dealing with identifiers. Failure to detect that two strings match can cause problems during evaluation of identifier uniqueness and identifier allocation. This may undermine significant part of the provisioning logic.

MidPoint allows to optionally specify a matching rule for resource attribute.

Matching rule specification
<resource>
    ...
    <schemaHandling>
    ...
        <objectType>
            ...
            <attribute>
                <ref>icfs:uid</ref>
                <matchingRule>mr:stringIgnoreCase</matchingRule>
            </attribute>
            ...
        </objectType>
    </schemaHandling>
</resource>

The matching rule will be used to match individual values of the attribute. E.g. in this case the values of ICF UID attribute will be matched in case-insensitive way.

Matching rules are identified by QName. The design of the matching rules implementation is extensible and it may be possible to add custom matching rules in the future. However currently the set of matching rules is built-in in midPoint product.

Query matching

Note that besides in attribute definitions, matching rules can also be used in queries. In midPoint Query Language, the matching rules are located right behind filter enclosed in square brackets.

locality =[origIgnoreCase] "Edinburgh"

For more information about matching rules in query see matching rules chapter in introduction to Midpoint Query Language.

In XML query, the matching rules are represented using the tag <matching>. An example for XML query:

Matching rule specification
<correlation>
   <q:equal>
	  <q:matching>polyStringNorm</q:matching>
      <q:path>name</q:path>
      <expression>
         <c:path>$account/c:attributes/icfs:uid</c:path>
      </expression>
   </q:equal>
</correlation>

There are some differences, though. Some matching rules are universally applicable - in attribute definitions as well as in repository queries. Others are usable only in the definitions (like distinguishedName), because there are no suitable normalization algorithms that could be used directly in SQL queries. Yet other ones exist only for the purpose of querying the repository (like the last three in the table below).

Known matching rules

Existing matching rules are summarized in the following table.

All of them have a namespace of http://prism.evolveum.com/xml/ns/public/matching-rule-3.

Name Applicable to Usable in attribute definition Usable in repository query Description

default

all types

yes

yes

Default matching rule compares the values in the default way appropriate for the data type. E.g. strings are compared in a case-sensitive way.

stringIgnoreCase

String

yes

yes

Case-ignore matching (case-insensitive).

distinguishedName

String

yes

no

Matching rule for LDAP distinguished name (DN).

exchangeEmailAddresses

String

yes

no

A specific matching rule for Microsoft Exchange EmailAddresses attribute consisting of SMTP:/smtp: prefix and email address. It considers the case in the prefix but ignores the case in the email address.

uuid

String

yes

no

Matching rule for universally unique identifier (UUID). Currently, it is (almost) simple case ignore matching.

xml

String

yes

no

String matching rule that compares strings as XML snippets. The XML comparison is not schema aware. It will not handle QNames in values correctly. The comparison ignores XML formatting (whitespaces between elements).

polyStringStrict

PolyString

N/A (attributes are never PolyString)

yes

Strict PolyString matching. Both the original part and the normalized parts are compared.

polyStringOrig

PolyString

yes

Non-strict PolyString matching. Only the original part is compared.

polyStringNorm

PolyString

yes

Non-strict PolyString matching. Only the normalized part is compared.

strictIgnoreCase

PolyString

yes; in repo only

Case-insensitive version of polyStringStrict. I.e. both original and normalized parts are compared in a case-insensitive way.

origIgnoreCase

PolyString

yes; in repo only

Case-insensitive version of polyStringOrig. May not follow DB indexes.

normIgnoreCase

PolyString

yes; in repo only

Case-insensitive version of polyStringNorm. Note that because polyStringNorm is itself case-insensitive, normIgnoreCase is the same as polyStringNorm.

Applicable to describes to which data types this matching rule can be used. Usable in columns provide information about applicability of the rule.

Note: "yes; in repo only" means that this matching rule is quite special, and can be used really in repository queries. (Technically, there are no corresponding MatchingRule classes.)

Was this page helpful?
YES NO
Thanks for your feedback