STIX 2.x documentation is available here. This site contains archived STIX 1.x documentation. STIX is now maintained by the OASIS CTI TC.
Many locations in STIX use controlled vocabularies as a mechanism to provide a defined list of values to use by default but also to allow users to define their own vocabularies or even use values outside of any vocabulary.
Using a value from the default vocabulary
You should use the default STIX vocabulary whenever possible in order to assure the greatest level of compatibility with other STIX users. To do so, simply set the xsi:type to the type for the default vocabulary and use a value as defined in that vocabulary. In the Python APIs, simply setting the value of the field to a value from that vocabulary will accomplish this.
You can find the xsi:type to use by looking in the documentation for the field you’re working with.
If you want to set the field to custom values and either don’t want to or can’t define a vocabulary ahead of time you can also set a value outside of any vocabulary. To do this, omit the xsi:type and set the text of the field to your custom value. In the Python APIs, create a new instance of VocabString from the stix.common.vocabs package and set the field to that.
Using a value from a custom vocabulary that is not defined as a custom STIX vocabulary
Often a sharing community or product will have a defined vocabulary they want to use but that vocabulary doesn’t align completely with the STIX default vocabulary. One way to accomplish this is to set the vocab_name and vocab_reference fields on the vocabulary field to indicate the vocabulary name and a URL that defines that vocabulary. In the Python APIs, instantiate a new VocabString with the custom value and set these fields on that.
fromstix.common.vocabsimportVocabStringvs=VocabString("MyCustomValue")vs.vocab_name="MyVocabName"#Contains a simple name to identify the vocabulary
vs.vocab_reference="http://myvocabname.example.com/SomeKindOfReferenceInformation"#Contains a reference item for the vocabulary
Using a value from a custom vocabulary that is defined as a custom STIX vocabulary
One down side of the above approach is that the values from the vocabulary are not validated. To allow for validation and a more formal description of the vocabulary, you can also define your own vocabulary ahead of time, similar to how the STIX team did so with the default vocabularies. To use this vocabulary, define it in schema and import that schema. Then, set the xsi:type to the type for your vocabulary. In the Python APIs, you’ll need to create a new class that extends from the ControlledVocabulary class and then at use time import that class and set the value to a new instance.