The format for a configuration resource is [1] JSON (JavaScript Object Notation) and it must be UTF-8 encoded. An example configuration resource has the following structure:

{
    // Resource Format Version
    ":configurator:resource-version" : 1,

    // First Configuration
    "pid.a": {
           "key": "val",
           "some_number": 123
        },

    // Second Configuration
    "pid.b": {
           "a_boolean": true
        }
}

Comments in the form of [2] JSMin (The JavaScript Minifier) comments are supported, that is, any text on the same line after // is ignored and any text between /* */ is ignored.

Configuration resources provide a set of configuration dictionaries each with a PID key to target a specific PID in the Configuration Admin Service and zero or more configuration values for this PID. Keys starting with the prefix :configurator: contain information about the resource or instructions for the Configurator and therefore are not interpreted as PIDs containing configurations. If a key contains an invalid PID, this entry is ignored and the Configurator should log an error with the Log Service if available.

The Configurator defines the following special keys on the resource level.

Configuration resources provide a set of configuration dictionaries each with a PID key to target a specific PID in the Configuration Admin Service.

Factory configurations can be addressed using the factory PID and a name by starting with the factory PID, appending a tilde ('~' \u007e), and then appending the name. This ensures a well-known name for the factory configuration instance. The PID for such a configuration is exactly this key. The Configurator must use the getFactoryConfiguration methods on Configuration Admin Service to create or obtain configurations with the given factory PID and name.

Targeted PIDs are supported through the configuration resource. In the case of single configurations, the full targeted PID is used as the key. For factory configurations, the key is assembled by chaining the targeted factory PID, a tilde ('~' \u007e), and the name.

The Configurator obtains all configurations with the location value of ? to allow the configurations to be received by multiple bundles.

The Configurator uses the Configuration.updateIfDifferent method on the configuration object to avoid any volatility in the system if the configuration applied has not been changed.

A configuration dictionary for the Configuration Admin Service is specified through a JSON object in the configuration resource. It is introduced using the PID as the key. The value is a JSON object containing the configuration dictionary.

The Configurator removes any comments and all properties where the key is starting with the special prefix :configurator: from the configuration object before converting it to a configuration dictionary that is provided to the Configuration Admin Service.

The Configurator defines special keys that can be used within the configuration object.

Configuration values support data types as specified with the Filter Syntax in the OSGi Core Specification. Configuration resources are specified in JSON, which supports a more basic set of data types. The following table describes how values are converted from JSON to configuration values.

If a specific data type is required for a configuration, the Configurator can be instructed to convert the JSON value to a given data type. The target type can be specified by adding a colon : and the desired data type to the property name. Supported data types are String, Integer, Long, Float, Double, Byte, Short, Character and Boolean. Additionally arrays of Scalar or primitive types are supported and Collection of scalar. The primitive types that can be specified for arrays are: int, long, float, double, byte, short, char, boolean. For Collection the Configurator picks a suitable implementation that preserves order. Both bare Collection as well as typed collections that use the generics style notation are supported. If a requested conversion cannot be performed, then the configuration is not processed and the Configurator implementation should log an error.

An example configuration resource with typed data:

{
  "my.pid": {      
    "port:Integer" : 300,
    "an_int_array:int[]" : [2, 3, 4],
    "an_Integer_collection:Collection<Integer>" : [2, 3, 4],
    "complex": {
      "a" : 1,
      "b" : "two"
    }
  }
}

The above configuration gets converted to a configuration dictionary with the following entries (in pseudo Java language):

Integer port = 300;
int[]   an_int_array = {2, 3, 4};
Collection<Integer> an_Integer_collection = {2, 3, 4};
String  complex = "{ \"1\" : 1, \"b\" : \"two\" }"

As an alternative of specifying data types for the Configurator, consumers of configuration can convert the configuration values to the desired type by using the OSGi Converter see Converter Specification. A convenient way to convert a configuration map to the desired data types is by using the Converter to convert it to an annotation instance or by using a Declarative Services component property type.

{
  "my.config": {
    "security.enabled": true,
    "public.key:binary" : "/OSGI-INF/files/mykey.pub"
  }
}

The order in which the Configurator processes bundles is not defined. To control which configurations are in effect configuration ranking can be used. Configuration ranking is similar to service ranking; it is an integer which defaults to 0. Configurations with a higher ranking are preferred over configurations with a lower ranking. When multiple configurations arrive over time it is possible that the Configurator changes the effective configuration if a higher ranked configuration arrives later. The design of the Configurator is such that the effective set of configurations once the system stabilizes is consistent, regardless of the order in which bundles are installed and processed.

The ranking of a configuration can be specified by adding the :configurator:ranking property. The value of this property is converted to an Integer as defined by the Converter specification. If the value cannot be converted a warning should be logged. When multiple configurations for a given PID have the same ranking the bundle providing the configuration with the lowest bundle ID is preferred. If multiple configurations for the same PID with the same ranking are specified within a single bundle, the first one encountered is used.

The following example shows two bundles with a configuration resource containing a configuration for the same PID:

Resource in Bundle A:
{
  "my.pid": {      
    "port:Integer" : 300,
    ":configurator:ranking" : 100
  }
}

Resource in Bundle B:
{
  "my.pid": {      
    "port:Integer" : 100,
    ":configurator:ranking" : 10
  }
}

Bundle A contains the configuration with the higher ranking. Therefore, regardless of the installation order of bundle A and B, the configuration from Bundle A will be in effect after both bundles are installed and processed by the Configurator.

In an IT operations scenario configurations are often updated by a systems administrator to suit the deployments requirements. In such scenarios it may be undesirable to have these modifications overwritten by a software update which includes a configuration resource. In other cases, bundles with configuration resources are used to enforce best practices or compliance with corporate guidelines, which should replace any previous manual settings. This specification defines policies to define the overwrite behavior of the Configurator when configurations have been set or modified by another entity.

Configuration policies are set by specifying the :configurator:policy property. Accepted values are default and force. This policy defines the behavior when a configuration to be applied was set by another entity in the system, or if it was modified by someone from the values set by the Configurator. The default value for this property is default. If the specified value is invalid an error is logged and the default value is used.

The Configurator must keep track of configuration change count values to identify configurations that were changed by other entities or administrators.

When a bundle that provides configuration resources is uninstalled, the Configurator removes any configurations that it has provided on behalf of this bundle from the system. Before it removes a configuration the Configurator checks with the Configuration Admin Service whether the configuration it has provided has been changed by another entity. If the configuration has not been changed by another entity it is removed. If it has been changed then whether the configuration is removed depends on the value of the configurator:policy property:

When a configuration is removed the Configurator checks whether another, lower ranked, configuration resource is available. If present the Configurator sets this configuration.

The following examples explain the two policy options. In the first example Bundle A contains a configuration for the PID my.pid without specifying the policy. In this case the default policy is used:

{
  "my.pid": {      
    "port:Integer" : 300
  }
}

The following actions demonstrate the behavior of the default policy:

In the second example Bundle A contains a configuration for the PID my.pid this time with the overwrite policy set to force.

{
  "my.pid": {      
    "port:Integer" : 300,
    ":configurator:policy" : "force"
  }
}

The following actions demonstrate the behavior of the force policy:

The Configurator manages configurations on behalf of the bundle containing the configuration resources. Therefore the Configurator needs to have the ConfigurationPermission[*,org.osgi.service.cm.ConfigurationPermission.CONFIGURE].

Every bundle has the implicit right to receive and configure configurations with a location that exactly matches the Bundle's location or that is null. Therefore the extendee does not need to special permissions.

The Configurator needs ServicePermission[<interface>, GET] for the Coordinator service.

The extendee needs ServicePermission[<interface>, GET] for the Configuration Admin Service.

The Configurator does get the Configuration Admin Service on behalf of the extendee. Therefore the extendee needs to be included in permission checks for getting the Configuration Admin Service. The Configurator needs to perform the required calls to ensure the extendee has the necessary permission to get the Configuration Admin Service.

If binaries are used, the Configurator needs to have read/write/delete permission to the configured directory to store the binaries.

A bundle using a binary referenced from a configuration needs to have read permission to correct sub directory of the configured binary directory. The subdirectory is named after the PID of the configuration.

By default binaries are stored in the bundle data are of the Configurator. While this works without Java security enabled, permission configuration for the extendees gets challenging as the location of the bundle data area is only known at runtime. Therefore with Java security enabled, the directory holding the binaries should be configured to allow permission configuration for the extendees.

The Configurator implementation bundle must provide the osgi.extender capability with name osgi.configurator with the version of this specification:

Provide-Capability: osgi.extender;
     osgi.extender="osgi.configurator";
     version:Version="1.0"

This capability must follow the rules defined for the osgi.extender Namespace.

Bundles providing configuration resources must require the osgi.extender capability to opt in to being processed by the Configurator. The default location for configuration resources is in OSGI-INF/configurator. A bundle can specify alternate locations for configuration resources through the configurations attribute. The value of this attribute is of type String or List<String>. Each value represents a path inside the bundle. This path is always relative to the root of the bundle and may start with a slash /. A path value of / indicates the root of the bundle. The Configurator uses Bundle.findEntries to find all resources with the .json extension in this location. Sub directories are not considered. If the configuration attribute specifies multiple paths, these are visited in the order specified. Duplicate paths are ignored. Paths that do not exist in the bundle are logged as an error and skipped. Resources in a single directory are processed in alphabetical order. For example:

Require-Capability: osgi.extender;
     filter:="(&(osgi.extender=osgi.configurator)
             (version>=1.0)(!(version>=2.0)))";
     configurations="resources/configs"

To simplify the creation of this requirement the RequireConfigurator annotation can be used. This annotation allows the configurations attribute to be defined is a value other than the default is needed.

@RequireConfigurator("resources/configs")