• ODF_1.2_Version_Significance

ODF 1.2 Version Significance

Summary

Proposal owner:

Dennis E. Hamilton

Brief Description:

Provide a tightened definition of version-number significance in ODF documents that is backward compatible, precise, and anticipates further versions.

Rationale

Considerations

These considerations will be adjusted as the proposal is fleshed out:

• For ODF 1.2, An optional manifest:version is defined for the ODF 1.2 manifest:manifest element. In addition, every document root element has a mandatory office:version attribute and the value is prescribed to be "1.2" in this specification. -- orcmid 2008-12-10 00:17:54

• A background section is needed here in order to show what the current statements are about version for ODF 1.0/1.1 and for the existing draft 7 of ODF 1.2. -- orcmid 2008-12-10 00:21:48

• It is not clear whether the metadata.rdf file, when present, should have a document root metadata:version as well.
• Although office:version indicates the schema version that applies to the document root element, it does not mean that the scheme for a previous version of ODF is not satisfied. This make ofice:version a brittle indicator for whether or not a processor might be able to properly accept and even update (but now with its own version level) the document.

• There is no assurance that all of the document roots in a package are at the same version level. This extends, in particular, to embedded <office:document> elements as well as ODF packages and XML documents for ODF document root elements that are external to an ODF document and linked from it.

• The ODF 1.1 rule for [XML] document-root elements is that "All root elements take an office:version attribute, which indicates which version of this specification it [the root element] complies with." This does not require that every root element in the structure of an ODF document comply with the same version of "this specification." For ODF 1.1, office:version attributes are also optional. There is a side comment about whether a processor "may" validate a document for which the version number is not known to the processor (whatever that means). The additional assertion that the document (the XML document having the root element?) be well-formed, which is odd since the requirement is that all XML documents that are parts of ODF documents be well-formed.
• For ODF 1.2 as of draft7-10 (section 18.590), there is a dramatic change in wording. In addition, office:version is now a required attribute, but only "1.2" is defined as a permissible value in the schema (which makes sense in an odd way). The most-significant change in wording is that
  • "The office:version attribute specifies that a document conforms to a particular version of this specification.
  • "An application that stores a document conforming to this version of the specification shall use the attribute value 1.2." (This is currently assured by the 1.2 schema.)
• Note that this seems to imply that a office:version attribute on any root element establishes the version of the specification that the entire ODF document possessing that root element conforms to. It is not clear how the conformance for different values on different root elements of the same document structure. Also, there is no mention of conformance which is somewhat different, since conformance is a specific term of art with regard to the specification and is defined in its own section of the specification. Again, this is a brittle indication in tht an ODF document (and certainly an ODF root element) may well conform to an earlier specification while also conforming to 1.2.
• There are the following additional provisos that I think should be modified:

  • "If an application processes a document with an attribute value 1.0 it may assume that the document conforms to the OpenDocument v1.0 specification [ODF10].

  • "If an application processes a document with an attribute value 1.1 or no office:version attribute, it may assume that the document conforms to the OpenDocument v1.1 specification [ODF11]."

• I believe this normative wording is inappropriate (see the JTC1 definitions). This needs to be dealt with in the conformance section, and perhaps here, that a processor of documents that comply with 1.2 need not accept root elements that are defined to comply with other specifications, and what the recommended behavior is. We might even say should accept, but need not produce a document of a previous version. Here, it should be asserted what specification such a root element complies with (since that is quite clear).
• In addition, since both ODF 1.0 and ODF 1.1 have office:version be optional. The only thing to be said when the attribute is missing is that the root element complies with a version of ODF earlier than ODF 1.2.
• I agree that office:version should be required for ODF 1.2 but that omission of the attribute signifies the element complies with an previous version of ODF, and that explicit indication of ODF 1.1 and ODF 1.2 signifies the definition that is stated in those standards.

• I disagree with changing the scope of the definition beyond the element, both because of problems with conformance language and other factors that will need to be reconciled with a sharper definition of document type and document structure. -- orcmid 2008-12-10 06:22:56

Use cases:

Use of office:version and manifest:version needs to be clarified as to the degree to which they are (loosely) descriptive and restrictive and what the requirements are for down-level and up-level acceptors, including the preferable behavior of down-level processors that encounter unrecognized or unsupported features in a known or later version.
'''TBD:''' No need for elaborate formal use cases.  But give a few sentences that explain what this feature is and does from the perspective of the consumer of this feature.  The consumer might be the end user of the application.  It might be an application developer.  It might be an archivist.  It could be almost anyone.  But please give a few words on why this feature should interest us.

Alternatives considered:

There is often more than one way to accomplish a task.  For your use case, what other alternatives did you consider, and why did you find them inadequate?  '''TBD'''

Requested changes to the ODF Standard

1. This version of the proposal does not address the manifest:version attribute.  
   This will be dealt with separately.

2. This version will be reconciled with the final Conformance section as the 
   ODF 1.2 specification is pulled together. 

3. The use of the loose term "apparently ODF" will be revisited and clarified
   in some way, if that portion is retained.

4. There is a tacit assumption, in the notes and in the recommended optional 
   treatment of non-1.2 document as 1.2, that the breaking changes between 
   ODF 1.2 and earlier versions are explicitly known, at least in some non-
   normative guidance. 

Replace the text in section 18.588 of OpenDocument-v1.2-draft7-13.odt with the following text -- orcmid 2009-01-12 18:16:27):

18.588 The office:version attribute

The office:version attribute identifies the version of ODF specification that defines the associated element, its schema, its complete content, and its interpretation.

The office:version attribute shall be present in each and every <office:document>, <office:document-content>, <office:document-styles>, <office:document-meta>, and <office:document-settings> element in the XML documents that comprise an ODF 1.2 document. The value of the office:version attribute shall be "1.2".

• Note: Notwithstanding the occurrences of office:version="1.2", an ODF 1.2 document that relies solely on features of a previous ODF specification that are upward-compatible into ODF 1.2 can also be interpreted correctly under that earlier specification by taking the office:version attribute as everywhere omitted or as identifying that earlier version instead. See also Appendix H, Changes From Previous Specification Versions (Non-Normative).

• Note: When an office:version-requiring element has office:version="1.1" the element and its content are based on the OpenDocument v1.1 specification [ODF11]. For office:version="1.0" the element and its content are based on the OpenDocument v1.0 specification [ODF10]. When an office:version-requiring element has office:version omitted, the element is based on a version of the OpenDocument specification earlier than ODF 1.2. In these cases and in the case of values other than "1.2" for office:version, the elements do not comprise an ODF 1.2 document.

In any case where an apparent ODF document does not provide the office:version attributes and values required for ODF 1.2 documents, an ODF 1.2 implementation may process the document as if it is an ODF 1.2 document:

• In doing so, the implementation should behave as if the requisite office:version="1.2" attributes are present.

• Any elements and attributes based on earlier versions of ODF for which the same-named ODF 1.2 features are incompatible need not be accepted. If accepted, an ODF 1.2-incompatible feature should be cast into an equivalent but ODF 1.2-compatible form. See Appendix H, Changes From Previous Specification Versions (Non-Normative), as well as previous specifications and any approved errata for them.

• Any elements and attributes that are neither recognized, accepted, nor supported by the implementation, even though identified in XML namespaces defined for use in ODF 1.2 documents, should be treated in accordance with the rules for foreign elements and attributes (section 1.4).

• Subsequent processing should be as if the accepted document were exactly the ODF 1.2 document derived in this way.

[Note to Editor: These section numbers and (corrected) Appendix letters correspond to those of OpenDocument-v1.2-draft7-13.odt and may need to be reviewed and adjusted to apply to subsequent drafts.]

Schema changes/additions:

The current schema has office:version="1.2" be an office-document-common-attrs non-optional attribute with required value. This proposal makes no change to the schema.

Impacts

Conformance:

This proposal requires that explicit schema version dependency be provided in all XML parts of ODF 1.2 document representations. The version dependency is not optional for ODF 1.2. Absence of explicit version indication is defined to signify presence of an XML part specified in a previous specification for ODF. The recommended behavior when accepting different-versions document into a processor for ODF 1.2 is made explicit and optional.

Backwards compatibility:

This proposal applies specifically to ODF 1.2. The version significance for ODF 1.0 and ODF 1.1 is preserved and processors that accept and produce those format versions are not impacted.

Accessibility impact:

This feature has no impact on accessibility. The feature addresses conformance of XML documents, involving attributes and conformance aspects that are not related to presentation and accessibility of document format and content.

Difficulties with preservation of accessibility features that differ across versions of ODF are unchanged by this definition of version significance.

Workflow (to be filled in by TC Chairs)

Category: CategoryIntegratedProposal CategoryODF1.2Proposal

Date Proposal initially made:

Dates Proposal discussed on TC calls:5 January 2009

Date vote is requested:

Date vote is held: 19-01-2008

Results of vote: preliminary approved, see minutes

ODF version into which the proposal has been integrated: ODF 1.2 draft 8

• CategoryNewProposal