specification.json

{
    "rules": [
        {
            "id": "Requirement 1.1.1",
            "machine_id": "requirement_1_1_1",
            "content": "The `API`, and any state it maintains SHOULD exist as a global singleton, even in cases wherein multiple versions of the `API` are present at runtime.",
            "RFC 2119 keyword": "SHOULD",
            "children": []
        },
        {
            "id": "Requirement 1.1.2",
            "machine_id": "requirement_1_1_2",
            "content": "The `API` MUST provide a function to set the global `provider` singleton, which accepts an API-conformant `provider` implementation.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 1.1.3",
            "machine_id": "requirement_1_1_3",
            "content": "The `API` MUST provide a function to add `hooks` which accepts one or more API-conformant `hooks`, and appends them to the collection of any previously added hooks. When new hooks are added, previously added hooks are not removed.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 1.1.4",
            "machine_id": "requirement_1_1_4",
            "content": "The API MUST provide a function for retrieving the metadata field of the configured `provider`.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 1.1.5",
            "machine_id": "requirement_1_1_5",
            "content": "The `API` MUST provide a function for creating a `client` which accepts the following options:  - name (optional): A logical string identifier for the client.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 1.1.6",
            "machine_id": "requirement_1_1_6",
            "content": "The client creation function MUST NOT throw, or otherwise abnormally terminate.",
            "RFC 2119 keyword": "MUST NOT",
            "children": []
        },
        {
            "id": "Requirement 1.2.1",
            "machine_id": "requirement_1_2_1",
            "content": "The client MUST provide a method to add `hooks` which accepts one or more API-conformant `hooks`, and appends them to the collection of any previously added hooks. When new hooks are added, previously added hooks are not removed.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 1.2.2",
            "machine_id": "requirement_1_2_2",
            "content": "The client interface MUST define a `metadata` member or accessor, containing an immutable `name` field or accessor of type string, which corresponds to the `name` value supplied during client creation.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 1.3.1",
            "machine_id": "requirement_1_3_1",
            "content": "The `client` MUST provide methods for typed flag evaluation, including boolean, numeric, string, and structure, with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required), `evaluation context` (optional), and `evaluation options` (optional), which returns the flag value.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Condition 1.3.2",
            "machine_id": "condition_1_3_2",
            "content": "The implementation language differentiates between floating-point numbers and integers.",
            "RFC 2119 keyword": null,
            "children": [
                {
                    "id": "Conditional Requirement 1.3.2.1",
                    "machine_id": "conditional_requirement_1_3_2_1",
                    "content": "The client SHOULD provide functions for floating-point numbers and integers, consistent with language idioms.",
                    "RFC 2119 keyword": "SHOULD",
                    "children": []
                }
            ]
        },
        {
            "id": "Requirement 1.3.3",
            "machine_id": "requirement_1_3_3",
            "content": "The `client` SHOULD guarantee the returned value of any typed flag evaluation method is of the expected type. If the value returned by the underlying provider implementation does not match the expected type, it's to be considered abnormal execution, and the supplied `default value` should be returned.",
            "RFC 2119 keyword": "SHOULD",
            "children": []
        },
        {
            "id": "Requirement 1.4.1",
            "machine_id": "requirement_1_4_1",
            "content": "The `client` MUST provide methods for detailed flag value evaluation with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required), `evaluation context` (optional), and `evaluation options` (optional), which returns an `evaluation details` structure.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 1.4.2",
            "machine_id": "requirement_1_4_2",
            "content": "The `evaluation details` structure's `value` field MUST contain the evaluated flag value.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Condition 1.4.3",
            "machine_id": "condition_1_4_3",
            "content": "The language supports generics (or an equivalent feature).",
            "RFC 2119 keyword": null,
            "children": [
                {
                    "id": "Conditional Requirement 1.4.3.1",
                    "machine_id": "conditional_requirement_1_4_3_1",
                    "content": "The `evaluation details` structure SHOULD accept a generic argument (or use an equivalent language feature) which indicates the type of the wrapped `value` field.",
                    "RFC 2119 keyword": "SHOULD",
                    "children": []
                }
            ]
        },
        {
            "id": "Requirement 1.4.4",
            "machine_id": "requirement_1_4_4",
            "content": "The `evaluation details` structure's `flag key` field MUST contain the `flag key` argument passed to the detailed flag evaluation method.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 1.4.5",
            "machine_id": "requirement_1_4_5",
            "content": "In cases of normal execution, the `evaluation details` structure's `variant` field MUST contain the value of the `variant` field in the `flag resolution` structure returned by the configured `provider`, if the field is set.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 1.4.6",
            "machine_id": "requirement_1_4_6",
            "content": "In cases of normal execution, the `evaluation details` structure's `reason` field MUST contain the value of the `reason` field in the `flag resolution` structure returned by the configured `provider`, if the field is set.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 1.4.7",
            "machine_id": "requirement_1_4_7",
            "content": "In cases of abnormal execution, the `evaluation details` structure's `error code` field MUST contain a string identifying an error occurred during flag evaluation and the nature of the error.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 1.4.8",
            "machine_id": "requirement_1_4_8",
            "content": "In cases of abnormal execution (network failure, unhandled error, etc) the `reason` field in the `evaluation details` SHOULD indicate an error.",
            "RFC 2119 keyword": "SHOULD",
            "children": []
        },
        {
            "id": "Requirement 1.4.9",
            "machine_id": "requirement_1_4_9",
            "content": "Methods, functions, or operations on the client MUST NOT throw exceptions, or otherwise abnormally terminate. Flag evaluation calls must always return the `default value` in the event of abnormal execution. Exceptions include functions or methods for the purposes for configuration or setup.",
            "RFC 2119 keyword": "MUST NOT",
            "children": []
        },
        {
            "id": "Requirement 1.4.10",
            "machine_id": "requirement_1_4_10",
            "content": "In the case of abnormal execution, the client SHOULD log an informative error message.",
            "RFC 2119 keyword": "SHOULD",
            "children": []
        },
        {
            "id": "Requirement 1.4.11",
            "machine_id": "requirement_1_4_11",
            "content": "The `client` SHOULD provide asynchronous or non-blocking mechanisms for flag evaluation.",
            "RFC 2119 keyword": "SHOULD",
            "children": []
        },
        {
            "id": "Requirement 1.5.1",
            "machine_id": "requirement_1_5_1",
            "content": "The `evaluation options` structure's `hooks` field denotes an ordered collection of hooks that the client MUST execute for the respective flag evaluation, in addition to those already configured.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 1.6.1",
            "machine_id": "requirement_1_6_1",
            "content": "The `client` SHOULD transform the `evaluation context` using the `provider's` `context transformer` function if one is defined, before passing the result of the transformation to the provider's flag resolution functions.",
            "RFC 2119 keyword": "SHOULD",
            "children": []
        },
        {
            "id": "Requirement 2.1",
            "machine_id": "requirement_2_1",
            "content": "The provider interface MUST define a `metadata` member or accessor, containing a `name` field or accessor of type string, which identifies the provider implementation.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 2.2",
            "machine_id": "requirement_2_2",
            "content": "The `feature provider` interface MUST define methods to resolve flag values, with parameters `flag key` (string, required), `default value` (boolean | number | string | structure, required), `evaluation context` (optional), and `evaluation options` (optional), which returns a `flag resolution` structure.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Condition 2.3",
            "machine_id": "condition_2_3",
            "content": "The implementing language type system differentiates between strings, numbers, booleans and structures.",
            "RFC 2119 keyword": null,
            "children": [
                {
                    "id": "Conditional Requirement 2.3.1",
                    "machine_id": "conditional_requirement_2_3_1",
                    "content": "The `feature provider` interface MUST define methods for typed flag resolution, including boolean, numeric, string, and structure.",
                    "RFC 2119 keyword": "MUST",
                    "children": []
                }
            ]
        },
        {
            "id": "Requirement 2.4",
            "machine_id": "requirement_2_4",
            "content": "In cases of normal execution, the `provider` MUST populate the `flag resolution` structure's `value` field with the resolved flag value.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 2.5",
            "machine_id": "requirement_2_5",
            "content": "In cases of normal execution, the `provider` SHOULD populate the `flag resolution` structure's `variant` field with a string identifier corresponding to the returned flag value.",
            "RFC 2119 keyword": "SHOULD",
            "children": []
        },
        {
            "id": "Requirement 2.6",
            "machine_id": "requirement_2_6",
            "content": "The `provider` SHOULD populate the `flag resolution` structure's `reason` field with a string indicating the semantic reason for the returned flag value.",
            "RFC 2119 keyword": "SHOULD",
            "children": []
        },
        {
            "id": "Requirement 2.7",
            "machine_id": "requirement_2_7",
            "content": "In cases of normal execution, the `provider` MUST NOT populate the `flag resolution` structure's `error code` field, or otherwise must populate it with a null or falsy value.",
            "RFC 2119 keyword": "MUST NOT",
            "children": []
        },
        {
            "id": "Requirement 2.8",
            "machine_id": "requirement_2_8",
            "content": "In cases of abnormal execution, the `provider` MUST indicate an error using the idioms of the implementation language, with an associated error code having possible values `\"PROVIDER_NOT_READY\"`, `\"FLAG_NOT_FOUND\"`, `\"PARSE_ERROR\"`, `\"TYPE_MISMATCH\"`, or `\"GENERAL\"`.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Condition 2.9",
            "machine_id": "condition_2_9",
            "content": "The implementation language supports generics (or an equivalent feature).",
            "RFC 2119 keyword": null,
            "children": [
                {
                    "id": "Conditional Requirement 2.9.1",
                    "machine_id": "conditional_requirement_2_9_1",
                    "content": "The `flag resolution` structure SHOULD accept a generic argument (or use an equivalent language feature) which indicates the type of the wrapped `value` field.",
                    "RFC 2119 keyword": "SHOULD",
                    "children": []
                }
            ]
        },
        {
            "id": "Requirement 2.10",
            "machine_id": "requirement_2_10",
            "content": "The provider interface MAY define a `context transformer` method or function, which can be optionally implemented in order to transform the `evaluation context` prior to flag value resolution.",
            "RFC 2119 keyword": "MAY",
            "children": []
        },
        {
            "id": "Condition 2.11",
            "machine_id": "condition_2_11",
            "content": "The implementation language supports generics (or an equivalent feature).",
            "RFC 2119 keyword": null,
            "children": [
                {
                    "id": "Conditional Requirement 2.11.1",
                    "machine_id": "conditional_requirement_2_11_1",
                    "content": "If the implementation includes a `context transformer`, the provider SHOULD accept a generic argument (or use an equivalent language feature) indicating the type of the transformed context.  If such type information is supplied, more accurate type information can be supplied in the flag resolution methods.",
                    "RFC 2119 keyword": "SHOULD",
                    "children": []
                }
            ]
        },
        {
            "id": "Requirement 3.1.1",
            "machine_id": "requirement_3_1_1",
            "content": "The `evaluation context` structure MUST define an optional `targeting key` field of type string, identifying the subject of the flag evaluation.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 3.1.2",
            "machine_id": "requirement_3_1_2",
            "content": "The evaluation context MUST support the inclusion of custom fields, having keys of type `string`, and values of type `boolean | string | number | datetime | structure`.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 3.2.1",
            "machine_id": "requirement_3_2_1",
            "content": "The API, Client and invocation MUST have a method for supplying `evaluation context`.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 3.2.2",
            "machine_id": "requirement_3_2_2",
            "content": "Evaluation context MUST be merged in the order: API (global) - client - invocation, with duplicate values being overwritten.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.1.1",
            "machine_id": "requirement_4_1_1",
            "content": "Hook context MUST provide: the `flag key`, `flag value type`, `evaluation context`, and the `default value`.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.1.2",
            "machine_id": "requirement_4_1_2",
            "content": "The `hook context` SHOULD provide: access to the `client metadata` and the `provider metadata` fields.",
            "RFC 2119 keyword": "SHOULD",
            "children": []
        },
        {
            "id": "Requirement 4.1.3",
            "machine_id": "requirement_4_1_3",
            "content": "The `flag key`, `flag type`, and `default value` properties MUST be immutable. If the language does not support immutability, the hook MUST NOT modify these properties.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.1.4",
            "machine_id": "requirement_4_1_4",
            "content": "The evaluation context MUST be mutable only within the `before` hook.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.2.1",
            "machine_id": "requirement_4_2_1",
            "content": "`hook hints` MUST be a structure supports definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number | datetime | structure`..",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Condition 4.2.2",
            "machine_id": "condition_4_2_2",
            "content": "The implementation language supports a mechanism for marking data as immutable.",
            "RFC 2119 keyword": null,
            "children": [
                {
                    "id": "Conditional Requirement 4.2.2.1",
                    "machine_id": "conditional_requirement_4_2_2_1",
                    "content": "Condition: `Hook hints` MUST be immutable.",
                    "RFC 2119 keyword": "MUST",
                    "children": []
                },
                {
                    "id": "Conditional Requirement 4.2.2.2",
                    "machine_id": "conditional_requirement_4_2_2_2",
                    "content": "Condition: The client `metadata` field in the `hook context` MUST be immutable.",
                    "RFC 2119 keyword": "MUST",
                    "children": []
                },
                {
                    "id": "Conditional Requirement 4.2.2.3",
                    "machine_id": "conditional_requirement_4_2_2_3",
                    "content": "Condition: The provider `metadata` field in the `hook context` MUST be immutable.",
                    "RFC 2119 keyword": "MUST",
                    "children": []
                }
            ]
        },
        {
            "id": "Requirement 4.3.1",
            "machine_id": "requirement_4_3_1",
            "content": "Hooks MUST specify at least one stage.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.3.2",
            "machine_id": "requirement_4_3_2",
            "content": "The `before` stage MUST run before flag resolution occurs. It accepts a `hook context` (required) and `hook hints` (optional) as parameters and returns either an `evaluation context` or nothing.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.3.3",
            "machine_id": "requirement_4_3_3",
            "content": "Any `evaluation context` returned from a `before` hook MUST be passed to subsequent `before` hooks (via `HookContext`).",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.3.4",
            "machine_id": "requirement_4_3_4",
            "content": "When `before` hooks have finished executing, any resulting `evaluation context` MUST be merged with the invocation `evaluation context` with the invocation `evaluation context` taking precedence in the case of any conflicts.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.3.5",
            "machine_id": "requirement_4_3_5",
            "content": "The `after` stage MUST run after flag resolution occurs. It accepts a `hook context` (required), `flag evaluation details` (required) and `hook hints` (optional). It has no return value.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.3.6",
            "machine_id": "requirement_4_3_6",
            "content": "The `error` hook MUST run when errors are encountered in the `before` stage, the `after` stage or during flag resolution. It accepts `hook context` (required), `exception` representing what went wrong (required), and `hook hints` (optional). It has no return value.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.3.7",
            "machine_id": "requirement_4_3_7",
            "content": "The `finally` hook MUST run after the `before`, `after`, and `error` stages. It accepts a `hook context` (required) and `hook hints` (optional). There is no return value.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Condition 4.3.8",
            "machine_id": "condition_4_3_8",
            "content": "`finally` is a reserved word in the language.",
            "RFC 2119 keyword": null,
            "children": [
                {
                    "id": "Conditional Requirement 4.3.8.1",
                    "machine_id": "conditional_requirement_4_3_8_1",
                    "content": "Instead of `finally`, `finallyAfter` SHOULD be used.",
                    "RFC 2119 keyword": "SHOULD",
                    "children": []
                }
            ]
        },
        {
            "id": "Requirement 4.4.1",
            "machine_id": "requirement_4_4_1",
            "content": "The API, Client and invocation MUST have a method for registering hooks which accepts `flag evaluation options`",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.4.2",
            "machine_id": "requirement_4_4_2",
            "content": "Hooks MUST be evaluated in the following order:  - before: API, Client, Invocation - after: Invocation, Client, API - error (if applicable): Invocation, Client, API - finally: Invocation, Client, API",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.4.3",
            "machine_id": "requirement_4_4_3",
            "content": "If a `finally` hook abnormally terminates, evaluation MUST proceed, including the execution of any remaining `finally` hooks.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.4.4",
            "machine_id": "requirement_4_4_4",
            "content": "If an `error` hook abnormally terminates, evaluation MUST proceed, including the execution of any remaining `error` hooks.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.4.5",
            "machine_id": "requirement_4_4_5",
            "content": "If an error occurs in the `before` or `after` hooks, the `error` hooks MUST be invoked.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.4.6",
            "machine_id": "requirement_4_4_6",
            "content": "If an error occurs during the evaluation of `before` or `after` hooks, any remaining hooks in the `before` or `after` stages MUST NOT be invoked.",
            "RFC 2119 keyword": "MUST NOT",
            "children": []
        },
        {
            "id": "Requirement 4.4.7",
            "machine_id": "requirement_4_4_7",
            "content": "If an error occurs in the `before` hooks, the default value MUST be returned.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.5.1",
            "machine_id": "requirement_4_5_1",
            "content": "`Flag evaluation options` MAY contain `hook hints`, a map of data to be provided to hook invocations.",
            "RFC 2119 keyword": "MAY",
            "children": []
        },
        {
            "id": "Requirement 4.5.2",
            "machine_id": "requirement_4_5_2",
            "content": "`hook hints` MUST be passed to each hook.",
            "RFC 2119 keyword": "MUST",
            "children": []
        },
        {
            "id": "Requirement 4.5.3",
            "machine_id": "requirement_4_5_3",
            "content": "The hook MUST NOT alter the `hook hints` structure.",
            "RFC 2119 keyword": "MUST NOT",
            "children": []
        }
    ]
}