Both formats ultimately require a Map<String,Object> be constructed and passed into the the underlying class, TranscodingRule.
A parent bean called shibboleth.TranscodingRule to support direct use of the class, but in most cases (*) it's easier to use the shibboleth.TranscodingProperties parent bean, which allows the rule to be defined using the Spring
(*) The main reason you might need the direct class is to use non-String values of properties, which is not a general need; the system converts things from String internally to simplify things.
The conf/attributes/default-rules.xml file includes a number of examples of this syntax being used.
The other useful bean, also used in that file, is shibboleth.TranscodingRuleLoader, and the value of that bean with this syntax is that it allows multiple rules to be collected together in a list without each individual rule having to be given a Spring bean ID, which is just more work and hassle to assign while avoiding duplication.
The previous example for "mail" when defined in this syntax would be:
Spring XML version of "mail" rule
The only functional difference is that this rule includes via merge a couple of additional default properties that are included in the IdP's system files.localtab-live
The alternative syntax for defining a single rule is just to use a Java Properties file (only the non-XML flat-file syntax is supported, because, obviously...)
An example of this was shown earlier. A key point: the name of the file is irrelevant. It doesn't make assumptions about the attribute ID based on the name or allow that property to be omitted. In practice of course it's sensible to name things appropriately for ease of maintenance.
The use of Properties files is also handled by the shibboleth.TranscodingRuleLoader bean, which supports vacuuming up a directory tree of Properties file all at once.
This is illustrated for you in the conf/attribute-registry.xml file, and by default the conf/attributes/custom/ directory is already designated as a place for these files to be created. You can create any subfolders you want for organization because it will walk the whole tree.
You can of course create other loader beans that load different directories if desired.
There are a small set of generic properties, some required and some optional. The "Type" refers to the underlying object that the system expects to be able to produce as a value of the property, but String is almost always a supported format to use for convenience.
The IdPAttribute id/name that is used internally. This dictates when the rule will be applied to attributes within the IdP for outbound encoding, as well as what to call an attribute created during inbound decoding.
Space-delimited list of Bean IDs, or an AttributeTranscoder
This defines which AttributeTranscoder objects should be used to encoder and decode data when the rule runs, and dictates most of the rest of the properties that will be required or supported.
In most cases this is expressed by specifying one or more Spring bean IDs in a list; the implementation will turn those into the right objects if they exist.
Standard across the system, this is a condition to evaluate at runtime to control whether to apply the rule
Defaults to true, can be set false to limit use of the rule to decoding only
Defaults to true, can be set false to limit use of the rule to encoding only
Collection<String> or a space-delimited list of Strings
Shortcut for applying an activation condition that matches a set of relying party names against the request
Language-specific values to use as display names for the IdPAttribute
Language-specific values to use as descriptions for the IdPAttribute
The latter two are optionally language-aware; if the raw property name is used, then the corresponding value is used any time the default Locale is in effect for a request. Otherwise a dot separator must be followed by a language code, which may also include country code.
Also discussed above, there are several beans defined to support the creation of the mapping rules contained in the registry.
Parent bean for defining transcoding rules using a Java Properties object
Parent bean for low-level Spring-based creation of transcoding rules; shibboleth.TranscodingProperties is generally used instead
Parent bean for defining collections of rules either as a collection of maps or by loading property files from a directory
Built-in collection of transcoders usable in rules