[V_delta] Rename depends_on(k).value → document_id

schemas/V_delta/conversions/from_did_v1/_universal_renames.md

@@ -247,7 +247,55 @@ directory (one markdown per class) rather than in a version flag.
 This rule is purely V_delta-side bookkeeping; it imposes no
 transformation on the did_v1 document being migrated.
 
-## 9. Planned: `schema_version` on every document
+## 9. `depends_on(k).id` → `depends_on(k).document_id`
+
+Every did_v1 document carries cross-document references as an array of
+two-key (sometimes three-key) entries:
+
+```json
+"_depends_on": [
+    { "_name": "probe_id", "_id": "aabb...", "_version": "..." },
+    ...
+]
+```
+
+After rule §1 strips the underscore prefix the keys are `name`, `id`,
+and optionally `version`. V_delta renames `id` → `document_id` and
+drops `version` entirely. The result on every V_delta document
+instance is:
+
+```json
+"depends_on": [
+    { "name": "probe_id", "document_id": "aabb..." },
+    ...
+]
+```
+
+The rename motivation: `id` collided with the top-level
+`base.id` field for the documents themselves; the earlier V_delta
+draft used `value`, which avoided the collision but was uninformative
+("a value of what?"). `document_id` says exactly what the field is —
+a `did_uid` referring to another document — and the explicit
+`document_` prefix disambiguates from any future id-shaped fields the
+schema may add.
+
+`version` is dropped because V_delta does not support per-document
+version branches; cross-document references resolve to whichever
+version of the target document is current in the database.
+
+| did_v1 entry key | V_delta entry key |
+|---|---|
+| `id` | `document_id` |
+| `version` | _(dropped)_ |
+| `name` | `name` *(unchanged)* |
+
+The universal-rename pass in `did2.convert.universalRenames`
+(`renameDependsOnEntries`) implements this rule. It also tolerates
+the earlier V_delta-draft key `value` as a synonym for `id` so
+already-migrated corpora convert forward to `document_id` on next
+read.
+
+## 10. Planned: `schema_version` on every document
 
 V_delta plans to add a required `schema_version` field on `base` (and
 therefore on every inheriting document). Established values:

schemas/V_delta/conversions/from_did_v1/contrast_tuning.md

@@ -37,7 +37,7 @@ template (the schema file alone is insufficient).
 | `contrast_tuning.fit.naka_rushton_RB_*` (9 fields) | `contrast_tuning.fit.naka_rushton_rb.*` | regrouped into nested struct + snake-cased; scalar metrics → `double`, array metrics → `matrix<double>`; `sensitivity` is a 1x10 `matrix<double>` (see below) |
 | `contrast_tuning.fit.naka_rushton_RBN_*` | `contrast_tuning.fit.naka_rushton_rbn.*` | same |
 | `contrast_tuning.fit.naka_rushton_RBNS_*` | `contrast_tuning.fit.naka_rushton_rbns.*` | same |
-| (top-level) `depends_on: [element_id, stimulus_tuningcurve_id]` | top-level `depends_on` array | identity (named refs declared on the schema, value carried on document instances) |
+| (top-level) `depends_on: [element_id, stimulus_tuningcurve_id]` | top-level `depends_on` array | identity (named refs declared on the schema, document_id carried on document instances) |
 
 ## Transformations in detail
 

schemas/V_delta/conversions/from_did_v1/ontology_image.md

@@ -90,7 +90,7 @@ a new field).
         ]
     },
     "depends_on": [
-        { "name": "element_id", "value": "" }
+        { "name": "element_id", "document_id": "" }
     ],
     "base": {
         "id":         "aabb1122ccdd3344_1122334455667788",
@@ -117,7 +117,7 @@ a new field).
         ]
     },
     "depends_on": [
-        { "name": "element_id", "value": "" }
+        { "name": "element_id", "document_id": "" }
     ],
     "base": {
         "id":         "aabb1122ccdd3344_1122334455667788",

schemas/V_delta/conversions/from_did_v1/ontology_label.md

@@ -98,7 +98,7 @@ new field).
         ]
     },
     "depends_on": [
-        { "name": "element_id", "value": "" }
+        { "name": "element_id", "document_id": "" }
     ],
     "base": {
         "id":         "aabb1122ccdd3344_1122334455667788",
@@ -126,7 +126,7 @@ new field).
         ]
     },
     "depends_on": [
-        { "name": "element_id", "value": "" }
+        { "name": "element_id", "document_id": "" }
     ],
     "base": {
         "id":         "aabb1122ccdd3344_1122334455667788",

schemas/V_delta/conversions/from_did_v1/orientation_direction_tuning.md

@@ -49,7 +49,7 @@ field-level typing in V_delta is recovered from the paired db_doc template
 | `orientation_direction_tuning.fit.orientation_angle_preference` | same | identity (double) |
 | `orientation_direction_tuning.fit.direction_angle_preference` | same | identity (double) |
 | `orientation_direction_tuning.fit.hwhh` | same | identity (double) |
-| (top-level) `depends_on: [element_id, stimulus_tuningcurve_id]` | top-level `depends_on` array | identity (named refs declared on the schema, value carried on document instances) |
+| (top-level) `depends_on: [element_id, stimulus_tuningcurve_id]` | top-level `depends_on` array | identity (named refs declared on the schema, document_id carried on document instances) |
 
 ## Transformations in detail
 

schemas/V_delta/conversions/from_did_v1/probe_location.md

@@ -33,7 +33,7 @@ class-scoped property block keyed by `probe_location`).
 | `probe_location.ontology_name` (char) | `probe_location.location.node` | composed into `ontology_term` | CURIE (e.g., `uberon:0002436`). See "Transformations in detail". |
 | `probe_location.name` (char) | `probe_location.location.name` | composed into `ontology_term` | Human-readable label snapshot (e.g., `primary visual cortex`). |
 | — | `probe_location.location` (ontology_term) | new composite field | Created by composing the two did_v1 chars above. |
-| `depends_on[probe_id]` | `depends_on[probe_id]` | identity | Declared on the schema; the value travels with each document. |
+| `depends_on[probe_id]` | `depends_on[probe_id]` | identity | Declared on the schema; the document_id travels with each document. |
 
 ## Transformations in detail
 
@@ -85,7 +85,7 @@ once it ships; until then no migrated document needs to carry it.
         ]
     },
     "depends_on": [
-        { "name": "probe_id", "value": "aabb1122ccdd3344_aabb1122ccdd3344" }
+        { "name": "probe_id", "document_id": "aabb1122ccdd3344_aabb1122ccdd3344" }
     ],
     "base": {
         "id":         "aabb1122ccdd3344_1122334455667788",
@@ -112,7 +112,7 @@ once it ships; until then no migrated document needs to carry it.
         ]
     },
     "depends_on": [
-        { "name": "probe_id", "value": "aabb1122ccdd3344_aabb1122ccdd3344" }
+        { "name": "probe_id", "document_id": "aabb1122ccdd3344_aabb1122ccdd3344" }
     ],
     "base": {
         "id":         "aabb1122ccdd3344_1122334455667788",

schemas/V_delta/conversions/from_did_v1/treatment.md

@@ -96,9 +96,9 @@ will be inherited from `base` when it ships.
         ]
     },
     "depends_on": [
-        { "name": "subject_id",      "value": "aabb1122ccdd3344_aabb1122ccdd3344" },
-        { "name": "manipulation_id", "value": "" },
-        { "name": "protocol_id",     "value": "" }
+        { "name": "subject_id",      "document_id": "aabb1122ccdd3344_aabb1122ccdd3344" },
+        { "name": "manipulation_id", "document_id": "" },
+        { "name": "protocol_id",     "document_id": "" }
     ],
     "base": {
         "id":         "aabb1122ccdd3344_1122334455667788",
@@ -127,9 +127,9 @@ will be inherited from `base` when it ships.
         ]
     },
     "depends_on": [
-        { "name": "subject_id",      "value": "aabb1122ccdd3344_aabb1122ccdd3344" },
-        { "name": "manipulation_id", "value": "" },
-        { "name": "protocol_id",     "value": "" }
+        { "name": "subject_id",      "document_id": "aabb1122ccdd3344_aabb1122ccdd3344" },
+        { "name": "manipulation_id", "document_id": "" },
+        { "name": "protocol_id",     "document_id": "" }
     ],
     "base": {
         "id":         "aabb1122ccdd3344_1122334455667788",

schemas/V_delta/stable/ndi_reserved_keys.json

@@ -35,9 +35,9 @@
         { "name": "class_name", "context": "inside document_class and inside document_class.superclasses entries", "description": "Concrete-class or superclass identifier." },
         { "name": "class_version", "context": "inside document_class and inside document_class.superclasses entries", "description": "Semantic version at write time." },
         { "name": "superclasses", "context": "inside document_class", "description": "Snapshot of the inheritance chain at write time." },
-        { "name": "depends_on", "context": "top-level", "description": "Array of dependency-value objects." },
+        { "name": "depends_on", "context": "top-level", "description": "Array of dependency-id objects." },
         { "name": "name", "context": "inside depends_on entries", "description": "Role name matching a dependency declaration (after numbered-dependency expansion)." },
-        { "name": "value", "context": "inside depends_on entries", "description": "DID UID of the referenced document." }
+        { "name": "document_id", "context": "inside depends_on entries", "description": "DID UID of the referenced document. Renamed from V_alpha's `id` and the earlier V_delta draft `value`: the field is always a did_uid string referring to another document, and the explicit name signals that." }
     ],
     "notes": [
         "Property-block keys in a document instance equal the `class_name` of a class in the document's inheritance chain. These are reserved by virtue of being class names; they are not enumerated here because they are not fixed strings.",

schemas/V_delta_notes.md

@@ -44,6 +44,17 @@ substantive schema content changes will land in follow-up PRs.
 
 ### Schema content
 
+- **`depends_on(k).document_id` (renamed from `value`).** The
+  `depends_on` array entries on every V_delta document instance carry
+  the keys `name` (role) and `document_id` (DID UID of the referenced
+  document). This replaces the earlier V_delta draft choice of `value`,
+  which was generic but uninformative — every entry's value in practice
+  always is a `did_uid` referring to another document. The rename lets
+  the field name signal its semantics. V_alpha → V_delta migration in
+  `did2.convert.universalRenames` now produces `document_id` (was
+  `value`); existing V_delta corpora with `value` are accepted by the
+  universal-rename pass and converted forward. See
+  `ndi_reserved_keys.json` for the registry entry.
 - **`maturity_level` values updated.** All 101 V_delta document-class
   schemas now declare `"maturity_level": "stable"` to match their
   current `stable/` folder placement. The meta-schema enforces the new