targeting.json

{
  "$id": "https://flagd.dev/schema/v0/targeting.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "flagd Targeting",
  "description": "Defines targeting logic for flagd; a extension of JSONLogic, including purpose-built feature-flagging operations.",
  "type": "object",
  "properties": {
    "targeting": {
      "$ref": "#/definitions/targeting"
    }
  },
  "definitions": {
    "targeting": {
      "title": "Targeting",
      "description": "An expression returning a value which is coerced to a string to be used as a targeting key, or null (to fall back to defaultVariant). If targeting returns a value which is not a variant key, it's considered an error.",
      "anyOf": [
        {
          "$comment": "we need this to support empty targeting",
          "type": "object",
          "additionalProperties": false,
          "properties": {}
        },
        {
          "$ref": "#/definitions/anyRule"
        }
      ]
    },
    "primitive": {
      "oneOf": [
        {
          "description": "When returned from rules, a null value \"exits\", the targeting, and the \"defaultValue\" is returned, with the reason indicating the targeting did not match.",
          "type": "null"
        },
        {
          "description": "When returned from rules, booleans are converted to strings (\"true\"/\"false\"), and used to as keys to retrieve the associated value from the \"variants\" object. Be sure that the returned string is present as a key in the variants!",
          "type": "boolean"
        },
        {
          "description": "When returned from rules, the behavior of numbers is not defined.",
          "type": "number"
        },
        {
          "description": "When returned from rules, strings are used to as keys to retrieve the associated value from the \"variants\" object. Be sure that the returned string is present as a key in the variants!.",
          "type": "string"
        },
        {
          "description": "When returned from rules, strings are used to as keys to retrieve the associated value from the \"variants\" object. Be sure that the returned string is present as a key in the variants!.",
          "type": "array"
        }
      ]
    },
    "varRule": {
      "title": "Var Operation",
      "description": "Retrieve data from the provided data object.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "var": {
          "anyOf": [
            {
              "type": "string",
              "description": "flagd automatically injects \"$flagd.timestamp\" (unix epoch) and \"$flagd.flagKey\" (the key of the flag in evaluation) into the context.",
              "pattern": "^\\$flagd\\.((timestamp)|(flagKey))$"
            },
            {
              "not": {
                "$comment": "this is a negated (not) match of \"$flagd.{some-key}\", which is faster and more compatible that a negative lookahead regex",
                "type": "string",
                "description": "flagd automatically injects \"$flagd.timestamp\" (unix epoch) and \"$flagd.flagKey\" (the key of the flag in evaluation) into the context.",
                "pattern": "^\\$flagd\\..*$"
              }
            },
            {
              "type": "array",
              "$comment": "this is to support the form of var with a default... there seems to be a bug here, where ajv gives a warning (not an error) because maxItems doesn't equal the number of entries in items, though this is valid in this case",
              "minItems": 1,
              "items": [
                {
                  "type": "string"
                }
              ],
              "additionalItems": {
                "anyOf": [
                  {
                    "type": "null"
                  },
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "string"
                  },
                  {
                    "type": "number"
                  }
                ]
              }
            }
          ]
        }
      }
    },
    "missingRule": {
      "title": "Missing Operation",
      "description": "Takes an array of data keys to search for (same format as var). Returns an array of any keys that are missing from the data object, or an empty array.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "missing": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "missingSomeRule": {
      "title": "Missing-Some Operation",
      "description": "Takes a minimum number of data keys that are required, and an array of keys to search for (same format as var or missing). Returns an empty array if the minimum is met, or an array of the missing keys otherwise.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "missing_some": {
          "minItems": 2,
          "maxItems": 2,
          "type": "array",
          "items": [
            {
              "type": "number"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          ]
        }
      }
    },
    "binaryOrTernaryOp": {
      "type": "array",
      "minItems": 2,
      "maxItems": 3,
      "items": {
        "$ref": "#/definitions/args"
      }
    },
    "binaryOrTernaryRule": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "substr": {
          "title": "Substring Operation",
          "description": "Get a portion of a string. Give a positive start position to return everything beginning at that index. Give a negative start position to work backwards from the end of the string, then return everything. Give a positive length to express how many characters to return.",
          "$ref": "#/definitions/binaryOrTernaryOp"
        },
        "<": {
          "title": "Less-Than/Between Operation. Can be used to test that one value is between two others.",
          "$ref": "#/definitions/binaryOrTernaryOp"
        },
        "<=": {
          "title": "Less-Than-Or-Equal-To/Between Operation. Can be used to test that one value is between two others.",
          "$ref": "#/definitions/binaryOrTernaryOp"
        }
      }
    },
    "binaryOp": {
      "type": "array",
      "minItems": 2,
      "maxItems": 2,
      "items": {
        "$ref": "#/definitions/args"
      }
    },
    "binaryRule": {
      "title": "Binary Operation",
      "description": "Any primitive JSONLogic operation with 2 operands.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "if": {
          "title": "If Operator",
          "description": "The if statement takes 1 or more arguments: a condition (\"if\"), what to do if its true (\"then\", optional, defaults to returning true), and what to do if its false (\"else\", optional, defaults to returning false). Note that the else condition can be used as an else-if statement by adding additional arguments.",
          "$ref": "#/definitions/variadicOp"
        },
        "==": {
          "title": "Lose Equality Operation",
          "description": "Tests equality, with type coercion. Requires two arguments.",
          "$ref": "#/definitions/binaryOp"
        },
        "===": {
          "title": "Strict Equality Operation",
          "description": "Tests strict equality. Requires two arguments.",
          "$ref": "#/definitions/binaryOp"
        },
        "!=": {
          "title": "Lose Inequality Operation",
          "description": "Tests not-equal, with type coercion.",
          "$ref": "#/definitions/binaryOp"
        },
        "!==": {
          "title": "Strict Inequality Operation",
          "description": "Tests strict not-equal.",
          "$ref": "#/definitions/binaryOp"
        },
        ">": {
          "title": "Greater-Than Operation",
          "$ref": "#/definitions/binaryOp"
        },
        ">=": {
          "title": "Greater-Than-Or-Equal-To Operation",
          "$ref": "#/definitions/binaryOp"
        },
        "%": {
          "title": "Modulo Operation",
          "description": "Finds the remainder after the first argument is divided by the second argument.",
          "$ref": "#/definitions/binaryOp"
        },
        "/": {
          "title": "Division Operation",
          "$ref": "#/definitions/binaryOp"
        },
        "map": {
          "title": "Map Operation",
          "description": "Perform an action on every member of an array. Note, that inside the logic being used to map, var operations are relative to the array element being worked on.",
          "$ref": "#/definitions/binaryOp"
        },
        "filter": {
          "title": "Filter Operation",
          "description": "Keep only elements of the array that pass a test. Note, that inside the logic being used to filter, var operations are relative to the array element being worked on.",
          "$ref": "#/definitions/binaryOp"
        },
        "all": {
          "title": "All Operation",
          "description": "Perform a test on each member of that array, returning true if all pass. Inside the test code, var operations are relative to the array element being tested.",
          "$ref": "#/definitions/binaryOp"
        },
        "none": {
          "title": "None Operation",
          "description": "Perform a test on each member of that array, returning true if none pass. Inside the test code, var operations are relative to the array element being tested.",
          "$ref": "#/definitions/binaryOp"
        },
        "some": {
          "title": "Some Operation",
          "description": "Perform a test on each member of that array, returning true if some pass. Inside the test code, var operations are relative to the array element being tested.",
          "$ref": "#/definitions/binaryOp"
        },
        "in": {
          "title": "In Operation",
          "description": "If the second argument is an array, tests that the first argument is a member of the array.",
          "$ref": "#/definitions/binaryOp"
        }
      }
    },
    "reduceRule": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "reduce": {
          "title": "Reduce Operation",
          "description": "Combine all the elements in an array into a single value, like adding up a list of numbers. Note, that inside the logic being used to reduce, var operations only have access to an object with a \"current\" and a \"accumulator\".",
          "type": "array",
          "minItems": 3,
          "maxItems": 3,
          "items": {
            "$ref": "#/definitions/args"
          }
        }
      }
    },
    "associativeOp": {
      "type": "array",
      "minItems": 2,
      "items": {
        "$ref": "#/definitions/args"
      }
    },
    "associativeRule": {
      "title": "Mathematically Associative Operation",
      "description": "Operation applicable to 2 or more parameters.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "*": {
          "title": "Multiplication Operation",
          "description": "Multiplication; associative, will accept and unlimited amount of arguments.",
          "$ref": "#/definitions/associativeOp"
        }
      }
    },
    "unaryOp": {
      "anyOf": [
        {
          "type": "array",
          "minItems": 1,
          "maxItems": 1,
          "items": {
            "$ref": "#/definitions/args"
          }
        },
        {
          "$ref": "#/definitions/args"
        }
      ]
    },
    "unaryRule": {
      "title": "Unary Operation",
      "description": "Any primitive JSONLogic operation with 1 operands.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "!": {
          "title": "Negation Operation",
          "description": "Logical negation (“not”). Takes just one argument.",
          "$ref": "#/definitions/unaryOp"
        },
        "!!": {
          "title": "Double Negation Operation",
          "description": "Double negation, or 'cast to a boolean'. Takes a single argument.",
          "$ref": "#/definitions/unaryOp"
        }
      }
    },
    "variadicOp": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/definitions/args"
      }
    },
    "variadicRule": {
      "$comment": "note < and <= can be used with up to 3 ops (between)",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "or": {
          "title": "Or Operation",
          "description": "Simple boolean test, with 1 or more arguments. At a more sophisticated level, \"or\" returns the first truthy argument, or the last argument.",
          "$ref": "#/definitions/variadicOp"
        },
        "and": {
          "title": "",
          "description": "Simple boolean test, with 1 or more arguments. At a more sophisticated level, \"and\" returns the first falsy argument, or the last argument.",
          "$ref": "#/definitions/variadicOp"
        },
        "+": {
          "title": "Addition Operation",
          "description": "Addition; associative, will accept and unlimited amount of arguments.",
          "$ref": "#/definitions/variadicOp"
        },
        "-": {
          "title": "Subtraction Operation",
          "$ref": "#/definitions/variadicOp"
        },
        "max": {
          "title": "Maximum Operation",
          "description": "Return the maximum from a list of values.",
          "$ref": "#/definitions/variadicOp"
        },
        "min": {
          "title": "Minimum Operation",
          "description": "Return the minimum from a list of values.",
          "$ref": "#/definitions/variadicOp"
        },
        "merge": {
          "title": "Merge Operation",
          "description": "Takes one or more arrays, and merges them into one array. If arguments aren't arrays, they get cast to arrays.",
          "$ref": "#/definitions/variadicOp"
        },
        "cat": {
          "title": "Concatenate Operation",
          "description": "Concatenate all the supplied arguments. Note that this is not a join or implode operation, there is no “glue” string.",
          "$ref": "#/definitions/variadicOp"
        }
      }
    },
    "stringCompareArg": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "$ref": "#/definitions/anyRule"
        }
      ]
    },
    "stringCompareArgs": {
      "type": "array",
      "minItems": 2,
      "maxItems": 2,
      "items": {
        "$ref": "#/definitions/stringCompareArg"
      }
    },
    "stringCompareRule": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "starts_with": {
          "title": "Starts-With Operation",
          "description": "The string attribute starts with the specified string value.",
          "$ref": "#/definitions/stringCompareArgs"
        },
        "ends_with": {
          "title": "Ends-With Operation",
          "description": "The string attribute ends with the specified string value.",
          "$ref": "#/definitions/stringCompareArgs"
        }
      }
    },
    "semVerString": {
      "title": "Semantic Version String",
      "description": "A string representing a valid semantic version expression as per https://semver.org/.",
      "type": "string",
      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
    },
    "ruleSemVer": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "sem_ver": {
          "title": "Semantic Version Operation",
          "description": "Attribute matches a semantic version condition. Accepts \"npm-style\" range specifiers: \"=\", \"!=\", \">\", \"<\", \">=\", \"<=\", \"~\" (match minor version), \"^\" (match major version).",
          "type": "array",
          "minItems": 3,
          "maxItems": 3,
          "items": [
            {
              "oneOf": [
                {
                  "$ref": "#/definitions/semVerString"
                },
                {
                  "$ref": "#/definitions/varRule"
                }
              ]
            },
            {
              "description": "Range specifiers: \"=\", \"!=\", \">\", \"<\", \">=\", \"<=\", \"~\" (match minor version), \"^\" (match major version).",
              "enum": [
                "=",
                "!=",
                ">",
                "<",
                ">=",
                "<=",
                "~",
                "^"
              ]
            },
            {
              "oneOf": [
                {
                  "$ref": "#/definitions/semVerString"
                },
                {
                  "$ref": "#/definitions/varRule"
                }
              ]
            }
          ]
        }
      }
    },
    "fractionalWeightArg": {
      "$comment": "if we remove the \"sum to 100\" restriction, update the descriptions below!",
      "description": "Distribution for all possible variants, with their associated weighting out of 100.",
      "type": "array",
      "minItems": 1,
      "maxItems": 2,
      "items": [
        {
          "description": "If this bucket is randomly selected, this string is used to as a key to retrieve the associated value from the \"variants\" object.",
          "type": "string"
        },
        {
          "description": "Weighted distribution for this variant key (must sum to 100).",
          "type": "number"
        }
      ]
    },
    "fractionalOp": {
      "type": "array",
      "minItems": 3,
      "$comment": "there seems to be a bug here, where ajv gives a warning (not an error) because maxItems doesn't equal the number of entries in items, though this is valid in this case",
      "items": [
        {
          "description": "Bucketing value used in pseudorandom assignment; should be unique and stable for each subject of flag evaluation. Defaults to a concatenation of the flagKey and targetingKey.",
          "$ref": "#/definitions/anyRule"
        },
        {
          "$ref": "#/definitions/fractionalWeightArg"
        },
        {
          "$ref": "#/definitions/fractionalWeightArg"
        }
      ],
      "additionalItems": {
        "$ref": "#/definitions/fractionalWeightArg"
      }
    },
    "fractionalShorthandOp": {
      "type": "array",
      "minItems": 2,
      "items": {
        "$ref": "#/definitions/fractionalWeightArg"
      }
    },
    "fractionalRule": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "fractional": {
          "title": "Fractional Operation",
          "description": "Deterministic, pseudorandom fractional distribution.",
          "oneOf": [
            {
              "$ref": "#/definitions/fractionalOp"
            },
            {
              "$ref": "#/definitions/fractionalShorthandOp"
            }
          ]
        }
      }
    },
    "reference": {
      "additionalProperties": false,
      "type": "object",
      "$comment": "patternProperties here is a bit of a hack to prevent this definition from being dereferenced early.",
      "patternProperties": {
        "^\\$ref$": {
          "title": "Reference",
          "description": "A reference to another entity, used for $evaluators (shared rules).",
          "type": "string"
        }
      }
    },
    "args": {
      "oneOf": [
        {
          "$ref": "#/definitions/reference"
        },
        {
          "$ref": "#/definitions/anyRule"
        },
        {
          "$ref": "#/definitions/primitive"
        }
      ]
    },
    "anyRule": {
      "anyOf": [
        {
          "$ref": "#/definitions/varRule"
        },
        {
          "$ref": "#/definitions/missingRule"
        },
        {
          "$ref": "#/definitions/missingSomeRule"
        },
        {
          "$ref": "#/definitions/binaryRule"
        },
        {
          "$ref": "#/definitions/binaryOrTernaryRule"
        },
        {
          "$ref": "#/definitions/associativeRule"
        },
        {
          "$ref": "#/definitions/unaryRule"
        },
        {
          "$ref": "#/definitions/variadicRule"
        },
        {
          "$ref": "#/definitions/reduceRule"
        },
        {
          "$ref": "#/definitions/stringCompareRule"
        },
        {
          "$ref": "#/definitions/ruleSemVer"
        },
        {
          "$ref": "#/definitions/fractionalRule"
        }
      ]
    }
  }
}