From c92f00fad4707bb56083e8fb7c2e7dee6bb972f8 Mon Sep 17 00:00:00 2001
From: Nicolas Karageuzian <nka11@users.noreply.github.com>
Date: Sun, 11 Oct 2026 10:14:23 +0200
Subject: [PATCH] docs: state that policy right operands are literals

Document in the adopters policy engine page that a constraint's right
operand is a literal value, that identifiers are plain strings, and how
EDC handles a node reference ({"@id": ...}) as a right operand. Replace
the contributors' entities page claim that the right operand is
"completely arbitrary" with a link to the new section.

Assisted-by: Anthropic Claude Opus (claude-opus-5-5)
---
 .../control-plane/policy-engine/_index.md     | 36 +++++++++++++++++++
 .../control-plane/entities/_index.md          |  5 +--
 2 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/content/en/documentation/for-adopters/control-plane/policy-engine/_index.md b/content/en/documentation/for-adopters/control-plane/policy-engine/_index.md
index 9535bb2..c5a8b74 100644
--- a/content/en/documentation/for-adopters/control-plane/policy-engine/_index.md
+++ b/content/en/documentation/for-adopters/control-plane/policy-engine/_index.md
@@ -4,6 +4,7 @@ weight: 10
 ---
 
 <!-- TOC -->
+  * [Right Operand Values](#right-operand-values)
   * [CEL Policy Expressions](#cel-policy-expressions)
   * [Policy Scopes and Bindings](#policy-scopes-and-bindings)
     * [Designing for Optimal Policy Performance](#designing-for-optimal-policy-performance)
@@ -96,6 +97,41 @@ public class TestPolicy implements AtomicConstraintRuleFunction<Duty, Participan
 
 Note that `PolicyContext` has its own hierarchy, that's tightly bound to the policy scope.
 
+## Right Operand Values
+
+The right operand of a constraint is a literal value: a string, a number, a boolean, a typed literal, or an array of
+these. EDC applies no IRI semantics to it: the policy model is a plain object model, and JSON-LD is only used for
+namespace handling. Policy functions receive the value and compare it as given. If a policy profile needs the right
+operand to be an identifier, it states so and uses a plain string.
+
+Concretely, a right operand expressed as a node reference (`{"@id": ...}`):
+
+- is rejected by the Management API with a `400 Bad Request`;
+- is read as the plain string it contains when received over the Dataspace Protocol;
+- is never emitted by EDC.
+
+This constraint is accepted:
+
+```json
+{
+  "leftOperand": "membership",
+  "operator": "eq",
+  "rightOperand": "https://example.com/memberships/gold"
+}
+```
+
+This one is rejected by the Management API:
+
+```json
+{
+  "leftOperand": "membership",
+  "operator": "eq",
+  "rightOperand": {
+    "@id": "https://example.com/memberships/gold"
+  }
+}
+```
+
 ## CEL Policy Expressions
 
 The code-first approach described above is the primary way to evaluate policies, but it requires writing and
diff --git a/content/en/documentation/for-contributors/control-plane/entities/_index.md b/content/en/documentation/for-contributors/control-plane/entities/_index.md
index b21ad7d..f8cdff9 100644
--- a/content/en/documentation/for-contributors/control-plane/entities/_index.md
+++ b/content/en/documentation/for-contributors/control-plane/entities/_index.md
@@ -212,9 +212,10 @@ MUST (`duty`), MAY (`permission`) or MUST NOT (`prohibition`) relation. The `act
 which the rule is intended. Acceptable values for `action` are defined [here](https://www.w3.org/TR/odrl-model/#action),
 but in EDC you'll exclusively encounter `"use"`.
 
-The `constraint` object expresses logical relationship of a key (`leftOperand`), the value (`righOperand`) and the
+The `constraint` object expresses logical relationship of a key (`leftOperand`), the value (`rightOperand`) and the
 `operator`. Multiple constraints can be linked with logical operators, see [advanced policy
-concepts](#25-advanced-policy-concepts). The `leftOperand` and `rightOperand` are completely arbitrary, only the
+concepts](#25-advanced-policy-concepts). The `leftOperand` is arbitrary, and the `rightOperand` is a literal value (see
+[Right Operand Values](../../../for-adopters/control-plane/policy-engine/_index.md#right-operand-values)). The
 `operator` is limited to the following possible values: `eq`, `neq`, `gt`, `geq`, `lt`, `leq`, `in`, `hasPart`, `isA`,
 `isAllOf`, `isAnyOf`, `isNoneOf`.