XSD Schema

Last modified 26 Jan 2026 20:37 +01:00

Welcome to the comprehensive guide on effectively handling the life cycle of XSD (XML Schema Definition) elements. This document aims to provide you with a clear understanding of the steps involved in managing XSD elements for midPoint schemas throughout their entire life cycle.

Life cycle for XSD elements

Currently, there are multiple states life-cycle for elements in our XSD is following:

  1. Created in XSD

  2. Modified (optionally)

  3. Deprecated

  4. Removed

  5. Deleted from XSD

Creation

Designing XSD elements is a crucial aspect of ensuring the integrity and consistency of XML data. Each new XSD element and type should contain documentation and annotations.

All complex types should be marked with container annotation, unless there’s a documented reason why it’s not a good idea to create prism container from complex type.

Required annotations:

  • since

Optional annotations:

  • container

  • experimental

  • displayName

  • help

  • For more information see prism project: annotation-3.xsd

Annotation example for created element
<xsd:annotation>
    <xsd:documentation>
        <!-- todo documentation -->
    </xsd:documentation>
    <xsd:appinfo>
        <a:since>4.8</a:since>
    </xsd:appinfo>
</xsd:annotation>

Modification

Modification of element (complex type) structure is most often handled as three cases. First one is adding new sub elements, for which we can follow Creation chapter. Another case is removing sub elements, which should be handled using deprecation/removal scenario (see Deprecation).

Separate case is when underlying XSD elements, types or type names change, but change is only internal and NOT VISIBLE in final XML objects. If this is the case, then we don’t have necessarily to go through creation/deprecation/removal, we can only update midPoint codebase for new types.

Deprecation

When there’s decision to remove feature or configuration options from XSD schema, elements need to be marked deprecated. At this stage code behind such feature or configuration should still be in place and work correctly (unless otherwise specifically stated in documentation and release notes).

Required annotations:

  • deprecated

  • deprecatedSince

Optional annotations:

  • plannedRemoval

Example of deprecation
<xsd:annotation>
    <xsd:documentation>
        <!-- todo documentation -->

        DEPRECATED:
        <!-- short info about optional replacement feature for this deprecation -->
    </xsd:documentation>
    <xsd:appinfo>
        <a:since>4.6</a:since>
        <a:deprecated>true</a:deprecated>
        <a:deprecatedSince>4.7</a:deprecatedSince>
        <a:plannedRemoval>4.8</a:plannedRemoval>
    </xsd:appinfo>
</xsd:annotation>

Element removed

Element can be marked as removed only after all code related or dependent on it is removed from midPoint codebase.

Required annotations:

  • removed

  • removedSince

Example of removed element
<xsd:annotation>
    <xsd:documentation>
        <!-- todo documentation -->

        REMOVED:
        <!-- short info about optional replacement feature for this removal -->
    </xsd:documentation>
    <xsd:appinfo>
        <a:since>4.6</a:since>
        <a:deprecatedSince>4.7</a:deprecatedSince>
        <a:removed>true</a:deprecated>
        <a:removedSince>5.0</a:plannedRemoval>
    </xsd:appinfo>
</xsd:annotation>

Element deleted from XSD

XSD element can be deleted from XSD only in LTS that is after LTS in which element was already marked removed. Schema migration information must be added to schema.

Example of schema migration
<xsd:appinfo>
    <a:object/>
    <a:since>3.6</a:since>
    <a:schemaMigration>
        <a:element>tns:objectChange</a:element>
        <a:version>4.0</a:version>
        <a:operation>removed</a:operation>
    </a:schemaMigration>
</xsd:appinfo>

Upgrade notes

  1. If XSD element is marked deprecated (or removed) and there’s a strategy on how to upgrade existing XML objects:

    1. Such transformation must be implemented by extending com.evolveum.midpoint.schema.validator.UpgradeObjectProcessor class

    2. Cherrypicked to proper branches:

      1. Current LTS support

      2. Last feature support branch

Additional annotations details

The container annotation

The container annotation is used to mark a complex type as a Prism container, which can hold individual Prism items. It is important to allow core functionalities like deltas or querying.

Using container=true

When container is set to true, the complex type becomes a Prism container. Elements of a container are stored internally as a list of items, not directly as Java attributes, which makes them more dynamic. This has several benefits, including:

  • Great flexibility

  • Support for crucial functionalities like deltas

  • Fine-grained data manipulation and operations (e.g., queries, deltas, …​)

In most cases, this is the recommended approach.

Using container=false

When container is set to false (or omitted), the complex type becomes a traditional JAXB bean with a fixed structure. The elements are stored as traditional class attributes.

This has a few advantages:

  • Better performance

  • Internal lists are true lists, which preserve order

  • If they are inside a container, they are represented as a Prism property and thus updated as a whole (atomically)

However, it also has several disadvantages:

  • No support for deltas

  • No support for queries

  • Not extensible (by schema extensions)

One potential use case is at the boundaries, interfacing with other external services.

Table 1. Comparison table
container=true container=false (default if missing)

Implemented interface

Containerable

PlainStructured

Query support

Supported

Not supported

Delta support

Supported

Not supported

Data access

Via generated methods or as Prism items using paths

Only via generated getters/setters

Structure

Dynamic (elements are stored as a list of items)

Fixed (elements are stored as class attributes)

Extensibility

Supported (e.g., via schema extensions)

No schema extensions support

Recommendations

The best practice is to use the container annotation set to true for all types, unless you have a good reason not to. In such cases, set it to false (to make it explicit) and add a reason in a comment.

Was this page helpful?
YES NO
Thanks for your feedback