7.2 Custom Objects
There will be cases where certain information exchanges can be improved by adding objects that are not specified nor reserved in this document; these objects are called Custom Objects. This section provides guidance and requirements for how producers can use Custom Objects and how consumers should interpret them in order to extend STIX in an interoperable manner.
7.2.1 Requirements
- Producers MAY include any number of Custom Objects in STIX documents.
- Custom Objects MUST support the Common Properties as defined in section 3.1.
- The definitions of these properties are the same as those defined in Common Properties and therefore those properties MUST NOT be used to represent the custom properties in the object.
- The type property in a Custom Object MUST be in ASCII and MUST only contain the characters a–z (lowercase ASCII), 0–9, and hyphen (-).
- The type property MUST NOT contain a hyphen (-) character immediately following another hyphen (-) character.
- Custom Object names MUST have a minimum length of 3 ASCII characters.
- Custom Object names MUST be no longer than 250 ASCII characters in length.
- The value of the type property in a Custom Object SHOULD start with “x-” followed by a source unique identifier (like a domain name with dots replaced by hyphens), a hyphen and then the name. For example, x-example-com-customobject.
- A Custom Object whose name is not prefixed with “x-” may be used in a future version of the specification with a different meaning. Therefore, if compatibility with future versions of this specification is required, the “x-” prefix MUST be used.
- The value of the id property in a Custom Object MUST use the same format as the identifier type, namely, [object-type]--[UUIDv4].
- Custom Objects SHOULD only be used when there is no existing STIX Object defined by the STIX specification that fulfils that need.
Examples
{
"type": "bundle",
"id": "bundle--f37aa79d-f5f5-4af7-874b-734d32c08c10",
"spec_version": "2.0",
"custom_objects": [
{
"type": "x-example-com-customobject",
"id": "x-example-com-customobject--4527e5de-8572-446a-a57a-706f15467461",
"created": "2016-08-01T00:00:00.000Z",
"modified": "2016-08-01T00:00:00.000Z",
"some_custom_stuff": 14,
"other_custom_stuff": "hello"
}
]
}