-
Notifications
You must be signed in to change notification settings - Fork 21
Proposal: Allow Multiple Descriptions
- Status: Accepted
- Closed: March 23, 2015
- Issue: #186
Multiple community members have expressed a need for STIX to be able to support the specification of multiple Description instances on constructs that support providing Descriptions. The primary driver provided for this has been the need to specify differing Descriptions with different data markings. It has also been mentioned as potentially relevant to support internationalization.
Challenge: How to enable providing of Descriptions for constructs with differing markings (e.g. different levels of classification)?
Proposed Solution: Increase cardinality for all fields of StructuredTextType (all Description fields, all Short_Description fields, incident:Description_Of_Effect, and incident:Business_Function_Or_Role) from 0..1 to 0..Many. While Description is the field identified in this urgent change request, the same issues are likely to be applicable to other fields of StructuredTextType.
- Backwards Compatibility: While this change would technically be backward compatible from a language perspective, it would likely have a direct impact on all current implementations that to-date assume only a single Description will be present.
- Location of Change: This change would need to be made at the element instance level of the schema rather than the type level meaning that it would cause a ripple of small, identical changes throughout the schemas.
- Internationalization: This could also potentially help support StructuredTextType fields in different languages. Supporting this additional use case however, would require more time for additional thinking in regards to any other structure needed and would leave the issue only partly addressed as there are many other textual fields of other than just StructuredTextType (e.g. String) for which internationalization is a concern. In the interests of time and appropriate consistency, it is proposed that the issue of internationalization be considered out of scope for the multiple descriptions issue and be pursued by the community going forward.
Challenge: How to specify a marking for a particular Description instance for a given construct with multiple Descriptions?
Proposed Solution: Add @id attribute to StructuredTextType. This allows the controlled structures in markings to select individual Description elements via a simple XPath @id attribute selector.
Challenge: How to specify intended ordering (including specifying which instance should be considered "default") of multiple Descriptions for display or for processing, including in situations where only one Description is supported?
Proposed Solution: Add an @ordinality to Description structure along with clear guidance that @ordinality values cannot be duplicated within a set of multiple Descriptions on a single construct and that the Description with the lowest @ordinality value should be considered "default".
<xs:complexType name="StructuredTextType">
<xs:annotation>
<xs:documentation>The StructuredTextType is a type representing
a generalized structure for capturing structured or unstructured
textual information such as descriptions of things.</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="id" type="xs:QName" use="optional">
<xs:annotation>
<xs:documentation>Specifies a globally unique identifier for
this Description.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name=“ordinality" type=“xs:positiveInteger" use="optional">
<xs:annotation>
<xs:documentation>Specifies the intended order position of this construct
instance (e.g. Description) within a set of potentially multiple peer
construct instances. If only a single construct instance is
present its ordinality can be assumed to be 1. If multiple
construct instances are present, the ordinality field should
be specified with unique values for each instance.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="structuring_format" type="xs:string" use="optional">
<xs:annotation>
<xs:documentation>Used to indicate a particular structuring format
(e.g., HTML5) used within an instance of StructuredTextType. Note
that if the markup tags used by this format would be interpreted
as XML information (such as the bracket-based tags of HTML) the
text area should be enclosed in a CDATA section to prevent the
markup from interferring with XML validation of the STIX document.
If this attribute is absent, the implication is that no markup is
being used.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType><xs:element name="Construct”>
<xs:complexType>
<xs:sequence>
<xs:element name="Description" type=“StructuredTextType"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>Simple single instance:
<stix:Indicator>
<!-- @ordinality="1" is default -->
<indicator:Description>This is a description</Description>
<!-- Other content here -->
</stix:Indicator>Multiple instance marked differently:
<stix:Indicator>
<indicator:Description id="example:Description-2e20c5b2-56fa-46cd-9662-8f199c69d2c9"
ordinality="1">This is paragraph 1</Description>
<indicator:Description id="example:Description-970ebd99-3d50-4a44-8ef7-aa012a0c4a52"
ordinality="2">This is paragraph 2</Description>
<indicator:Description id="example:Description-41146bf6-4604-421e-83f6-a70b8edd0565"
ordinality="3">This is paragraph 3</Description>
<!-- Other content here -->
<indicator:Handling>
<marking:Marking>
<!-- Mark the indicator as a whole as TLP:GREEN -->
<marking:Controlled_Structure>
../../../descendant-or-self::node()
</marking:Controlled_Structure>
<marking:Marking_Structure xsi:type="tlp:TLPMarkingStructureType"
tlp:color="GREEN" />
</marking:Marking>
<marking:Marking>
<!-- Mark the third paragraph as TLP:RED (which per STIX TLP
extension rules overrides the GREEN) -->
<marking:Controlled_Structure>
../../../stix:Indicator/indicator:Description[
@id="example:Description-41146bf6-4604-421e-83f6-a70b8edd0565"]
</marking:Controlled_Structure>
<marking:Marking_Structure xsi:type="tlp:TLPMarkingStructureType"
tlp:color="RED" />
</marking:Marking>
</stix:Handling>
</stix:Indicator>The above would be backward compatible for any existing 1.1.1 content as long as the consuming system assumed that @ordinality="1" for the single Description and made no assumptions about @id.
- Should this change be included in STIX 1.2?
- Is the suggested solution the best way to implement this for 1.2?
Feedback can be sent to the public STIX discussion list (make sure to join first), as a public comment on the github issue for this proposal or sent privately to the core STIX team at [email protected].