Rule format schemas

Understand rule format schemas

Akamai often modifies PAPI features, each time deploying a new internal version of the feature. By default, the Property Manager interface in Control Center uses the latest available feature versions and you may be prompted to upgrade your configuration. In the interest of stability, PAPI does not support this system of selective updates for each feature. Instead, PAPI's rule objects are simply versioned as a whole. These versions, which update infrequently, are known as rule formats.

PAPI provides rule format schema objects that define the features you may enable under a product. This section shows how to interpret a rule format and use it to validate a rule tree or research available features.

The schema's relevant content is nested within the outer object's definitions member, which is empty in this example:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "rules": {
            "$ref": "#/definitions/toprule"
        }
    },
    "required": [ "rules" ],
    "definitions": {
    }
}

The top level of the schema specifies only that the rule tree must feature a rules member, specified indirectly within a large definitions section that this example doesn't display. The toprule itself specifies an object, which needs a name. While these specify the object's basic structure, the definition's catalog member contains available features, separately within the behaviors and criteria sub-trees. Each of those object's keys list supported features, and the values define their components.

📘
The features specified in the rule format represent all the behaviors and criteria the product supports, not necessarily those currently enabled for your account. Each product specifies a baseline set, with other more specialized features enabled with add-on modules, as discussed in key concepts and terms. To determine the set of features currently available on your account, saving a property that specifies them returns an error that notifies you otherwise.

This example shows a typical behavior definition for caching, along with its component options, some of whose data types are referenced elsewhere within the schema.

"caching": {
    "type": "object",
    "properties": {
        "name": {
            "enum": [ "caching" ]
        },
        "uuid": {
            "type": "string"
        },
        "options": {
            "type": "object",
            "properties": {
                "behavior": {
                    "default": "max-age",
                    "enum": [ "max-age", "no-store", "bypass-cache", "both", "cc", "expires" ]
                },
                "mustRevalidate": {
                    "default": "off",
                    "enum": [ "off", "on" ]
                },
                "ttl": {
                    "$ref": "#/definitions/catalog/option_types/duration"
                },
                "defaultTtl": {
                    "$ref": "#/definitions/catalog/option_types/duration"
                }
            }
        }
    }
}

Understand the limitations of the rule format's available data. While each option's basic data type is specified, additional validation logic isn't necessarily available within the schema, and may be implemented as part of the API's back end. The rule format also doesn't represent dependencies among the options. For example, many behaviors feature a high-level enabled switch. When disabled, the API typically ignores any other specified option. When enabled, there may be other contextual dependencies among the options. The behavior and criteria reference references detail most of these dependencies.

Rule formats often specify only minimal validation criteria. For example, the rule format's option_types section describes custom data formats, such as this example representing a CP code object with a required id member:

"cpCode": {
    "type": "object",
    "properties": {
        "id": {
            "type": "number"
        }
    },
    "required": [ "id" ]
},

The rule format doesn't specify the name member that also typically appears within a cpcode object. It doesn't specify what happens if you omit the name, or supply other members unknown to the API's back end. The back end may behave slightly differently over time, even if you freeze the API's set of features.

Check the following links for more information related to rule formats:

If you want more details about the underlying features that are applied as part of a property's rule tree, run List rule formats to get available versions for each feature set, and Get a rule format's schema to validate a rule tree against a specific rule format's supported features.
To control which rule format is assigned to a property, see Freeze a rule tree's feature set and Update rules to a newer set of features, both of which are based on the operations that read and write rule trees. See Update client settings to set the default rule format for new properties.
If you want to apply a common set of customized XML metadata to more than one property, see the Custom behaviors and Custom overrides interfaces.

Freeze a feature set for a rule tree

PAPI tracks rule formats in a database keyed by rule format version date strings. These reference rule format schema objects, which specify the full set of behaviors and criteria available for a given product and the set of modules it may enable, as well as their allowed options and option values.

This section describes a specific use for the Update a rule tree operation. You can assign the most recent dated rule format to freeze the set of features in a rule tree. Otherwise, if you assign the latest rule format to your rule tree, features update automatically to their most recent version. This may abruptly result in errors if JSON objects your rules specify no longer comply with the most recent feature's set of requirements.

New properties' rule trees are assigned whatever rule format you specify as a default client setting, or else the most recent dated rule format version available.

👍
As best practice, assign the most recent dated rule format in any API driven workflow.

To confirm your rule tree is already frozen, and freeze it if necessary:

Run Get a rule tree and store the URL you use to get it.
If the rule tree's top-level ruleFormat member is a dated version, the rule tree is already frozen and you don't need to proceed. If the value for the member is latest, continue with this procedure.
Run List rule formats and store the most recent dated rule format version string.
Build a custom MIME type string using this template: application/vnd.akamai.papirules.vYYYY-MM-DD+json, where vYYYY-MM-DD is the variable ruleFormat version string.
PUT the rule tree to the same URL you got it from, adding the custom MIME type to the request as a Content-Type header.

See also Update rules to a newer set of features for steps to update a rule tree to a more recent rule format. If the set of features you include in your rule tree doesn't conform to the associated rule format schema, the response includes errors that may prevent you from activating the property.

Update rules to a newer set of features

This section describes a specific use for the Get a property rule tree operation. Use this procedure to update the set of features assigned to your rule format. This also modifies the rule tree to implement most required syntax changes, such as changes to option names and enum values. You can't use this approach to assign an older rule format. In this procedure, the initial GET operation specifies a MIME type that converts the rule tree, after which you PUT the converted object to write it back.

List rule formats and store a more recent ruleFormat version to which you want to update the rule tree.
Build a custom MIME type string using this template, application/vnd.akamai.papirules.vYYYY-MM-DD+json, where vYYYY-MM-DD is the variable ruleFormat version.
Get a rule tree, adding an Accept header that specifies the custom MIME type.
Confirm the response object's top-level ruleFormat reflects the desired version.
PUT the converted rule tree to the same URL you got it from, adding a Content-Type header that specifies the same custom MIME type.

This represents the formal update path to increment versions of deployed features.

🚧
For better stability, don't assign a rule format of latest, as that doesn't modify your rule tree to smoothly upgrade to any emerging changes to features. The latest rule format is instead likely to produce unexpected errors over time.

Updating to a more recent rule format modifies the rule tree to accommodate renamed options, renamed enumeration values, and two-state enums retyped as boolean. Other values may not be able to convert, such as string numerics retyped as actual numerics, or if an updated behavior features a new required option or different validation criteria. If this occurs, the PUT response's rule tree object includes errors that help you refine the updated rule tree, as detailed in the Errors section.