This document details the current methodology for determining whether a new revision will require a major version change, minor version change, or a version update, and how version information is represented and conveyed in the STIX Language.
The version number is formatted as:
Major.Minor.Update. The Update value may be omitted if it is 0.
Major Version — A major release is for adding features that require breaking backward compatibility with previous versions or represent fundamental changes to concepts. For a major release, the MAJOR component is incremented by one and the MINOR and UPDATE components are set to zero.
Minor Version — A minor release is for adding features that do not break backward compatibility with previous versions and for fixing bugs that may or may not break backwards compatibility. For a minor release, the MINOR component is incremented by one and the UPDATE component is set to zero.
Update Version — An update release may only be initiated to address critical defects that affect usability. Fixes may break backward compatibility if necessary. New functionality outside of what was intended in the previous MAJOR.MINOR release is not permitted. However, once an update release is agreed to, other non-critical fixes and clarifications may be addressed. When an update version change is made, the UPDATE component is incremented by one.
A particular release of the STIX Language (i.e., a specific version) pins the following:
In all cases, the XML namespace of an XML file includes the major version of that file. The XML namespace of a schema does not change under a Minor or an Update revision.
The STIX Core (
stix_common.xsd schemas) is always versioned in lock-step with the STIX Language. These files always have the same version as each other, and always have the same version as the STIX Language overall.
STIX Components are versioned independently of each other and independently of the STIX Language. Each version of the STIX Language indicates the list of supported Component schemas and the version for each of these Component schemas.
Tools that support a given version of the STIX Language are not required to support every type of STIX Component associated with that version of the STIX Language. However, for STIX Components that such tools do support, they must support the specific version of those Components associated with the supported version of the STIX Language. Tools may support older and/or newer versions of those same Components, but are not required to do so.
Note that, in STIX, components are considered extension points. As such, authors can utilize custom STIX Components other than those associated by a given release. However, this is considered to be a customized use of the STIX Language and compatibility is not guaranteed. Any use of a STIX Component version other than the specific version associated with a particular STIX Language release (i.e., a Component that is either an earlier version or a later version) is considered a customized use of STIX with the associated compatibility risks.
The STIX Vocabularies (in
stix_default_vocabularies.xsd) represent a set of default controlled vocabularies for use in STIX content. These vocabularies are broken out from the STIX Core/Component schemas to support customized extension and replacement of these vocabularies in content. Nonetheless, it is expected that most STIX authors will utilize the provided default vocabularies, and most tools that parse STIX should support those vocabularies where appropriate.
Any individual STIX vocabulary may be revised at any time, including between releases of the STIX Language. Authors and tools may begin utilizing this new vocabulary immediately.
To facilitate this, each version of a given controlled vocabulary (an XML SimpleType that resolves to an enumeration) is assigned a different version number. An individual vocabulary has a Major and Minor version number, but no Update number. For a vocabulary:
The version of the vocabulary is appended to the end of the name of the XML type that defines that vocabulary. Specifically, all types used to define a controlled vocabulary end in “-Major.Minor” where Major is the vocabulary’s Major number and Minor is the vocabulary’s Minor number. For example, version 1.0 of the Package Intent controlled vocabulary has the name PackageIntentVocab-1.0 and uses the PackageIntentEnum-1.0 enumeration. If new terms are added to this vocabulary, new types are created with the names of PackageIntentVocab -1.1 and PackageIntentEnum -1.1. If terms are deleted from the vocabulary, new types are created with the names of PackageIntentVocab -2.0 and PackageIntentEnum -2.0.
Every time any of the vocabularies in stix_default_vocabularies.xsd changes, the Update number of the schema’s @version attribute increments. The Major and Minor numbers of the schema’s version only change in conjunction with a Major or Minor revision to the STIX Language, and always match the Major and Minor numbers of the STIX Language in which it is used. A change to the Update number in the STIX Language does not impact the version of the stix_default_vocabularies.xsd schema.
Within a single Major release of the STIX Language, the stix_default_vocabularies.xsd contains every version of all of the controlled vocabularies that were defined. Thus, if the Package Intent controlled vocabulary went through version 1.0, 1.1, 2.0, and 2.1 all within version 1.* of the STIX Language, the stix_default_vocabularies.xsd schema contains all of the following XML types:
This means that a single version of
stix_default_vocabularies.xsd can be used to validate content that uses any version of a supported vocabulary up to and including the latest version of the given vocabulary present in the schema file within any Major version of STIX. In the case of a Major revision of STIX, older versions of vocabularies may be removed. However, the individual version numbers of vocabularies do not reset when this happens. I.e., if the Package Intent controlled vocabulary was on revision 2.1 (PackageIntentVocab-2.1 and PackageIntentEnum-2.1) and then there was a major revision to STIX to 3.0, the new version of the stix_default_vocabularies.xsd is assigned version 3.0 and might not contain types for previous versions of the Package Intent vocabulary, but the Package Intent vocabulary is still in version 2.1, and is represented by the types PackageIntentVocab -2.1 and PackageIntentEnum -2.1.
For a given version of the STIX Language, use of any version of a controlled vocabulary within a stix_default_vocabularies.xsd associated with that Language version. That is, authors may use version 1.2 of a particular vocabulary and be considered compliant with the STIX Language even if the latest version of that vocabulary for that Language version is version 1.4. However, authors should be aware that there may be differences in support for various versions of the STIX default vocabularies even between tools that support the same version of the STIX Language.
As noted earlier, controlled vocabularies are considered extension points and the default vocabularies can be extended or replaced by authors. However, in doing this the author is considered to be utilizing a customized version of the STIX Language and might encounter compatibility issues.
The STIX Extensions schemas are used for structured representation of data using externally defined schemas. For example, there is an extension schema that allows for the structured representation of undefined vulnerabilities using ICASI’s Common Vulnerability Reporting Format (CVRF) schema. Rather than importing these schemas directly into STIX, these external schemas are captured in STIX Extension schemas, which can be hooked into STIX at certain defined extension points.
The STIX Extension schemas represent the recommended way of structuring certain information using existing, externally defined XML schemas (following STIX’s design objective of “reuse rather than reinvent”). However, no author is ever required to use any of the recommended extension schemas nor are tools required to process those extension schemas. No use case of STIX requires the use of extension schemas, although authors may wish to use them to achieve greater expressivity in certain situations.
Each STIX Extension schema is versioned independently. Releases of revised extension schemas usually, but not always, coincide with a revision of the STIX Language. A given release of the STIX Language contains recommendations as to the STIX Extension schemas to use for certain purposes. This recommendation includes the Major, Minor, and Update numbers for each of those extension schemas.