diff --git a/schemas/V_delta/conversions/from_did_v1/_universal_renames.md b/schemas/V_delta/conversions/from_did_v1/_universal_renames.md index fa5ffa6..e6a38e1 100644 --- a/schemas/V_delta/conversions/from_did_v1/_universal_renames.md +++ b/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: diff --git a/schemas/V_delta/conversions/from_did_v1/contrast_tuning.md b/schemas/V_delta/conversions/from_did_v1/contrast_tuning.md index 3da67b2..fd05120 100644 --- a/schemas/V_delta/conversions/from_did_v1/contrast_tuning.md +++ b/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`; `sensitivity` is a 1x10 `matrix` (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 diff --git a/schemas/V_delta/conversions/from_did_v1/ontology_image.md b/schemas/V_delta/conversions/from_did_v1/ontology_image.md index 867503b..25aca7c 100644 --- a/schemas/V_delta/conversions/from_did_v1/ontology_image.md +++ b/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", diff --git a/schemas/V_delta/conversions/from_did_v1/ontology_label.md b/schemas/V_delta/conversions/from_did_v1/ontology_label.md index 5df2414..1df8ba0 100644 --- a/schemas/V_delta/conversions/from_did_v1/ontology_label.md +++ b/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", diff --git a/schemas/V_delta/conversions/from_did_v1/orientation_direction_tuning.md b/schemas/V_delta/conversions/from_did_v1/orientation_direction_tuning.md index fc2c02a..12edd7d 100644 --- a/schemas/V_delta/conversions/from_did_v1/orientation_direction_tuning.md +++ b/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 diff --git a/schemas/V_delta/conversions/from_did_v1/probe_location.md b/schemas/V_delta/conversions/from_did_v1/probe_location.md index 3c478ad..7d04051 100644 --- a/schemas/V_delta/conversions/from_did_v1/probe_location.md +++ b/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", diff --git a/schemas/V_delta/conversions/from_did_v1/treatment.md b/schemas/V_delta/conversions/from_did_v1/treatment.md index a4114f5..a991342 100644 --- a/schemas/V_delta/conversions/from_did_v1/treatment.md +++ b/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", diff --git a/schemas/V_delta/stable/ndi_reserved_keys.json b/schemas/V_delta/stable/ndi_reserved_keys.json index aaf9a13..acceb7a 100644 --- a/schemas/V_delta/stable/ndi_reserved_keys.json +++ b/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.", diff --git a/schemas/V_delta_notes.md b/schemas/V_delta_notes.md index 88c80d3..3107ba1 100644 --- a/schemas/V_delta_notes.md +++ b/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