XSD Schema
Last modified 17 Aug 2023 20:44 +02: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

Was this page helpful?
YES NO
Thanks for your feedback