Files with the .xsp-config extension are used to describe the controls that are available in the IBM Lotus Domino Designer tool. The information in the files is used in Designer to provide tooling support when editing the XPages XML files. For example, the xsp-config files list all the Controls that are present in the Controls palette, and if you select a control and view the Properties panel, the All Properties tab is populated by the lists of properties declared in the xsp-config files. The information in the xsp-config files is also used to build the .class file generated from each XPage XML file, so it needs to be accurate to prevent compile errors at design-time and to prevent ClassCastExceptions or other type related errors at runtime.
The xsp-config format is based on JSF's existing faces-config format, but the xsp-config files are only loaded at design-time in the Domino Designer tool and builders, rather than at runtime when the XPages are executing.

In this document most examples are from xsp-config files. The samples from the XPage source tab are marked with (XPage snippet).

The table of contents above describes the contents of this page, but there are 5 separate pages in this document.

1. Overview and top-level elements
2. Page 2, components, defining controls
3. Page 3, property level elements, allowing properties
4. Page 4, complex-types, non-control objects like converters and data sources
5. Page 5, other definitions.

1. Top Level Elements.
   The 2 higher level elements contain the definition elements.
   • faces-config
   • render-kit
2. Definition Elements.
   These define tags, abstract tag superclasses, or other named reference-able definitions. These are elements which contain other elements. Includes the -extension elements which allow any contents.
   • complex-type
   • component
   • composite-component
   • converter
   • group
   • property-type
   • renderer
   • validator
3. Property Level Elements.
   Multiple property level elements can be defined within the definition level elements. Different definitions allow different types of property level elements, or are more commonly used with certain types of property level elements.
   • attribute
   • facet
   • property
4. Lower Level Elements.
   Lower level elements generally only contain text. These are used within the other level elements.
   
5. designer-extension elements and their contents.
   Design-time only extensions used within the definition elements and property level elements.
   

• complex-type,
• composite-component,
• group,
• faces-config-extension

The new file format takes the place of a JSP Tag Library, in that it defines XML tag tag-names and the namespace-uri to which they are contributed.
It differs from Tag Libraries in that properties can be referenced from an existing group definition, or inherited from a parent component or complex-type. (See base-component-type and base-complex-id.)

It also provides other information that will be used when loading a page from a file. For example, the property-extension gives more information on the expected value of a property, so that pages can be validated by the design-time builder.

Present in faces-config.

For example:

<faces-config-extension>

<namespace-uri>http://www.ibm.com/xsp/custom</namespace-uri>

<default-prefix>xc</default-prefix>

</faces-config-extension>

The faces-config-extension used to also contain an element "public" (<public>false</public>). You will see that in Custom Control xsp-config files from 8.5 and 8.5.1, but it is not useful in the Notes/Domino environment, and should not be added to your files. [It was left over from the Lotus Component Designer technology.]

A suggested xmlns prefix to act as a synonym for the namespace-uri .
For example, the "xp" here (XPage snippet):

<xp:view xmlns:xp="http://www.ibm.com/xsp/core">

<xp:text value="#{requestScope.result}" />

</xp:view>

 <default-prefix>xc</default-prefix>

The namespace-uri corresponds to the xmlns namespace declarations at the top of every XPage, like so (XPage snippet).

<?xml version="1.0" encoding="UTF-8"?> 

<xp:view xmlns:xp="http://www.ibm.com/xsp/core"

xmlns:eg="http://example.com/">

<eg:mycomponent/>

</xp:view>

XPage pages that use the controls and complex-types defined in a configuration file will need to reference the namespace defined in that file, so that the tags are resolved.

The XML format, which the XPage source is based on, suggests that tags can be namespaced by a uri, so that each person or company that provides tags can declare any URI to uniquely identifying that company, and so long as the URIs do not conflict, it allows tags with the same name but from different companies to be used in the same XML page.

In XPages, any tags that do not have a namespace, or are from a namespace that is not declared in a loaded XPage configuration file, will be treated as HTML, and passed through to the output HTML page. So the configuration files must have a namespace.

There is no "hard" compiler requirement that people use different namespaces, but it is advised to do so for a number of reasons. It provides disambiguation between identical tag-names from different sources. It means you don't accidentally override the XPages core tag names, which would lead to unexpected behaviors in applications using those tags. Some parts of the Designer tooling may expect control libraries to have different namespaces, leading to odd behaviors if they are the same.

The exception to the rule for uniqueness is the custom control namespace, which is the same in every custom control created by the Designer editor:
xmlns:xc="http://www.ibm.com/xsp/custom"
Since custom controls design element names are unique within the application where they are defined, that does not generally cause a problem. However if you are exporting a custom control, to share with other developers, it is best to change the namespace-uri of that custom control to prevent conflicting with the names of custom controls defined in applications. You can rename the custom control namespace in the Properties view of the Custom Control editor.

The namespace-uri is generally URL-like, but it is not resolved as a URL and there is no requirement that it should resolve. (People have been known to publish information about their tags at the namespace URL, at their own discretion.)

The namespace-uri must be known for each xsp-config file. It is usually defined with the optional default-prefix.
It is normally present in the faces-config-extension. Otherwise the namespace-uri can be present in component-extensions. In that case the first definition in the xsp-config file should declare the namespace-uri (or they should all have the same namespace-uri), and any initial definitions without a namespace-uri will be ignored.

 <namespace-uri>http://www.ibm.com/xsp/custom</namespace-uri>