...
Going forward we expect to make broader use of Spring's native configuration format, and less of custom files, but backward compatibility (and in some services, user sanity) demands that we continue to support the older formats. While native Spring syntax can be more complex in some ways, it's also more consistent, better documented, and allows for a lot of syntactic tricks that make advanced features much easier to take advantage of.
...
The Spring Web Flow mechanism is used to execute ProfileActions, which make up the bulk of the IdP's processing model.
Custom Schemas
Where custom schemas are used, there is a lot of complex machinery involved that isn't readily apparent. Even once you understand how the Spring bean parsing logic works, it's not always as simple as just adding to the custom schema files. In particular there are subtle issues that arise if you incorporate outside schemas by reference, including SAML or XML Signature/Encryption elements. We don't control the Spring XML parsing layer sufficiently to control the entity resolution process, such as when external schemas are referenced. We do validate the XML through Spring however, so this is a major point of concern.
Spring will, unfortunately and brokenly, rely on the schemaLocation hint int the root element to map XML namespaces to schema locations. Furthermore, the code will end up dereferencing external URLs if it's left to its own devices. The only way to prevent that is by adding mappings between the URLs that appear in the hint to an alternate (i.e., local, via the classpath) reference to the schema file included in the software stack. This is managed in idp-schema/src/main/resources/META-INF/spring.schemas
Even so, the actual location hints are in the user-editable files themselves, so all we can do is document and ship appropriate content to use.
Contexts
The state of an executing Web Flow is managed in the IdP using a concept called the "context tree", a graph of objects each descended from a common class. Each context can have a parent, and maintains a class-indexed hashtable of children, limiting a tree to contain a single instance of a context type at a given level. Each context is typically of a derived type that particularizes it to store information specific to a single category of information. A context tree tends to be shallow, and is designed to support type-safe access to conversational state by ProfileActions.
...