[DFDL-WG] Action Item: Versioning mechanism for DFDL v2.0 features/changes

[Mike Beckerle]

There are some features now under discussion which will most likely not be
part of the DFDL v1.0 standard, but a subsequent version 2.0 of the
standard.

Implementations may have these features prior to the existence of that
draft version of the DFDL standard; hence, a mechanism for indicating the
support, and requirements that implies, on DFDL schemas is needed in order
for these v2.0 features to be introduced.

The purpose of the versioning mechanism is to provide access to DFDL v2.0
features, while maintaining also backward compatibility with DFDL v1.0
schemas.

For example, new DFDL format properties may be added to the DFDL v2.0
version; however, those properties are not required to be specified unless
the version of the schema is specifically set to indicate it is using
version 2.0 features. Also, deprecated features should only generate
deprecation warnings if the user is requesting version 2.0 of DFDL, and
should be silent otherwise.

Proposal:

New attribute on the dfdl:format annotation: DFDLVersion with valid values
"1", "2". All values are reserved for future use.

The DFDLVersion, if unspecified, defaults to "1" which means the
implementation is of the DFDL v1.0 specification.

If the DFDLVersion is "2", then new requirements for version 2.0 of DFDL
may be enforced on the schema, and schema definition errors will result if
version 2.0 requirements are not met. DFDL Version 1.0 features that are
deprecated will generate warnings.

Example:

<dfdl:format DFDLVersion="2" .../>

Example:

<dfdl:defineFormat name="myV2Format">
  <dfdl:format DFDLVersion="2" .../>
</dfdl:defineFormat>

The DFDLVersion is not a format property and is not scoped. It can be added
to a named format definition which is then referenced in the usual manner
for named format definitions.

Backward Compatibility Requirement

DFDL Implementations that provide version 2.0 functionality must also
provide DFDL v1.0 compatibility. That is, version 2.0 subsumes and extends
version 1.0.

Mixed Version Schemas

If a schema consists of multiple schema documents, and their respective
dfdl:format annotations do not all contain the same value for the
DFDLVersion attribute, then the schema is said to be "mixed version". This
is allowed.

A named dfdl:format carrying DFDLVersion "2" may not be referenced from a
DFDL Schema document having DFDLVersion "1".

The opposite is allowed: A named dfdl:format carrying DFDLVersion="1" or
lacking the DFDLVersion attribute may be referenced from a DFDL Schema
having DFDLVersion="2".

There are really 3 ways that DFDL version 2.0 can differ from version 1.0,
and these are that new features are added, old features are deprecated, or
old features are removed. This latter is quite undesirable, but will be
considered a possibility for purpose of discussion this versioning system.

These will commonly be in combination such as if an old feature is
deprecated with the replacement feature being added.

These will now be discussed separately, with the emphasis on how mixed
version schemas must work.

New Features Added

Each new required DFDL property introduced for version 2.0 will be defined
along with what is called its "version 1.0 default value". When a mixed
version schema exists, the DFDL v1.0 parts of it behave as if any required
DFDLVersion 2 properties have their version 1.0 default value defined, at
top level of the schema (as if defined with that default value in each
DFDLVersion 1 schema document's dfdl:format annotation).

Features Removed

Incompatibilities are to be avoided wherever possible, and may not be
needed at all. However, there is still the possibility that some feature
will want to be entirely removed and replaced by something better, and in
that case the versioning scheme needs to be able to support this.

In that situation, the schema definition error for version 2 is only
generated when a schema has DFDLVersion 2 specified (in dfdl:format
explicitly, or by reference to a named format carrying or referencing
DFDLVersion 2). Mixed schemas that contain schema documents entirely using
version 1 of DFDL do not generate this schema definition error.

Features deprecated

Deprecation warnings are generated only when a DFDLVersion="2" attribute is
present or is incorporated by reference (to a named format). A version 1
schema that is incorporated with a version 2 DFDL schema but is not
modified in any way, does not generate deprecation warnings about version
1.0 features that have been deprecated in version 2.0.

(Most likely deprecations would be revising property names or value enums
for clarity.)

Implementations may provide mechanisms for suppressing warnings. These are
implementation dependent.

Version 1.0 Existing Deprecations and Compatibility

During the process of standardization for DFDL v1.0 a number of properties
names were changed. DFDL version 1.0 implementations accept both the old
and new property names.
(Example: dfdl:separatorSuppressionPolicy, which replaced an older property
name.) DFDL schemas that specify DFDLVersion="2" will not accept the older
property names, and it is a schema definition error if the old (pre DFDL
v1.0) property names are used.

Properly constructed mixed version schemas can still depend on the older
property names in the version 1.0 parts of the schema.

------------------------------


Mike Beckerle | OGF DFDL Workgroup Co-Chair | Tresys Technology |
www.tresys.com
Please note: Contributions to the DFDL Workgroup's email discussions are
subject to the OGF Intellectual Property Policy
<http://www.ogf.org/About/abt_policies.php>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.ogf.org/pipermail/dfdl-wg/attachments/20180123/f3a0d3a7/attachment.html>