OASIS Darwin Information Typing Architecture (DITA) TC

While working through action items about keys in the spec, I realized I'm still unclear on one thing about key scopes and subject schemes. Assume that I have my taxonomy and controlled values in a subject scheme map. The map is pulled into my root map with the key scope set to "tax". The scheme is used to set up all my taxonomy subjects, and to set controlled values for @audience, @platform, and @product. I can use the <subjectref> element to reference subjects. In this case I think it's clear that I should include the scope, because these keys resolve just as any other keys: <subjectref keyref="tax.myproduct"/> I'm not clear what we determined for attribute values. Assume the subject scheme defines the keys "user" and "admin", then restricts @audience to just those values. Looking at the subject scheme in isolation, it appears I'm restricting @audience to the literal values "user" and "admin", which are also key names. The question is - in the broader context of the root map, where I've put my subject scheme into the key scope "tax", what values are valid for @audience? In topics referenced from my map, is @audience restricted to "user" and "admin", or is it restricted to "tax.user" and "tax.admin"? I think we decided it's the former because doing otherwise will be difficult (if not impossible) to manage. But, I feel we've gone around on these issues enough that I need to double check before moving forward. Thanks - Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ )

My understanding of our decision was that attribute value validation is always in terms of the unqualified values. If value validation included scope values it would require map authors to always use the same scope hierarchy for a given subject scheme map in every map that included it. In addition, the scope qualification might not make sense for some values. So I think the only right answer is that value validation is done with respect to the unqualified @keys values in the subject scheme map. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 4/3/15, 10:13 AM, "Robert D Anderson" <robander@us.ibm.com> wrote: >While working through action items about keys in the spec, I realized I'm >still unclear on one thing about key scopes and subject schemes. > >Assume that I have my taxonomy and controlled values in a subject scheme >map. The map is pulled into my root map with the key scope set to "tax". >The scheme is used to set up all my taxonomy subjects, and to set >controlled values for @audience, @platform, and @product. > >I can use the <subjectref> element to reference subjects. In this case I >think it's clear that I should include the scope, because these keys >resolve just as any other keys: ><subjectref keyref="tax.myproduct"/> > >I'm not clear what we determined for attribute values. Assume the subject >scheme defines the keys "user" and "admin", then restricts @audience to >just those values. Looking at the subject scheme in isolation, it appears >I'm restricting @audience to the literal values "user" and "admin", which >are also key names. > >The question is - in the broader context of the root map, where I've put >my subject scheme into the key scope "tax", what values are valid for >@audience? In topics referenced from my map, is @audience restricted to >"user" and "admin", or is it restricted to "tax.user" and "tax.admin"? I >think we decided it's the former because doing otherwise will be >difficult (if not impossible) to manage. But, I feel we've gone around on >these issues enough that I need to double check before moving forward. > >Thanks - > >Robert D Anderson >IBM Authoring Tools Development >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ )

I agree. However, I think we need to decide exactly what the spec needs to say and where. I've just re-read through the subjectScheme content as it currently exists in SVN. (PDF attached). We don't mention key scopes anywhere in it. I think that perhaps the relevant place is the following topic (specific content highlighted in bold ): ---- Processing controlled attribute values An enumeration of controlled values can be defined with hierarchical levels by nesting subject definitions. This affects how processors perform filtering and flagging. The following algorithm applies when processors apply filtering and flagging rules to attribute values that are defined as a hierarchy of controlled values and bound to an enumeration: 1. If an attribute specifies a value in the taxonomy, and a DITAVAL or other categorization tool is configured with that value, the rule matches. 2. Otherwise, if the parent value in the taxonomy has a rule, that matches. Subject scheme maps 3. Otherwise, continue up the chain in the taxonomy until a matching rule is found. The following behavior is expected of processors: • Processors SHOULD be aware of hierarchies of attribute values that are defined in subject scheme maps for purposes of filtering, flagging, or other metadata-based categorization. • Processors SHOULD validate that the values of attributes that are bound to controlled values contain only valid values from those sets. (The list of controlled values is not validated by basic XML parsers.) • Processors SHOULD check that all values listed for an attribute in a DITAVAL file are bound to the attribute by the subject scheme before filtering or flagging. If a processor encounters values that are not included in the subject scheme, it SHOULD issue a warning. ---- Maybe we need to add If the @keyscope attribute is set on the root element of the subjectScheme map or any of the elements that it contains, the attribute is ignored for the purpose of validating the controlled values ? Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 4/3/2015 11:22 AM, Eliot Kimber wrote: My understanding of our decision was that attribute value validation is always in terms of the unqualified values. If value validation included scope values it would require map authors to always use the same scope hierarchy for a given subject scheme map in every map that included it. In addition, the scope qualification might not make sense for some values. So I think the only right answer is that value validation is done with respect to the unqualified @keys values in the subject scheme map. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 4/3/15, 10:13 AM, Robert D Anderson <robander@us.ibm.com> wrote: While working through action items about keys in the spec, I realized I'm still unclear on one thing about key scopes and subject schemes. Assume that I have my taxonomy and controlled values in a subject scheme map. The map is pulled into my root map with the key scope set to tax . The scheme is used to set up all my taxonomy subjects, and to set controlled values for @audience, @platform, and @product. I can use the <subjectref> element to reference subjects. In this case I think it's clear that I should include the scope, because these keys resolve just as any other keys: <subjectref keyref= tax.myproduct /> I'm not clear what we determined for attribute values. Assume the subject scheme defines the keys user and admin , then restricts @audience to just those values. Looking at the subject scheme in isolation, it appears I'm restricting @audience to the literal values user and admin , which are also key names. The question is - in the broader context of the root map, where I've put my subject scheme into the key scope tax , what values are valid for @audience? In topics referenced from my map, is @audience restricted to user and admin , or is it restricted to tax.user and tax.admin ? I think we decided it's the former because doing otherwise will be difficult (if not impossible) to manage. But, I feel we've gone around on these issues enough that I need to double check before moving forward. Thanks - Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php Attachment: subject-scheme-maps.pdf Description: Adobe PDF document

I'd make one change to what Kris suggested. Based on this suggestion: "If the @keyscope attribute is set on the root element of the subjectScheme map or any of the elements that it contains, the attribute is ignored for the purpose of validating the controlled values" The key scope can be set inside of a scheme, on the root of the scheme, on a reference to a scheme, or somewhere in the hierarchy above the reference to the scheme. All of those have the same result and should be covered by this new language. So, I'd suggest rewording along the lines of: "If the controlled values are part of a named key scope, the scope name is ignored for the purpose of validating the controlled values". Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) Kristen James Eberlein ---04/03/2015 11:00:57---I agree. However, I think we need to decide exactly what the spec needs to say and where. I've just From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org Date: 04/03/2015 11:00 Subject: Re: [dita] Key scopes for subjectdef versus controlled attribute values Sent by: <dita@lists.oasis-open.org> I agree. However, I think we need to decide exactly what the spec needs to say and where. I've just re-read through the subjectScheme content as it currently exists in SVN. (PDF attached). We don't mention key scopes anywhere in it. I think that perhaps the relevant place is the following topic (specific content highlighted in bold ): ---- Processing controlled attribute values An enumeration of controlled values can be defined with hierarchical levels by nesting subject definitions. This affects how processors perform filtering and flagging. The following algorithm applies when processors apply filtering and flagging rules to attribute values that are defined as a hierarchy of controlled values and bound to an enumeration: 1. If an attribute specifies a value in the taxonomy, and a DITAVAL or other categorization tool is configured with that value, the rule matches. 2. Otherwise, if the parent value in the taxonomy has a rule, that matches. Subject scheme maps 3. Otherwise, continue up the chain in the taxonomy until a matching rule is found. The following behavior is expected of processors: • Processors SHOULD be aware of hierarchies of attribute values that are defined in subject scheme maps for purposes of filtering, flagging, or other metadata-based categorization. • Processors SHOULD validate that the values of attributes that are bound to controlled values contain only valid values from those sets. (The list of controlled values is not validated by basic XML parsers.) • Processors SHOULD check that all values listed for an attribute in a DITAVAL file are bound to the attribute by the subject scheme before filtering or flagging. If a processor encounters values that are not included in the subject scheme, it SHOULD issue a warning. ---- Maybe we need to add "If the @keyscope attribute is set on the root element of the subjectScheme map or any of the elements that it contains, the attribute is ignored for the purpose of validating the controlled values" ? Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 4/3/2015 11:22 AM, Eliot Kimber wrote: My understanding of our decision was that attribute value validation is always in terms of the unqualified values. If value validation included scope values it would require map authors to always use the same scope hierarchy for a given subject scheme map in every map that included it. In addition, the scope qualification might not make sense for some values. So I think the only right answer is that value validation is done with respect to the unqualified @keys values in the subject scheme map. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 4/3/15, 10:13 AM, "Robert D Anderson" <robander@us.ibm.com>  wrote: While working through action items about keys in the spec, I realized I'm still unclear on one thing about key scopes and subject schemes. Assume that I have my taxonomy and controlled values in a subject scheme map. The map is pulled into my root map with the key scope set to "tax". The scheme is used to set up all my taxonomy subjects, and to set controlled values for @audience, @platform, and @product. I can use the <subjectref> element to reference subjects. In this case I think it's clear that I should include the scope, because these keys resolve just as any other keys: <subjectref keyref="tax.myproduct"/> I'm not clear what we determined for attribute values. Assume the subject scheme defines the keys "user" and "admin", then restricts @audience to just those values. Looking at the subject scheme in isolation, it appears I'm restricting @audience to the literal values "user" and "admin", which are also key names. The question is - in the broader context of the root map, where I've put my subject scheme into the key scope "tax", what values are valid for @audience? In topics referenced from my map, is @audience restricted to "user" and "admin", or is it restricted to "tax.user" and "tax.admin"? I think we decided it's the former because doing otherwise will be difficult (if not impossible) to manage. But, I feel we've gone around on these issues enough that I need to double check before moving forward. Thanks - Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail.  Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php   [attachment "subject-scheme-maps.pdf" deleted by Robert D Anderson/Rochester/IBM] --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail.  Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php  

I'll update the topic with the changes suggested by Robert. Folks, please check and see whether you are satisfied that this handles the issues raised in review #1 and on hold on the TC agenda for quite a while: Review #1 comments re subjectdef elements and key scopes (on hold) https://lists.oasis-open.org/archives/dita/201407/msg00029.html (Eberlein, 20 July 2014) https://lists.oasis-open.org/archives/dita/201407/msg00032.html (Nitchie, 21 July 2014) https://lists.oasis-open.org/archives/dita/201407/msg00033.html (Eberlein, 21 July 2014) https://lists.oasis-open.org/archives/dita/201407/msg00034.html (Kimber, 21 July 2014) https://lists.oasis-open.org/archives/dita/201407/msg00035.html (Priestley, 21 July 2014) Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 4/3/2015 2:18 PM, Robert D Anderson wrote: I'd make one change to what Kris suggested. Based on this suggestion: If the @keyscope attribute is set on the root element of the subjectScheme map or any of the elements that it contains, the attribute is ignored for the purpose of validating the controlled values The key scope can be set inside of a scheme, on the root of the scheme, on a reference to a scheme, or somewhere in the hierarchy above the reference to the scheme. All of those have the same result and should be covered by this new language. So, I'd suggest rewording along the lines of: If the controlled values are part of a named key scope, the scope name is ignored for the purpose of validating the controlled values . Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) Kristen James Eberlein ---04/03/2015 11:00:57---I agree. However, I think we need to decide exactly what the spec needs to say and where. I've just From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org Date: 04/03/2015 11:00 Subject: Re: [dita] Key scopes for subjectdef versus controlled attribute values Sent by: <dita@lists.oasis-open.org> I agree. However, I think we need to decide exactly what the spec needs to say and where. I've just re-read through the subjectScheme content as it currently exists in SVN. (PDF attached). We don't mention key scopes anywhere in it. I think that perhaps the relevant place is the following topic (specific content highlighted in bold ): ---- Processing controlled attribute values An enumeration of controlled values can be defined with hierarchical levels by nesting subject definitions. This affects how processors perform filtering and flagging. The following algorithm applies when processors apply filtering and flagging rules to attribute values that are defined as a hierarchy of controlled values and bound to an enumeration: 1. If an attribute specifies a value in the taxonomy, and a DITAVAL or other categorization tool is configured with that value, the rule matches. 2. Otherwise, if the parent value in the taxonomy has a rule, that matches. Subject scheme maps 3. Otherwise, continue up the chain in the taxonomy until a matching rule is found. The following behavior is expected of processors: • Processors SHOULD be aware of hierarchies of attribute values that are defined in subject scheme maps for purposes of filtering, flagging, or other metadata-based categorization. • Processors SHOULD validate that the values of attributes that are bound to controlled values contain only valid values from those sets. (The list of controlled values is not validated by basic XML parsers.) • Processors SHOULD check that all values listed for an attribute in a DITAVAL file are bound to the attribute by the subject scheme before filtering or flagging. If a processor encounters values that are not included in the subject scheme, it SHOULD issue a warning. ---- Maybe we need to add If the @keyscope attribute is set on the root element of the subjectScheme map or any of the elements that it contains, the attribute is ignored for the purpose of validating the controlled values ? Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 4/3/2015 11:22 AM, Eliot Kimber wrote: My understanding of our decision was that attribute value validation is always in terms of the unqualified values. If value validation included scope values it would require map authors to always use the same scope hierarchy for a given subject scheme map in every map that included it. In addition, the scope qualification might not make sense for some values. So I think the only right answer is that value validation is done with respect to the unqualified @keys values in the subject scheme map. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 4/3/15, 10:13 AM, Robert D Anderson <robander@us.ibm.com>  wrote: While working through action items about keys in the spec, I realized I'm still unclear on one thing about key scopes and subject schemes. Assume that I have my taxonomy and controlled values in a subject scheme map. The map is pulled into my root map with the key scope set to tax . The scheme is used to set up all my taxonomy subjects, and to set controlled values for @audience, @platform, and @product. I can use the <subjectref> element to reference subjects. In this case I think it's clear that I should include the scope, because these keys resolve just as any other keys: <subjectref keyref= tax.myproduct /> I'm not clear what we determined for attribute values. Assume the subject scheme defines the keys user and admin , then restricts @audience to just those values. Looking at the subject scheme in isolation, it appears I'm restricting @audience to the literal values user and admin , which are also key names. The question is - in the broader context of the root map, where I've put my subject scheme into the key scope tax , what values are valid for @audience? In topics referenced from my map, is @audience restricted to user and admin , or is it restricted to tax.user and tax.admin ? I think we decided it's the former because doing otherwise will be difficult (if not impossible) to manage. But, I feel we've gone around on these issues enough that I need to double check before moving forward. Thanks - Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail.  Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php   [attachment subject-scheme-maps.pdf deleted by Robert D Anderson/Rochester/IBM] --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail.  Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php  

Robert,


I agree with your assessment that they should be resolved/restricted to “user” and “admin” in your example. Whether the wording in the spec reflects that understanding, I’m not sure…





Thanks and best regards,


Scott Hudson
Senior Consultant
Comtech Services Inc.

303-232-7586









From: Robert D Anderson
Date: Friday, April 3, 2015 at 9:13 AM
To: " dita@lists.oasis-open.org "
Subject: [dita] Key scopes for subjectdef versus controlled attribute values





While working through action items about keys in the spec, I realized I'm still unclear on one thing about key scopes and subject schemes.

Assume that I have my taxonomy and controlled values in a subject scheme map. The map is pulled into my root map with the key scope set to "tax". The scheme is used to set up all my taxonomy subjects, and to set controlled values for @audience, @platform, and
@product.

I can use the <subjectref> element to reference subjects. In this case I think it's clear that I should include the scope, because these keys resolve just as any other keys:
<subjectref keyref="tax.myproduct"/>

I'm not clear what we determined for attribute values. Assume the subject scheme defines the keys "user" and "admin", then restricts @audience to just those values. Looking at the subject scheme in isolation, it appears I'm restricting @audience to the literal
values "user" and "admin", which are also key names.

The question is - in the broader context of the root map, where I've put my subject scheme into the key scope "tax", what values are valid for @audience? In topics referenced from my map, is @audience restricted to "user" and "admin", or is it restricted to
"tax.user" and "tax.admin"? I think we decided it's the former because doing otherwise will be difficult (if not impossible) to manage. But, I feel we've gone around on these issues enough that I need to double check before moving forward.

Thanks -

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ )