docs: clarify custom op edge cases (#1936)

- Custom ops (sem_ver, starts_with/ends_with, fractional) now specify
null on error instead of false in specs and flowcharts
- Added null error-handling admonition to the custom operations section
in flag-definitions.md
- Documented semver edge cases (v-prefix stripping, partial version
padding, numeric coercion, build metadata ignored)
- Documented shared evaluator $ref resolution and nested $ref limitation
in both flag-definitions.md and providers.md
- Fixed fractional spec Go reference code fallthrough to return nil
instead of ""
- Fixed dotnet provider README include path

Everything here is covered in newly added gherkin tests.

Signed-off-by: Todd Baert <todd.baert@dynatrace.com>

Author: toddbaert

docs/providers/dotnet.md

@@ -3,6 +3,6 @@
 ## Installation
 
 {%
-  include "https://raw.githubusercontent.com/open-feature/dotnet-sdk-contrib/main/src/OpenFeature.Contrib.Providers.Flagd/README.md"
+  include "https://raw.githubusercontent.com/open-feature/dotnet-sdk-contrib/main/src/OpenFeature.Providers.Flagd/README.md"
   start="## Install dependencies"
 %}

docs/reference/custom-operations/semver-operation.md

@@ -15,17 +15,25 @@ Note that the 'sem_ver' evaluation rule must contain exactly three items:
 The `sem_ver` evaluation returns a boolean, indicating whether the condition has been met.
 
 ```js
-{
-    "if": [
-        {
-            "sem_ver": [{"var": "version"}, ">=", "1.0.0"]
-        },
-        "red", null
-    ]
-}
+// sem_ver property name used in a targeting rule
+"sem_ver": [
+  // Evaluation context property to be evaluated
+  {"var": "version"},
+  // Operator to use for comparison
+  ">=",
+  // Target value to compare against
+  "1.0.0"
+]
 ```
 
-## Example for 'sem_ver' Evaluation
+!!! tip
+
+    Version strings may include a `v` or `V` prefix (e.g. `v1.0.0`), which is stripped before comparison.
+    Partial versions such as `1.0` or `1` are also accepted and padded with `.0` to form a complete version.
+    Numeric context values (e.g. integer `1`) are coerced to strings before parsing.
+    Build metadata (e.g. `1.0.0+build`) is ignored during comparison, per the SemVer specification.
+
+## Example
 
 Flags defined as such:
 

docs/reference/custom-operations/string-comparison-operation.md

@@ -22,7 +22,7 @@ The `starts_with` evaluation returns a boolean, indicating whether the condition
 ]
 ```
 
-## Example for 'starts_with' Operation
+## Example
 
 Flags defined as such:
 

docs/reference/flag-definitions.md

@@ -393,6 +393,11 @@ Consistent with built-in JsonLogic operators, flagd's custom operators return fa
 | `ends_with`                        | Attribute ends with the specified value             | string                                       | Logic: `#!json { "ends_with" : [ "noreply@example.com", "@example.com"] }`<br>Result: `true`<br><br>Logic: `#!json { ends_with" : [ "noreply@example.com", "@test.com"] }`<br>Result: `false`<br>Additional documentation can be found [here](./custom-operations/string-comparison-operation.md). |
 | `sem_ver`                          | Attribute matches a semantic versioning condition   | string (valid [semver](https://semver.org/)) | Logic: `#!json {"sem_ver": ["1.1.2", ">=", "1.0.0"]}`<br>Result: `true`<br><br>Additional documentation can be found [here](./custom-operations/semver-operation.md).                                                                                                                              |
 
+!!! info "Error handling in custom operations"
+
+    flagd's custom operations return `null` on invalid or unexpected inputs, consistent with how built-in JsonLogic operations represent no-value returns, for example how `var` treats missing keys.
+    When used inside an `if`, `null` is falsy, so evaluation falls through to the else branch rather than producing a false positive match.
+
 #### Targeting key
 
 flagd and flagd providers map the [targeting key](https://openfeature.dev/specification/glossary#targeting-key) into the `"targetingKey"` property of the context used in rules.
@@ -487,6 +492,11 @@ Example:
 }
 ```
 
+!!! warning
+
+    Shared evaluators do not support references to other shared evaluators (nested `$ref`s).
+    Each `$evaluator` definition must be self-contained.
+
 ## Metadata
 
 Metadata can be defined at both the flag set (as a sibling of [flags](#flags)) and within each flag.

docs/reference/specifications/custom-operations/fractional-operation-spec.md

@@ -227,6 +227,6 @@ func FractionalEvaluation(values, data interface{}) interface{} {
         }
     }
 
-    return ""
+  return nil
 }
 ```

docs/reference/specifications/custom-operations/semver-operation-spec.md

@@ -21,7 +21,7 @@ The 'sem_ver' evaluation rule contains exactly three items:
 1. Target property value: the resolved value of the target property referenced in the targeting rule
 2. Operator: One of the following: `=`, `!=`, `>`, `<`, `>=`, `<=`, `~` (match minor version), `^` (match major version)
 3. Target value: this needs to resolve to a semantic versioning string. If this condition is not met, the evaluator should
-log an appropriate error message and return `false`
+log an appropriate error message and return `null`
 
 The `sem_ver` evaluation returns a boolean, indicating whether the condition has been met.
 
@@ -35,7 +35,7 @@ The following flow chart depicts the logic of this evaluator:
 flowchart TD
 A[Parse targetingRule] --> B{Is an array containing exactly three items?};
 B -- Yes --> C{Is targetingRule at index 0 a semantic version string?};
-B -- No --> D[Return false];
+B -- No --> D[Return null];
 C -- Yes --> E{Is targetingRule at index 1 a supported operator?};
 C -- No --> D;
 E -- Yes --> F{Is targetingRule at index 2 a semantic version string?};

docs/reference/specifications/custom-operations/string-comparison-operation-spec.md

@@ -32,7 +32,7 @@ The following flow chart depicts the logic of this evaluator:
 flowchart TD
 A[Parse targetingRule] --> B{Is an array containing exactly two items?};
 B -- Yes --> C{Is targetingRule at index 0 a string?};
-B -- No --> D[Return false];
+B -- No --> D[Return null];
 C -- Yes --> E{Is targetingRule at index 1 a string?};
 C -- No --> D;
 E -- No --> D;

docs/reference/specifications/providers.md

@@ -239,6 +239,11 @@ In addition to the built-in evaluators provided by JsonLogic, the following cust
 - [Semantic version evaluation](../../reference/custom-operations/semver-operation.md)
 - [StartsWith/EndsWith evaluation](../../reference/custom-operations/string-comparison-operation.md)
 
+### Shared Evaluator Resolution
+
+Before evaluating a flag's targeting rules, providers resolve any `$ref` references by replacing them with the corresponding entry from the `$evaluators` object defined in the flag set.
+Nested references (`$ref` within a `$ref`) are not supported; each shared evaluator must be self-contained.
+
 ### Targeting Key
 
 Similar to the flagd daemon, in-process providers map the [targeting-key](https://openfeature.dev/specification/glossary#targeting-key) into a top level property of the context used in rules, with the key `"targetingKey"`.