05. Canonicalization

Adding Canonicalization Rules

Owin.Scim allows the developer to specify canonicalization rules (delegates) as rules for resource type attributes. These rules will be processed automatically, normalizing (mutating), the request data before it's sent to validation and repositories for persistence. Some rules are built-in by default.

builder
  .For(u => u.Emails)
      .AddCanonicalizationRule(email => 
          email.Canonicalize(
              e => e.Value, 
              e => e.Display, 
              value =>
          {
              // canonicalize email.Value (user@MyDomain.cOm) into email.Display (user@mydomain.com)
              var atIndex = value.IndexOf('@') + 1;
              if (atIndex == 0) return null; // IndexOf returned -1, invalid email
                              
              return value.Substring(0, atIndex) + value.Substring(atIndex).ToLower();
          }))
      .AddCanonicalizationRule((Email attribute, ref object state) => Canonicalization.EnforceSinglePrimaryAttribute(attribute, ref state))

This example illustrates canonicalization rules on the multi-valued attribute, emails. Here, we are taking the email.Value attribute and canonicalizing it to the email.Display attribute. Since this rule requires access to multiple email attributes, we add this rule to the Emails attribute of User. Note that the email.Value is not being mutated here, just the email.Display. Next, we will look at canonicalization rules for scalar attributes.

By default, all core resource types with multi-valued attributes have a canonicalization rule to EnforceSinglePrimaryAttribute. This complies with the specification's rules.

Scalar Attributes

It may be you're only canonicalizing a single scalar-valued attribute or do not need to reference its parent object's other attributes. (e.g. value and display). In that case, just apply the canonicalization rule:

For(role => role.Value)
  .AddCanonicalizationRule(value => value.ToLower()))

You do not need to check for null (reference-type) or default (value-type) values being passed in. Owin.Scim will not invoke your canonicalization rule function if either is default.