Schema Versioning Strategy and Policy

Objectives

• Enable the court to evolve the schema due to business or technical changes.
• Provide support for prior versions of schemas.
• Minimize the impact of schema changes to integration partners.
• Keep the number of supported schema versions down to a manageable number.
• Eliminate the need for integration partners to make unnecessary changes to their applications due to new schema versions.
• Give our partners as much time as possible to react to schema changes.
• Define a mechanism to gracefully phase in new schema versions and phase out old versions.

This strategy is intended to address these concerns:

• Partner may not be able to update their applications on the same schedule that the Court implements a schema change - we need a way to prevent schema changes from breaking client code
• As the number of schema versions increases, support becomes more difficult - the Court needs a way to keep the number of supported schema versions to a level that can be supported
• Partner application changes cannot be made on short notice - the Court needs to provide as much notice as possible before a schema version is inactivated, and support for prior versions for some period of time

Why are schema changes necessary? 

• As XML schema constructs are typed, any modification that would result in a type change is a potential incompatibility. For example, we might currently express a measurement or a count in integer values (xs:int), but in a future enhancement we might need a way to allow decimal fractions for the same value (xs:double). If your application is expecting a field to return an integer at runtime and we start returning a double instead, your application could fail. So, we need a way to avoid changing the type directly.
• Another example of a type change would be adding an element to an existing complex-type. If this new element is required and your client application does not include it, or expect it in a response that client application could fail. A similar problem would occur when removing an element.
• Changing the multiplicity of an element is also a potential incompatibility. For example, we might currently allow a single Name element, but in a future enhancement we might allow repeating Name elements (maxOccurs="unbounded"). As some toolkits interpret repeating fields as arrays, this would be equivalent to a type change.
• Note: We try to avoid making purely cosmetic changes to schemas that would break client code.

The Court's Integration Services are based on a set of schema that as a group we refer to as CourtXML. CourtXML is made up of 3 main types of schema.

• Simple Type Schemas: These schemas contain enumerated simple types that are used to define a list of valid values for a given element or attribute. These schema are never used on their own but are always imported into and used by another schema. Simple Type schemas can change over time as values are added, modified or removed. These changes do not result in versioning upgrades.
• Base Schema: The schema named CourtXML_#.xsd is referred to as our base schema. The # indicates the base schema version number. This schema contains type definitions that are used by other schema when defining messages. Like Simple Type schemas this schema is never used on its own but is always imported into and used by another schema.
• Message Schemas: Schemas that we refer to as Message Schemas define the content of messages that are either input to, or output from, one of our services. Message schemas are named with a suffix containing the base schema version that they are associated to along with the version of the message schema. For example the message schema CriminalComplaintDocument_3_2.xsd references the base CourtXML schema version 3 and is the 2nd version of the CriminalComplaintDocument schema that has been published. The top level element of every message defined within a message schema has an attribute named schemaVersion. This attribute will carry the version number of that message schema. For example messages defined within the message schema CriminalComplaintDocument_3_2.xsd will have "3:2" as their schemaVersion attribute value.

The version of a message schema that is used is driven by the consumer of a particular service. 

• For query and e-filing type services the version of the reply and response messages will always match the version of the request and submission message. If a request or submission is made using an inactivated version of a message schema a fault will be returned.
• For notification services the message version that is used is configured into the subscription. This will not change until the consumer makes a request to have it change.

When changes occur that would result in a type change the following steps are taken to prevent breaking existing client code.

• Any types contained in the base schema that require changes are copied and given a new name within that schema. Then the change is made to the type with the new name and an annotation is added to the old type indicated that it has been deprecated. For example a complex-type named ChargeType may need to have a new element added to it for some business reason. A new copy of the ChargeType complex-type would be added to the base schema with the name ChargeType2.
• If an element or type contained within a message schema requires a change, a new copy of that message schema will be created with its message version number incremented and the prior version will be deprecated.

The support status of message schemas will fall into 5 categories.

• Draft: These include schemas that are still being developed and being reviewed both internally and by partners.  These schemas are likely to change before implementation.
• Pre-Release: These include schemas that have not been published in production yet. Generally these will be available for testing in our development environment though they may be still considered in a draft state.
• Supported: These include schemas that are the current version, the prior version or any prior version that has been deprecated within one year. These schemas are fully supported. Full support includes the following:
  • When regression testing is done all supported schemas for a particular service are tested.
  • Issues that are identified with a service and a supported version of the schema receive the highest priority for troubleshooting and resolution.
  • Documentation for a particular service will always reflect the current version of its message schema.
• Unsupported: These include schemas that have been deprecated for more than a year and are not the prior version to a current schema. Unsupported means the following:
  • This message schema version is still available for use.
  • Any regression testing that is done will not include this version of the schema.
  • Issues that are identified with a service and an unsupported version of the schema will have a lower priority for troubleshooting and resolution, and depending on the problem may not be corrected. (The resolution may involve the partner migrating to the current version of the schema).
• Inactivated: These include versions of message schemas that can no longer be used. Message schemas will generally not be inactivated unless there is a particular reason to do so, such as a business change that makes them either not support the current business process, causes them to inaccurately represent their area of court information, or are no longer used by any consumers. We will attempt to provide a minimum of 6 months notice when a version of a message schema is about to become inactivated.

The following best practices are suggested for use of message schema versions:

• Use supported versions. As a part of your applications normal maintenance schedule attempt to keep it current with using only supported versions of message schemas. This provides the greatest likelihood that system changes will not negatively impact your application (because of regression testing) and assures that the support that you receive from the court will be at its highest level.
• When you have a need to change your application for some reason also migrate to the current version of any message schemas that are being used. If your application has fallen behind more than one version there is no need to migrate to the intermediate versions.
• For new development always use the current schema version.
• Monitor the Court Integration Services website, and Integration Services update notification emails for changes to the support status of message schemas. When a new version of a schema is published and an old version is deprecated, or when a version is slated to be inactivated, the change in status for that schema will be reflected on the CourtXML schema web page and will be announced in an Integration Services update email.
• Design your software to be able to handle, or gracefully ignore, new elements that we add to the schema. This will simplify migration to a new version.
• Make the schema version a configuration setting so if a new version does not change anything that is being used then migration to a new version only requires a configuration change.