HOCON Syntax Reference

This article describes the HOCON configuration syntax.

The configuration syntax for StreamBase is Human-Optimized Configuration Object Notation (HOCON). HOCON is a superset of JavaScript Object Notation (JSON), enhanced for readability. The specification for HOCON syntax is found here. Features in HOCON that are unchanged from JSON are described here.

StreamBase® extends standard HOCON in several ways, including:

Further differences between standard HOCON format and configuration file syntax are described in passing below.

Refer to the following terms when using HOCON syntax:

StreamBase configuration files must have a suffix of .conf. The basename of the file can be any valid name supported by the underlying operating system. There is no special significance associated with the file name; that is, configuration files can be named anything that reminds you of their contents.

Certain configuration file types are generated by StreamBase Studio with conventional names, such as node.conf. These file names are not required, but are suggested starting points.

It is a best practice using the last element of the type name as the basename, or an abbreviation of the last element. This allows a configuration file's contents to be known by their names, without opening the file. For example, a configuration file named sbengine.conf tells you at a glance that it contains a configuration of type com.tibco.ep.streambase.configuration.sbengine. The file app.conf contains a configuration of type com.tibco.ep.dtm.configuration.application.

Configuration files are loaded in alphabetic order by file name. You may need to name a collection of configuration files so that, for example, a defined name for a security realm is loaded before that realm's name is referenced in other configuration files.

A configuration file's character encoding can be UTF-8, UTF-16, or UTF-32 as defined by the JSON specification.

Every configuration file must contain header lines that specify the configuration type, name, and version of the file, which are all string values. The header lines are traditionally placed as the first three lines at the top of each StreamBase HOCON file, but this is a convention, and is not enforced.

Traditionally following the header lines, specify a configuration envelope in which all configuration specifications are contained. The configuration specifications allowed within the configuration envelope is defined by the configuration type specified in the header lines.

The supported configuration types are:

As in standard JSON and standard HOCON, any text between // or # and the next newline is considered a comment and is ignored (unless the // or # is inside a quoted string).

Prior to StreamBase 10.3.0, substitution variables commented AND inside a quoted string were ignored. Starting with 10.3.0 they are no longer ignored.

Per the standard HOCON specification, the \ escape character is used to escape the next character in the file. In all cases, except one, the escape character is significant and must follow the standard HOCON parsing rules.

The one exception is that escape characters in front of substitution variable definitions are ignored. For example:

configuration = 
{
    name = \${value}
}

The above is processed as the following, with the escape character stripped:

configuration = 
{
    name = ${value}
}

To escape the $ character that starts a substitution variable definition, use three backslashes:

configuration = 
{
    name = \\\${value}
}

The above is processed as the following, with the substitution variable escaped:

configuration = 
{
    name = \${value}
}

The values in configuration objects follow the standard HOCON syntax, including support for unit formatting (for example: ms, bytes, MB, and so on). The complete list of the standard supported unit formatting can be found here.

The supported date formats for date fields are:

Example:

//   Date value with timezone
//
dateValue = "1970-01-30T12:34:00"

//
//    Date value with milliseconds
//
dateValue = "1970-01-30T12:34:00.100"

//
//   Time-only date value
//
dateValue = "12:34:56"

HOCON configuration files can be embedded in another configuration file. The following example shows a complete node configuration file defined by its header lines at the top, that embeds an entire sbclientapilistener configuration file starting just below the fragmentIdentifier property.

The embedded configuration file is bounded by a pair of triple quotes (""") within a pair of square brackets.

name = "NodeDeployment"
version = "1.0"
type = "com.tibco.ep.dtm.configuration.node"
configuration = {
  NodeDeploy = {
    nodes = {
      "B.sbuser" = {
        engines = {
          engine1 = {
            fragmentIdentifier = "com.example.sample_operator"
            configuration = 
            [
              """
              name = "myapilistenersettings"
              version = "1.0.0"
              type = "com.tibco.ep.streambase.configuration.sbclientapilistener"
              configuration = {
                ClientAPIListener = {
                  apiListenerAddress = {
                    portNumber = 10000
                  }
                }
              }
              """
            ]
          }
        }
      }
    }
  }
}

The HOCON Configuration File Editor is a validating HOCON editor that is aware of the structure that defines the HOCON syntax of StreamBase configuration files.

See HOCON Configuration File Editor for instructions on using the Editor.