Conformation statement -- please review and discuss before the TCmeeting

This chapter outlines the requirements that must be met for documents, document types, specialization modules, and processors to be considered DITA conforming. This chapter also defines conformance related terminology that is used throughout the DITA specifications.

Conformance to the DITA specifications allows documents and document types that are shared within and across organizations and used with different processors or different versions of a processor to produce the same or similar results with little or no reimplementation.

Keywords

The capitalized words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the DITA specifications are to be interpreted as described in IETF RFC 2119. When these words are not capitalized, they should be interpreted in their natural-language sense.

The use of these keywords and other conformance requirements increase the level of interoperability that is available between DITA conforming implementations. Their use is not meant to impose particular methods on implementers where the method is not required for interoperability.

Conformance statement

DITA conforming implementations MUST include a conformance statement that lists the DITA features that are supported by the implementation and are implemented in accordance with the requirements of the DITA specifications together with the version of the DITA specification. Or, if it is clearer, the statement MAY say that the implementation includes all of the features for a particular category of implementation together with a list of features that are not included.

Documents, document types, specialization modules, and processors that implement the requirements given in the OASIS approved DITA specifications are considered conforming.

Implementations that include some DITA features, but not others, are considered conforming as long as all REQUIRED features for the category of implementation are included and all of the features that are included follow the requirements given in the DITA specification. An implementation which does not include a particular optional feature MUST be prepared to interoperate with another implementation which does include the feature, though perhaps with reduced functionality. And, while less common, an implementation which does include a particular optional feature MUST be prepared to interoperate with another implementation which does not include the feature.

Organizations and individuals are free to impose additional constraints on their own use of DITA that go beyond the requirements imposed by the DITA specifications, possibly including enforcement of the constraints by their local tools, as long as the result continues to meet the requirements given in the DITA specifications. For example, a given user community could impose rules on how files must be named or organized even if those rules go beyond the requirements given in the DITA specifications.

Conformance categories

The following categories are used to define the amount of flexibility that is available when implementing specific requirements.

Required and invariant

Features that MUST be implemented exactly as defined in the DITA specification. This classification applies primarily to the XML syntax, DITA documents, the rules for creating DITA specializations and document types, and address resolution behavior. For example where a given address must always resolve to the same object for the same input data set.

Required but variable

Features that MUST be implemented and for which the effective result MUST be consistent with rules as defined in the DITA specification but for which the specific expression may vary.

For example, any implementation of the content reference feature MUST reflect the same effective result for the same input data set but the way that effective result is provided can vary. The content reference could be implemented by a pre-process step that replaces the reference by the referenced content or by a process that generates the functional equivalent of the content reference in the target output (e.g., a transclusion instruction in a Wiki page).

Variable with defaults

Features that MAY produce various behaviors or outputs, but for which the DITA specification defines a default that all conforming implementations MUST provide.

Implementations are NOT REQUIRED to make the DITA-defined default their default. Implementations are only REQUIRED to provide an appropriate set of options or configuration that will provide the DITA-defined defaults.

These features are primarily formatting defaults for elements where a default presentation is natural or expected, such as paragraphs, lists, and tables. An application for a specific use domain might define default formatting behaviors that are significantly different from the DITA-defined defaults. For example, an application specifically for legal information could provide a different default presentation from an application for technical documentation.

Variable without defaults

Features that MAY be implemented to produce various behaviors or outputs and for which the DITA specification defines no required default.

The DITA specification may include examples or suggested behaviors for these features but such suggestions are informative, not normative.

Informative or non-normative

The DITA specifications include examples and other suggestions that are informative rather than normative. While informative information is often very helpful, it is never a binding part of the DITA specifications even when the example or other information is about a feature that is REQUIRED.

If a particular conformance category is not specified for a feature and the appropriate category cannot be determined from the information available in the DITA specifications the feature MUST be considered required and invariant. Unless it is clearly stated otherwise, examples are always informative rather than normative.

Processors and processor type categories

Processors that implement some DITA features, but not others, are considered conforming as long as the features that are implemented follow the requirements given in the DITA specification for those features. Processors that are not DITA aware are not considered conforming, but may still be useful when working with DITA.

The level of conformance for a given processor can only be determined by examining the features that the component implements and the degree to which these features follow the requirements given in the DITA specifications.

Because the number of possible DITA-aware processors is large, it is useful to define several processor type categories that can be used to define which requirements apply to which processors. A given processor may belong to more than one category.

The DITA specifications use the following categories of processor types in defining processor related requirements and suggestions:

DITA-aware processor

A processor that implements features defined by the DITA specifications including all of the required and invariant, the required but variable, the variable with defaults, and other requirements from the DITA specifications for the features that it includes.

All conforming DITA processors must be specialization aware such that they are able to process any valid DITA document regardless of the details of its governing document type.

DITA editor

An interactive application that enables the creation and modification of conforming DITA documents.

Information management system

A processor that stores and manages DITA documents in a way that takes advantage of DITA-specific aspects of the data in order to facilitate the management of those documents through a development or delivery process. Such systems may be content management systems that support authoring workflows or they may be retrieval systems that support delivery workflows.

Renderer

A processor that takes as input one or more conforming DITA documents and produces as output final-form renderings of those documents, such as HTML pages, paginated PDF, compiled online help, etc. Most simply, a DITA renderer is a processor that is directly responsible for producing a visual, aural, tactile, or interactive result from DITA content, either by providing the rendition directly or by providing direct input to the rendition delivery system (e.g., providing HTML content to a Web browser or typesetting commands to a pagination system). A renderer always either incorporates a source-to-source transform within itself or uses the output of a standalone source-to-source transformer.

Source-to-source transformer

A processor that takes as input one or more DITA or non-DITA documents and produces as output non-final-form XML documents. At least one of the input or output documents must be a conforming DITA document, but he output documents are NOT REQUIRED be conforming DITA documents. Source-to-source transformers may be standalone tools or may be inseparable components of tools in other categories.

Rendition categories

Draft comment:
Draft-comment: It is unclear if some or even any of these rendition categories will be used elsewhere in the DITA specification. If they are not used, this section will be deleted.

Not all rendition requirements, defaults, and suggestions are relevant to all possible rendered outputs. The DITA specifications use the following rendition types in defining rendition requirements and suggestions:

HTML-based interactive media: Renditions that use HTML markup as the primary representation, intended to be viewed through Web browsers or similar online, interactive systems.
paged media: Renditions that produce images of physical pages intended for printing on paper.
Embedded "constrained format" help: Help for use with highly constrained delivery environments such as mobile phones and printer consoles.
aural: Renditions that are intended for aural consumption by human listeners.
interactive: Renditions that include interactive behavior as a primary aspect of their presentation, such as an interactive electronic technical manual or an interactive learning application.

Conformance by feature groups

The following summary outlines the conformance requirements for high-level groups of features. For more detailed conformance information see the feature descriptions contained in the DITA specifications or the summary table in Appendix ?

Draft comment:
Draft-comment: It is possible that we should omit this section and just use the summary table in the Appendix.

Documents

Required but variable.

A conforming DITA document MUST be syntactically valid with respect to a conforming XML document type declaration (DTD) or XML schema document (XSD) and MUST otherwise implement all content and structure requirements defined by the DITA specifications.

Conforming DITA processors MUST be able to process all conforming DITA documents, but they are NOT REQUIRED to support all features that may be present in or used from those documents.

Document types (element and attribute definitions)

Required but variable.

A conforming DITA document type MUST implement all of the syntactic and organizational requirements for DITA document type declarations (DTDs) or schemas (XSD) as defined by the DITA Architecture Specification.

Conforming DITA processors MUST be able to process all conforming DITA document types, but they are NOT REQUIRED to support all features that may be available for use from those document types.

Specialization modules

Required but variable.

A conforming DITA specialization module MUST implement all of the syntactic and organizational requirements for DITA specialization modules as defined in the DITA Architecture Specification.

Conforming DITA processors MUST be able to process conforming DITA document types that include specialization modules, but they are NOT REQUIRED to support all features that may be available for use from those document types.

Addressing

Required and invariant.

Addressing includes the pointers from one DITA construct to another or from a DITA construct to a non-DITA construct including: href, conref, keyref, and other reference values.

Addressing includes the syntax that MUST be used to write addresses (pointers) as strings within DITA documents and the rules which MUST be followed when pointers are resolved to resources. How the resource is used once it is resolved is not covered by this feature group.

Linking

Required but variable.

Includes those features that establish relationships among abstract components, including: topicref , xref, reltable and data-about.

For a given relationship the set of related components and their DITA-defined roles within the relationship are required and invariant. However, the rendition result for a given relationship instance or type is variable with defaults for most or all of the DITA-defined link types.

Content reference (conref)

Required and invariant.

This is a special case of linking where there is less room for variance. In particular, the effective value of resolving a conref MUST be invariant for a given pair of elements. However, the rendition result for a Content Reference could vary.

Rendition behavior

Variable with or without defaults.

Includes all features that relate to how a given element looks or behaves interactively in the context of a particular rendition type. It is mostly bound to element types, e.g., lists must have a list nature, tables should have tabular nature, etc. Rendition is either rendition-specific with defaults or rendition specific.

While wide variation in rendition is possible, there is an intent that the rendition of a given element type be consistent with its core semantic. For example a "pre" element SHOULD NOT be rendered as flowing text unless it can be shown that the particular rendering is consistent with the basic semantic of "pre". In these cases the intent of the specification is often expressed through definition of variable with defaults rendering effects.

dita message

Conformance

Keywords

Conformance statement

Conformance categories

Processors and processor type categories

Rendition categories

Conformance by feature groups