DITA Proposed Feature # 20

Extensible metadata attributes.

Longer description

Allow document type authors to incorporate new attributes that can be used for filtering and flagging. Since the new attributes change the document model, their presence in the document type needs to be signalled to processes that care about that sort of thing (eg conref, generalization, respecialization). The proposed solution is to define a new global attribute, @props, and a new specialization capability, domain specialization of attributes. The new specialization capability would only be supported for the new @props attribute in DITA 1.1 but could be considered for wider adoption in future releases unless a better mechanism for adding attributes emerges.

Scope

Major

Use Case

  1. DITA architect for a team defines new attributes that are needed by the team (eg proglanguage)
  2. DITA architect expresses each new attribute as a separate domain package (eg proglanguage.mod, with new attribute specialized from props attribute)
  3. DITA architect integrates the domain packages into the authoring DTDs or schemas (eg redefining "props" attribute entity to include proglanguage attribute, same way we redefine element entities to integrate new domain elements; and adding the new attribute domain to the list of domains in the domains attribute, preceded by an "a"; for example domains="a(props proglanguage)" or domains="props audience role")
  4. Author can now add values to the new attributes, since they are physically present in the document type
  5. Build developer defines values in ditaval format and runs a build to remove or flag content based on the new attributes (eg flag all proglanguage="Java")
  6. Another build developer includes their content but needs to run all content through a specialization-unaware trademarking tool that requires generalization of the contributed content; after generalization, the content is processed into output with filtering based on the new attributes (which are now collapsed into props attribute). In other words, the generalize process turned proglanguage="Java" into props="proglanguage(Java)", and the conditional processing transform recognized the new form as equivalent to the old.
Summary of requirements:
  • Writers need to add attributes for conditional processing, following the existing model of platform, audience, etc. Requirement can be met by extending domain specialization rules to allow attribute domains.
  • New attributes need to be addressable by existing DITA-based conditional processing applications (ie be specialization-aware). Requirement can be met by improving conditional-processing applications.
  • Attributes need to be preserved during generalization, and remain processable by existing conditional processing applications as well as respecializable. Requirement can be met by improving conditional-processing applications.

Note that each base attribute we make specializable will require improved processing support to allow equivalent processing of both specialized and generalized forms of the content. This requirement currently addresses required changes to create a new "props" base attribute from which we can specialize the other metadata/profiling attributes. Equivalent work would be necessary for each attribute we so enable. For example, if we wanted to enable @href for specialization, we would need to define specialization and generalization rules for the attribute, and improve @href processing to handle both specialized and generalized forms.

Technical Requirements

Change to the architectural specification to allow specialization of new attributes off of existing ones, following domain model described above.

Define syntax for generalized attribute values that allows for continued processing and roundtripping, following syntax in otherprops for grouping values.

Replace existing section of specification on how to "break" architecture to get attribute specialization.

Add a "props" attribute to the architecture, from which the other metadata attributes (platform, product, audience, otherprops) will be specialized.

Add documentation for attribute-only domains, with syntax for expressing them in the domains attribute (for example by putting an "a" in front of a domain ancestry list)

Ensure all attributes are expressed in entities to allow domain-based expansion/specialization (DTDs); document equivalent mechanism for schemas

Formalize and document ditaval format, including logic for filtering, flagging, ignoring, or passing through values in the props attribute or in attributes specialized from the props attribute

Costs

Time required for design should hopefully be minimal. There will be more work by the open-source toolkit to enhance existing transforms to handle attribute generalization and respecialization, and make the conditional processing logic specialization-aware. If we want to make the process completely enabled for all attributes, we will want to add a standard routine that makes sure generalized attributes are processed correctly (ie any info added to support round-tripping will be ignored by output processes).

Benefits

Many people would make use of this. It is consistently a highly rated requirement. For some, this would remove a major barrier to DITA adoption.

Time Required

3 1-hour meetings to review requirements

3 1-hour meetings to agree on solution

2 days to complete document solution