How to use DITA subjectSchemes?

Question

The subjectScheme in DITA is a suitable format for creating a taxonomy of metadata, but how should it really be used? Specifically, my question regards the following:

1. Can it be used to represent metadata elements, or only metadata attributes? I've only seen it applied to attributes, which makes it kind of limited, since as far as I know elements are usually used for retrieval metada, i.e. not metadata used for filtering.
2. If you could use it for elements, should the value still be in the "keys" attribute of the subjectdef?
3. If you want to add a definition/description to a metadata value, where would you do that?
4. Can/should you publish subjectSchemes? I've seen it suggested that it is not intended for publishing, due to its resource-only default attribute. But isn't that limiting? If you use it to create a taxonomy, surely you would also want a simple way to publish it for the benefit of the users?

Answer 1

I'm going to do my best to address your original questions. Overall, the subjectScheme specialization is designed to create subject classifications and controlled values. It has great functionality for defining subject classifications that can be used for retrieval, as well as defining and controlling attribute values. Currently, the DITA-OT only provides functionality in the area of controlled values for attributes.

Question: "Can it be used to represent metadata elements or only metadata attributes"?

Answer: I would not say that its purpose is to "represent elements or attributes". It is designed to represent subjects and controlled values. Its design is based on keys and so makes heavy use of attributes.

Question: If you want to add a definition for an attribute value, where do you do so?

Answer: You have several options for doing this:

• You can create an associated topic that describes the subject or attribute value. You reference this topic using the @href attribute on the subjectdef element. This is especially useful for providing a consensus definition or information about when a conditional-processing value should be used.
• You can nest a topicmeta element within the subjectdef element; within the topicmeta element, you have access to the shortdesc and navtitle elements.
• You add content to the @navtitle attribute on the subjectdef element. I would not recommend this, as the @navtitle attribute is deprecated and usually cannot be translated.

Question: Can you use the subjectScheme specialization with metadata elements?

Answer: Yes. Off the top of my head, here is one immediate possibility and design for an HTML-based output format:

• For a specific subject, add a topicmeta element to the subjectdef element. Within the topicmeta element, you have full access to all the metadata elements. Add as many metadata elements as you like.
• Associate the DITA topics with the relevant subject. This can be done either by using specific attribute and values, or by using the subjectref element from the classification domain.
• Tweak the output processing so that each DITA topic associated with the subject has the metadata written to the HTML, just as it would be if the metadata elements were located in the DITA topics itself. With this design, you have enforced consistency and, because of the key-based architecture, ease of maintenance and an abstraction layer.

Question: Can you publish subject schemes?

Answer: Yes, if topics are referenced for subjectdef elements using the @href attribute. While by default, the @processing-role attribute for the subjectScheme element is set to "resource-only" and the @toc attribute is set to "no," you can modify those values and they will cascade throughout the map, making it possible to generate output. Of course, this is simply what one can currently do using the DITA-OT; with custom processing implementations, the possibilities are boundless.

I think subjectScheme maps and the classification domain offer lots of exciting possibilities, including faceted and filtered browsing (for output) and faceted searching (for DITA source).

I hope that people building implementations that make use of subjectScheme and classification will share stories, demo their implementations, and so forth. I think that would make what can be done with this part of the DITA architecture clearer and more accessible for people.

Answer 2

As far as the DITA-OT goes, I think you can only use it for conditional processing (filtering and flagging) of elements using DITAVAL files.

I think subject scheme maps have far more potential than this. They could be used for faceted browsing so we could dispense with static topic maps. Static content just seems to belong to the pre-web era. DITA's slightly staid aura could be solved with this.

Anyway, here's what you can currently do:

Subject scheme map:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE subjectScheme PUBLIC "-//OASIS//DTD DITA Subject Scheme Map//EN" "map.dtd"> 
<subjectScheme>
    <hasInstance>
        <subjectdef keys="all_routes">
            <subjectdef keys="every_route">
                <subjectdef keys="anglia"/>
                <subjectdef keys="east_midlands"/>
                <subjectdef keys="kent"/>
                <subjectdef keys="lne_london_north_eastern"/>
                <subjectdef keys="lnw_london_north_western"/>
                <subjectdef keys="scotland"/>
                <subjectdef keys="wales"/>
                <subjectdef keys="sussex"/>
                <subjectdef keys="wessex"/>
               <subjectdef keys="western"/>
            </subjectdef>
        </subjectdef>
    </hasInstance>

    <enumerationdef>
        <attributedef name="route"/>
        <!-- Above is my new specialized attribute "routes"! -->
     <subjectdef keyref="all_routes"/>
    </enumerationdef>

Here is the topic text with the metadata:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA General Task//EN" "task.dtd">
<task id="task_ozd_ckn_qh">
  <title>Route specialization test</title>
  <shortdesc route="">This tests the new route attribute!</shortdesc>
  <taskbody>
     <section>
         <title>Lines of text</title>
         <p route="anglia">Anglia text text text text text text.</p>
         <p route="sussex">Sussex text text text text text text.</p>
         <p route="east_midlands">East Midlands text text text text text.</p>
         <p route="kent">Kent text text text text text text.</p>
         <p route="lne_london_north_eastern"NE text text text text text text.</p>
         <p route="lnw_london_north_western">LNW text text text text text text.</p>
         <p route="scotland">Scotland text text text text text text.</p>
         <p route="sussex"Sussex text text text text text text.</p>
         <p route="wales">Wales text text text text text text.</p>
         <p route="western">Western text text text text text text.</p>
         <p route="wessex">Wessex text text text text text text.</p>
         <p route="every_route">Text.</p>
         <p>Not profiled.</p>
     </section>
  </taskbody>

Here's the DITAVAL filter:

  <prop action="exclude" att="route"/>
  <prop action="include" att="route" val="scotland"/>

This will knock out all the other routes except the route marked with "scotland".

That's basically it.

You can add metadata into the subject scheme map like this:

   <subjectdef keys="story_attributedef">

       <subjectdef keys="monster">
           <hasKind>
               <subjectdef keys="zarbi" href="glossary/contemporary.dita">
                   <topicmeta>
                       <navtitle>The Zarbi</navtitle>
                       <shortdesc>Ant-like creature</shortdesc>
                   </topicmeta>
               </subjectdef>

Subject scheme maps are rendered as "resource-only" (whether they have that value or not) so it's not suitable for rendering.