Re: Request for TC feedback about @subjectrefs proposal

[Eliot Kimber <eliot.kimber@servicenow.com>]

Reading this draft I think we need to be very clear about how the subjectScheme map can or must be associated with the map that makes @subjectrefs references and what the implications are, if any, for unresolvable keys.

 

I think that the following cases need to be accounted for:

 

1. Simple inclusion of the subjectScheme map in the referencing map. In this case, any keys defined in the subjectScheme are part of the key space of the referencing map per normal keyspace construction rules. The fact that the map happens to be a subjectScheme map is not relevant for the purposes of key space construction.
   
   
2. Use of the subjectScheme as a peer map:
   
   <map subjectrefs=”ss1.subject-01 ss1.subject-02”>
     <mapref scope=”peer” keyscope=”ss1” href="">   …
   </map>
   
   In this case, the subjectScheme is a separate root map but the subject keys are resolvable using normal cross-deliverable link key resolution rules (meaning if the referenced subjectScheme map is available to process the keys are resolvable and if it’s not then they aren’t and that isn’t a hard-stop error condition, only a warning at most). Again, the fact that the referenced map is a subjectScheme map is not relevant to the key space construction processing.
   
   
3. No subjectScheme is referenced from the map. In this case the subject keys are not resolvable using DITA-defined mechanisms, but a processor might define a way to define subjectScheme maps to use when resolving subjectrefs.

 

Note the implication that normal scoped key resolution rules apply: the same subject referenced in different scopes might resolve to different subjects in different subject scheme maps.

 

In all of these cases there is the question of whether or not DITA processors are required to attempt to resolve keys referenced from @subjectrefs. I think they should *not* be required to attempt to resolve them, making @subjectrefs key resolution a MAY not a MUST. I think SHOULD would be too strong as a lot of processors will simply never care about @subjectrefs and shouldn’t be made to feel bad for not doing anything with them.

 

The way I would expect processors to work is to treat @subjectrefs values as first-and-foremost simple classification keyword values as though they had been specified using e.g., <data value=”ss1.subject-01”/> or <data name=”ss1” value=”subject-01”/>: it’s metadata and who or what can make sense of it is a local concern. When the referenced key can be resolved then processors are free to do whatever they want with the resource bound to the key, if anything.

 

With this approach it cannot be a DITA-defined error to not be able to resolve subjectrefs keys, although processors MAY treat it as an error if the processor depends on the subject being resolvable (i.e., an application that uses subjectrefs to construct some essential aspect of the result using the resources bound to the keys).

 

This avoids requiring processors attempt to resolve subjectref keys when they otherwise don’t know anything about subject schemes.

 

Cheers,

 

E.

 

 

_____________________________________________

Eliot Kimber

Sr Staff Content Engineer

O: 512 554 9368

M: 512 554 9368

servicenow.com

LinkedIn | Twitter | YouTube | Facebook

 

From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> on behalf of kris eberleinconsulting.com <kris@eberleinconsulting.com>
Date: Monday, May 16, 2022 at 9:57 AM
To: dita <dita@lists.oasis-open.org>
Subject: [dita] Request for TC feedback about @subjectrefs proposal

[External Email]

 

I was expecting to send the stage three proposal to reviewers (Robert, Gershon, Carsten) last Friday, but ran into some glitches when considering how to update the example topics in the “Cascading metadata” section of the spec.

 

The technical requirements outlined in the stage two proposal called for adding @subjectrefs to <topicref> and specializations of <topicref>. Now I’m wondering if @subjectrefs should also be available on <map>.

 

I don’t think setting @subjectrefs on <map> will be something that folks often do, but it would make it easier to explain how @subjectrefs cascades from a <mapref> element to the topics referenced in the submap.

 

I was hoping to simply edit the following topic: “Example: How attributes cascade from one map to another” …

 

Draft stage three proposal attached, as well as a PDF of the extant example topic.

 

Kris