Prepare the Site Configuration JSON
Introduction
The site configuration JSON defines exactly how the CDN processes client requests and delivers content. This article describes the JSON format and illustrates how to build the configuration JSON that defines the site configuration.
Alternatively, you can use the Media Delivery user interface to build a site configuration. Learn More.
The configuration JSON encapsulates standard Streaming Video Technology Alliance (SVTA) metadata objects. Qwilt CDN supports a subset of the SVTA standard. Our development roadmap includes plans to gradually add support for additional configuration objects.
References
These documents are essential to understanding the Streaming Video Technology Alliance (SVTA) standard.
Open Caching Configuration Interface: Part 1 – Overview and Architecture
Open Caching Configuration Interface: Part 2 – Extensions to the CDNi Metadata Object Model
Open Caching Configuration Interface: Part 3 – Publishing Layer APIs
JSON Format Overview
While configuring a site for Media Delivery can be as simple as defining the traffic type, a single host, and a single origin, a typical use case may require configuring multiple site hosts, multiple origins, paths, processing and delivery rules, and access control lists (ACLs).
The minimum requirements for a valid JSON format are as follows:
- A hostIndex object that includes a metadata array specifying the site traffic-type.
- A hosts array defining at least one host.
- Each host must define an origin. The origin configuration may be defined at the host level, or at the site level and inherited by the hosts.
The following example shows the most basic valid site configuration. It uses the metadata object to configure the site for vod traffic, defines a single host (www.mysite.com) and includes a host-level origin configuration for that host (www.exampleOrigin.com):
{
"hostIndex": {
"metadata": [
{
"generic-metadata-type": "MI.TrafficType",
"generic-metadata-value": {
"traffic-type": "vod"
}
}
],
"hosts": [
{
"host": "www.mysite.com",
"host-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.SourceMetadataExtended",
"generic-metadata-value": {
"sources": [
{
"protocol": "https/1.1",
"endpoints": [
"www.exampleOrigin.com"
]
}
]
}
}
],
"paths": []
}
}
]
}
}
This example shows a valid configuration where the origin is defined at the site-level and automatically inherited by the host:
{
"hostIndex": {
"metadata": [
{
"generic-metadata-type": "MI.SourceMetadataExtended",
"generic-metadata-value": {
"sources": [
{
"protocol": "https/1.1",
"endpoints": [
"www.exampleOrigin.com"
]
}
]
}
},
{
"generic-metadata-type": "MI.TrafficType",
"generic-metadata-value": {
"traffic-type": "vod"
}
}
],
"hosts": [
{
"host": "www.mysite.com",
"host-metadata": {
"metadata": [],
"paths": []
}
}
]
}
}
Structural Components
Let's walk through each of the main structural components of the JSON configuration: Site, Host, and Path.
SITE LEVEL METADATA
The metadata object in the hostIndex is used for site-level configurations:
-
Use it to configure the settings that apply globally to the site and cannot be customized for individual hosts or paths: Traffic Type and IPv6 Client Connection Support.
-
You can also configure origins, processing behaviors, and ACLs at the site level. These settings apply across all site hosts and paths by default but can be customized for individual hosts or paths.
See the full list of supported configuration objects.
Note that the site level configuration feature is not supported by the Media Site Configuration UI.
HOSTS
The hosts object must configure at least one host and may configure multiple hosts.
-
Each host must define an origin. The origin configuration may be defined at the host level, or at the site level and inherited by the host.
-
A host may configure processing behaviors and ACLs.
-
A host configuration may include one or more paths to define custom processing parameters for specific content.
-
A host configuration may specify the HTTP Protocols available to the client.
-
A host may be configured to support Wildcard Subdomain.
-
A host may be configured for Low Latency Live traffic.
PATHS
A paths object is nested within each host object. As paths are optional, it may be empty or contain one or more path objects.
A path object is used to define custom CDN behavior based on the URI path of an incoming request. When a path match occurs, the rules configured for the path are applied.
-
A path may configure processing behaviors and ACLs.
-
A path may configure an alternate origin.
-
A path may be configured for Low Latency Live traffic.
CONFIGURATION OBJECTS
The metadata, host, and path objects may each contain a nested array of the SVTA metadata objects (generic-metadata-type and generic-metadata-value pairs) that define origins, processing behaviors, and ACLs.
See the full list of supported configuration objects.
Inheritance
A host either inherits the site-level configurations or overrides them with its own configurations.
-
Any distinct rules configured at the site level are inherited by the hosts.
For example, if a Cache Time to Live rule is defined at the site level, and a Compression rule is defined at the host level, both rules are applied to the host.
-
If the same rule is configured at both the site and host levels, the host-level configuration takes precedence.
For example, if a Cache Time to Live rule is set at both the site and host levels, the host-level Cache Time to Live configuration overrides the one defined at the site level.
-
The inheritance logic for Processing Stage Rules (On Client Request, On Client Response, On Origin Request) considers them as a single entity. If any Processing Stage rule is configured at the host level, it overrides all processing stage rules configured at the site level.
For example, if the site-level configuration includes an On Client Request and an On Client Response rule, and the host configuration includes an On Origin Request rule, then only the host-level On Origin Request rule is applied to the host.
Path Inheritance
Paths follow the same inheritance model: a path inherits all rules applied to its parent host including both host-level configurations and inherited site-level configurations. If the path defines additional rules, they are applied in addition to the inherited ones. However, if the path defines a configuration already set at the host or site level, the path-level setting overrides the inherited version.
Traffic-Type and IPv6 Client Connection Support cannot be customized for individual hosts or paths and should be configured at the site level only.
Qwilt Private Features
In addition to standard SVTA metadata objects (typically prefixed with MI.), and in accordance with the SVTA specification, Qwilt uses private features (prefixed with QW.) to provide extended functionality. These private features allow for more granular control over specific CDN behaviors.
There are two valid ways to represent Qwilt private features within the configuration JSON: Named Private Feature Format (Recommended), and Private Feature List Format.
Named Private Feature Format (Recommended)
This format uses a specific generic-metadata-type that directly identifies the feature, incorporating the organization (Qwilt) and the feature identifier (QW.<FeatureName>) into the object name.
{
"generic-metadata-type": "MI.PrivateFeature.Qwilt.QW.<FeatureName>",
"generic-metadata-value": { ... feature-specific configuration ... }
}
For example:
{
"generic-metadata-type": "MI.PrivateFeature.Qwilt.QW.HttpRangeRequests",
"generic-metadata-value": {
"enable": false
}
}
Private Feature List Format
This format uses the standard MI.PrivateFeatureList metadata type, where private features are defined within an array under the features key of the generic-metadata-value.
{
"generic-metadata-type": "MI.PrivateFeatureList",
"generic-metadata-value": {
"features": [
{
"feature-oid": "Qwilt",
"feature-type": "QW.<FeatureName>",
"feature-value": { ... feature-specific configuration ... }
}
// ... potentially other features ...
]
}
}
For example:
{
"generic-metadata-type": "MI.PrivateFeatureList",
"generic-metadata-value": {
"features": [
{
"feature-oid": "Qwilt",
"feature-type": "QW.HttpRangeRequests",
"feature-value": {
"enable": false
}
}
]
}
}
While both formats are supported and can be processed, it is strongly recommended to use the Named Private Feature format (MI.PrivateFeature.Qwilt.QW.<FeatureName>) when creating or modifying configurations.
Reason for Recommendation: The standard SVTA inheritance model determines overrides based on the generic-metadata-type. When using the MI.PrivateFeatureList format, any definition of this metadata type at the host or path level, even if it includes only one feature, will override entire MI.PrivateFeatureList defined at the parent level (site or host). As a result, private features configured at higher levels may be unintentionally excluded from the effective configuration of child entities.
In contrast, the Named Private Feature format assigns a unique generic-metadata-type to each private feature. This allows features to be inherited or selectively overridden individually, without impacting other private features.
When you use the QC Services UI to modify an existing site configuration and save it as a new version, any private features in the MI.PrivateFeatureList are automatically converted to the named private feature format. Similarly, if you use the UI to add a new rule that corresponds to a Qwilt private feature, to a new or existing site configuration, it is automatically configured in the named private feature format.
Remember to publish the new version to activate it in production.
Quick Start Template
You can use this example JSON as a template for configuring a basic but fully functional Media Delivery site.
Remember, a valid Media Delivery site configuration must define a traffic type and at least one host and origin host. (Note: Traffic type is required only for Media Delivery configurations and does not apply to Site Delivery.)
Media Delivery Site Configuration Template
{
"hostIndex": {
"metadata": [
{
"generic-metadata-type": "MI.TrafficType",
"generic-metadata-value": {
"traffic-type": "vod"
}
}
],
"hosts": [
{
"host": "www.mySite.com",
"host-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.SourceMetadataExtended",
"generic-metadata-value": {
"sources": [
{
"protocol": "https/1.1",
"endpoints": [
"www.exampleOrigin.com"
]
}
]
}
}
],
"paths": []
}
}
]
},
"changeDescription": "Example basic site configuration."
}
To use this file as a basis for configuring your own site, replace the example hostname and origin host server values with real values, and set the relevant traffic type.
The two generic-metadata-type/generic-metadata-value pairs define the traffic type and the origin:
-
MI.TrafficType - The metadata type for a traffic type object. In this example, the site is configured to deliver vod content. Supported traffic types are software-downloads, live, and vod. Note that a site is configured for a single traffic type. The traffic type must be the same for all hosts and paths. We recommend configuring it on the site level, where it is applied to all hosts and paths. Learn about the traffic type configuration..
-
MI.SourceMetadataExtended - The metadata type for an origin configuration object. The origin configuration parameters (protocol and hostname) are specified in the generic-metadata-value field. In this example, a single origin is configured. It is also possible to configure a failover origin, a round robin origin, and to set origin authentication parameters, header overrides, timeout, retry and other values. Learn about origin configuration.
You must add the ,"changeDescription":”<any text>" line to the end of the JSON file, before the last bracket, as in the example. Without this line, the configuration JSON is not valid, and the Add a Site Configuration function will not succeed.
Beyond the Basics
Next, we'll illustrate how to enhance the basic site configuration with a failover origin configuration and a path configuration.
Configure a Failover Origin
Here, we'll configure a failover origin, specifying the failover conditions (failover-errors) and the failover host in subsequent entries within the sources array.
In the following example:
-
The origin host is primary-origin.example.com
-
An
origin-hostheader override is set. -
The specified failover origin is www.failover.origin.example.com.
-
The rule is configured so that a request is redirected to the failover origin if either of the following conditions are met:
-
A response is not returned by the origin host (primary-origin.example.com) within 1200 milliseconds.
-
Any of the specified errors occur (401, 403, 500, 502, 503, 504)
{
"generic-metadata-type": "MI.SourceMetadataExtended",
"generic-metadata-value": {
"sources": [
{
"protocol": "https/1.1",
"endpoints": [
"primary-origin.example.com"
],
"origin-host": "content.example.com",
// Override Host Header
"connection-control": {
"connection-setup-timeout-ms": 1200
},
"failover-errors": [
"401",
"403",
"500",
"502",
"503",
"504"
]
},
{
"protocol": "https/1.1",
"endpoints": [
"failover.origin.example.com"
],
"origin-host": "content.example.com"
// Override Host Header
}
]
}
}
-
If you compare this origin configuration to the single host configuration illustrated in the Basic Site Configuration section, you'll notice that the MI.SourceMetadataExtended metadata type is the same, but the generic-metadata-value is updated with the failover origin parameters.
Learn more about origin configuration.
Configure a Path
Paths are used to define the CDN behavior based on the URI path of an incoming request. A path component must be nested within a host component, as illustrated in the JSON Format Overview section of this article.
When a path match occurs, the rules configured for the path are applied. Rules can be used to influence origin selection, cache configuration, and access control for a specific portion of your site.
For example, you could:
-
Define custom caching rules for your video protocol manifests (e.g. your .m3u8 files).
-
Create a custom ACL for your site's API.
-
Map a particular section of the site to an alternate origin that integrates content with ads.
In addition, a path inherits or overrides the processing behaviors defined by the parent host.
Specify the URI path by defining a path pattern or a path regex.
Use the QW.PathMatchMethod Qwilt private feature to indicate the path matching method (path-pattern or path-regex).
The following example uses the path-pattern match method to add a path to the site configuration. The purpose of this path is to enable configuring special processing parameters for requests for manifests (.m3u8 files).
{
"paths": [
{
"path-pattern": {
"pattern": "*.m3u8",
"case-sensitive": false
},
"path-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.PrivateFeature.Qwilt.QW.PathMatchMethod",
"generic-metadata-value": {
"method": "path-pattern"
}
}
// ... other path-specific metadata rules ...
]
}
}
]
}
The following example uses the path-regex match method to add a path to the site configuration. The regex expression says that a request URL that ends with either ".mp4" or ".ts" is a match. The purpose of this path is to enable configuring special processing parameters for .mp4 video files or .ts streams. Note that the expression defines a non-capturing group.
{
"paths": [
{
"path-pattern": {
"pattern": "\\.(?:mp4|ts)$",
"case-sensitive": false
},
"path-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.PrivateFeature.Qwilt.QW.PathMatchMethod",
"generic-metadata-value": {
"method": "path-regex"
}
}
// ... other path-specific metadata rules ...
]
}
}
]
}
If you'd like to use these examples to add paths to your own site configuration, replace the "pattern" value with your own path and set the relevant match type method (path-regex or path-pattern).
Path Order
The CDN evaluates the request URI against each path in the list in the order in which they are defined in the configuration. Only rules in the first path that matches the requested URI are applied. It is important to arrange the path list in a logical way to achieve the desired outcome.
In case of overlapping paths, where multiple paths match specific content items, the subpath should be positioned first in the list. For example, if you want to apply certain rules to all the .m3u8 files except for those in the xyz path, organize the paths as follows:
Path 1: /xyz/*.m3u8
Path 2: *.m3u8
This arrangement ensures that requests for .m3u8 files within the /xyz/ path adhere to the rules specified by path /xyz/*.m3u8, rather than those specified by path *.m3u8. Requests for other .m3u8 files follow the rules of the *.m3u8 path.
This is an example of an illogical path order:
Path 1: /*.jpg
Path 2: /pathX/*.jpg
The processing parameters defined for the second path will never be applied because the path, /*.jpg encompasses the files in the path, /pathX/*.jpg
Note that this type of mistake will not generate a validation error.
If the goal is to apply distinct rules to files in /pathX/*.jpg, the order should be adjusted so that in the path list, the more specific path precedes the broader path:
Path 1: /pathX/*.jpg
Path 2: /*.jpg
Set Processing Rules
Media Delivery supports a set of SVTA configuration objects that define processing behavior such as cache control, content control, and security policies. Each one has its own generic-metadata-type. The articles under Supported Configuration Objects describe the SVTA metadata objects that are the components of the site configuration JSON, including copyable examples. You can further enhance your own initial site configuration by copying the relevant snippets and substituting your own values.
Origins and processing rules can be configured at the site, host, or path level.
Note that the rule section headings are the descriptive names, followed by the respective SVTA metadata object name in parentheses.
The full example configuration JSON at the end of this document incorporates some examples so that you can view them in the context of a full site configuration JSON.
Supported Configuration Objects
Explore the JSON Format
To become more familiar with the JSON format, we suggest using the Media Delivery user interface to build and save (but not publish) test configurations. When you use the UI to configure a service, the JSON is automatically created. You can then preview the JSON from within the UI.
To view the JSON format from within the CDN configuration UI:
-
Navigate to the My Media Sites page and select or create a site.
-
In the Media Site Configuration tab, select the
JSON API Formatlink of the relevant version. These links are available for the selected and published versions on the main page:
To view the JSON format of a different saved version, under Versions & History, open the Versions List, select the three dots menu next to the version you want to view, and select JSON:
-
Play around with the different configuration features in the UI and see how they affect the JSON format.
When you are creating the JSON format for actual use, you must add this line to the end of the JSON file, inside the last bracket: ,"changeDescription":"<any text>"
For example:
,"changeDescription":"Updated by VRB. Added caching rules."
Example Site Configuration JSON
{
"hostIndex": {
"metadata": [
{
"generic-metadata-type": "MI.SourceMetadataExtended",
"generic-metadata-value": {
"sources": [
{
"protocol": "https/1.1",
"endpoints": [
"originexample.com"
]
}
]
}
},
{
"generic-metadata-type": "MI.TrafficType",
"generic-metadata-value": {
"traffic-type": "vod"
}
},
{
"generic-metadata-type": "MI.CrossoriginPolicy",
"generic-metadata-value": {
"allow-methods": [
"PUT",
"DELETE",
"GET",
"OPTIONS",
"HEAD"
],
"allow-origin": {
"allow-list": [
{
"pattern": "*"
}
],
"wildcard-return": false
}
}
}
],
"hosts": [
{
"host": "examplehost1.com",
"host-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.ProtocolACL",
"generic-metadata-value": {
"protocol-acl": [
{
"action": "allow",
"protocols": [
"https/1.1",
"http/2"
]
}
]
}
},
{
"generic-metadata-type": "MI.CachePolicy",
"generic-metadata-value": {
"internal": "31536000",
"external": "31536000",
"force-internal": true,
"force-external": true
}
},
{
"generic-metadata-type": "MI.ComputedCacheKey",
"generic-metadata-value": {
"expression": "match_replace(req.uri.path, '(\\\\/qsig=[^\\\\/]+)(\\\\/.*)', '$2')"
}
},
{
"generic-metadata-type": "MI.NegativeCachePolicy",
"generic-metadata-value": {
"cache-policy": {
"internal": "10",
"external": "10",
"force-internal": true,
"force-external": true
},
"error-codes": [
"404"
]
}
},
{
"generic-metadata-type": "MI.PrivateFeature.Qwilt.QW.DebugHeaderRule",
"generic-metadata-value": {
"request-header-name": "X-OC-Debug",
"request-header-value": "123ABC"
}
},
{
"generic-metadata-type": "MI.PrivateFeature.Qwilt.QW.QwiltUrlsigning",
"generic-metadata-value": {
"enforce": true,
"insertion-method": "first-path-segment",
"keySet": 30
}
},
],
"paths": [
{
"path-pattern": {
"pattern": "*.mp4",
"case-sensitive": false
},
"path-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.ProcessingStages",
"generic-metadata-value": {
"client-response": [
{
"stage-metadata": [
{
"response-transform": {
"headers": {
"replace": [
{
"value": "video/mp4",
"name": "content-type"
}
]
}
}
}
]
}
]
}
}
]
}
},
{
"path-pattern": {
"pattern": "*.pdf",
"case-sensitive": false
},
"path-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.ProcessingStages",
"generic-metadata-value": {
"client-response": [
{
"stage-metadata": [
{
"response-transform": {
"headers": {
"replace": [
{
"value": "application/pdf",
"name": "content-type"
}
]
}
}
}
]
}
]
}
}
]
}
},
{
"path-pattern": {
"pattern": "*.css",
"case-sensitive": false
},
"path-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.ProcessingStages",
"generic-metadata-value": {
"client-response": [
{
"stage-metadata": [
{
"response-transform": {
"headers": {
"replace": [
{
"value": "text/css",
"name": "content-type"
}
]
}
}
}
]
}
]
}
}
]
}
}
]
}
},
{
"host": "examplehost2.com",
"host-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.ProtocolACL",
"generic-metadata-value": {
"protocol-acl": [
{
"action": "allow",
"protocols": [
"https/1.1",
"http/2"
]
}
]
}
},
{
"generic-metadata-type": "MI.CachePolicy",
"generic-metadata-value": {
"internal": "no-cache",
"external": "no-cache",
"force-internal": true,
"force-external": true
}
},
{
"generic-metadata-type": "MI.NegativeCachePolicy",
"generic-metadata-value": {
"cache-policy": {
"internal": "3",
"external": "3",
"force-internal": true,
"force-external": true
},
"error-codes": [
"404"
]
}
},
{
"generic-metadata-type": "MI.PrivateFeature.Qwilt.QW.HttpMethodsAcl",
"generic-metadata-value": {
"allowed-methods": [
"POST",
"PUT",
"DELETE",
"GET",
"OPTIONS",
"HEAD"
],
"allow-client-payload": false
}
}
],
"paths": [
{
"path-pattern": {
"pattern": "*.css",
"case-sensitive": false
},
"path-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.ProcessingStages",
"generic-metadata-value": {
"client-response": [
{
"stage-metadata": [
{
"response-transform": {
"headers": {
"replace": [
{
"value": "text/css",
"name": "content-type"
}
]
}
}
}
]
}
]
}
}
]
}
},
{
"path-pattern": {
"pattern": "*.mp4",
"case-sensitive": false
},
"path-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.ProcessingStages",
"generic-metadata-value": {
"client-response": [
{
"stage-metadata": [
{
"response-transform": {
"headers": {
"replace": [
{
"value": "video/mp4",
"name": "content-type"
}
]
}
}
}
]
}
]
}
}
]
}
},
{
"path-pattern": {
"pattern": "*.pdf",
"case-sensitive": false
},
"path-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.ProcessingStages",
"generic-metadata-value": {
"client-response": [
{
"stage-metadata": [
{
"response-transform": {
"headers": {
"replace": [
{
"value": "application/pdf",
"name": "content-type"
}
]
}
}
}
]
}
]
}
}
]
}
},
{
"path-pattern": {
"pattern": "*.html",
"case-sensitive": false
},
"path-metadata": {
"metadata": [
{
"generic-metadata-type": "MI.ProcessingStages",
"generic-metadata-value": {
"client-response": [
{
"stage-metadata": [
{
"response-transform": {
"headers": {
"replace": [
{
"value": "text/html",
"name": "content-type"
}
]
}
}
}
]
}
]
}
}
]
}
}
]
}
}
]
},
"changeDescription": "Media Delivery site configuration example."
}