From f6610f3257707a1ec2845cb397ae27ebe6e3728a Mon Sep 17 00:00:00 2001 From: Jeroen De Dauw Date: Mon, 7 Sep 2026 19:17:22 +0200 Subject: [PATCH 1/2] Drop the "Child Subject" term; record what a page's Subjects are Fixes https://github.com/ProfessionalWiki/NeoWiki/issues/959 A page holds Subjects, one of them optionally the Main Subject; sharing a page is storage, not a relationship, so the other Subjects need no term of their own. The glossary still called them Child Subjects, which implied a link to the Main Subject that only an explicit Relation carries. Drop the term from the glossary (with an Avoid entry), from the Draft ADRs 28 and 31, and from planning/Relations.md; the decisions themselves are unchanged. The planning doc also records where in-flow-created Subjects land now that a Subject can be moved, carries the page-scoped vs free-standing question from the issue so closing it does not lose the question, and points at the identifier rename that follows (https://github.com/ProfessionalWiki/NeoWiki/issues/1367). Considered, omitted: the identifier and API renames themselves and the API docs that describe them, tracked in https://github.com/ProfessionalWiki/NeoWiki/issues/1367 for after https://github.com/ProfessionalWiki/NeoWiki/pull/1265 lands. ADR 7 keeps its wording as an accepted record. Co-Authored-By: Claude Fable 5 --- docs/adr/028-relations-model.md | 8 ++++---- docs/adr/031-optional-subject-labels.md | 19 ++++++++--------- docs/glossary.md | 4 +++- docs/planning/Relations.md | 27 ++++++++++++++++++++----- 4 files changed, 39 insertions(+), 19 deletions(-) diff --git a/docs/adr/028-relations-model.md b/docs/adr/028-relations-model.md index e7d7c00fc..ba5bb9a56 100644 --- a/docs/adr/028-relations-model.md +++ b/docs/adr/028-relations-model.md @@ -19,7 +19,7 @@ current wiki ([#1084](https://github.com/ProfessionalWiki/NeoWiki/pull/1084)). W the model questions as one coherent set. Two earlier decisions left threads this one closes. [ADR 7](007-multiple-subjects-per-page.md) allowed multiple -Subjects per page but left an automatic relation between the Main and Child Subjects open. +Subjects per page but left an automatic relation between the Main Subject and the page's other Subjects open. [ADR 10](010-add-guids-to-relations.md) gave Relations stable IDs and named edge properties as roadmap. ## Decision @@ -75,15 +75,15 @@ styling. ### Same-page relationships are schema-defined -No Relation is created automatically between Subjects that share a page. A Child Subject relates to the page's Main +No Relation is created automatically between Subjects that share a page. A Subject relates to the page's Main Subject only through an explicit relation property in its Schema. An unstated co-location link would carry no defined meaning, and the same relationship expressed across pages would then diverge from the same-page shortcut (positions in [#959](https://github.com/ProfessionalWiki/NeoWiki/issues/959)). The Main Subject designation stays: it anchors the automatic display and the page-topic semantics, and the page/document-type pattern builds on it ([#959](https://github.com/ProfessionalWiki/NeoWiki/issues/959)). Pre-filling a -Child Subject's relation to the Main Subject during creation is editing convenience layered on this rule, not a model -relation. This resolves the open question in [ADR 7](007-multiple-subjects-per-page.md). +new Subject's relation to the page's Main Subject during creation is editing convenience layered on this rule, not a +model relation. This resolves the open question in [ADR 7](007-multiple-subjects-per-page.md). ### Name a relation once, on the property diff --git a/docs/adr/031-optional-subject-labels.md b/docs/adr/031-optional-subject-labels.md index a205c22e6..49b48b4ff 100644 --- a/docs/adr/031-optional-subject-labels.md +++ b/docs/adr/031-optional-subject-labels.md @@ -26,10 +26,10 @@ frontend, so `rdfs:label`, Lua and `{{#neowiki_value}}` keep the bare Schema nam `displayNameIsGenerated`, which a client cannot derive, since a Main Subject on a page titled after its Schema is named its Schema name without anyone having generated it. -**The graph materializes the fallback for Main Subjects only.** A Child Subject without a label gets no `name` +**The graph materializes the fallback for Main Subjects only.** Any other label-less Subject gets no `name` property: the Schema name there would make every unnamed Subject of a Schema indistinguishable in query results, and -the Schema is already on the node as its other label. Should a consumer ever need it, materializing the Child tier too -is the escape hatch. +the Schema is already on the node as its other label. Should a consumer ever need it, materializing them too is the +escape hatch. **RDF emits `rdfs:label` for every Subject.** Consumers key on it, and the Schema appears there as `rdf:type` rather than as a label, so the argument above does not carry over. A Mapping's `labelPredicate` is emitted only from a stored @@ -45,10 +45,11 @@ that have no stored label, so without it every existing Subject keeps the bug. ## Consequences -A Subject node's `name` is null for a label-less Child Subject, so a stub is identified by its node labels rather than -by a missing name, and such a Subject is not findable by name in label search. Several label-less Child Subjects of one -Schema display identically; the computation can gain discriminators later, which stored defaults could not. +A Subject node's `name` is null for a label-less Subject that is not the Main Subject, so a stub is identified by its +node labels rather than by a missing name, and such a Subject is not findable by name in label search. Several such +Subjects of one Schema display identically; the computation can gain discriminators later, which stored defaults could +not. -Clearing costs a revision per page, and a Child Subject that carried the older page-name default is renamed to its -Schema name by it. `Subject.getLabel()` in the frontend bundle can return null; display code goes through -`presentation/subjectDisplayName.ts`, which marks the Schema tier. +Clearing costs a revision per page, and a Subject that is not the Main Subject and carried the older page-name default +is renamed to its Schema name by it. `Subject.getLabel()` in the frontend bundle can return null; display code goes +through `presentation/subjectDisplayName.ts`, which marks the Schema tier. diff --git a/docs/glossary.md b/docs/glossary.md index 22b12317a..2fc9c4b23 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -17,7 +17,9 @@ Pages have * An **id**: persistent numeric ID. * **Content**: wikitext * **Subjects**: list of Subjects, can be empty ([ADR 7](adr/007-multiple-subjects-per-page.md)) -* **Main Subject**: optional identifier of a Subject in the page's Subjects list. Indicates which Subject represents the same entity as the page itself. All other Subjects stored on a page are called **Child Subjects**. +* **Main Subject**: optional identifier of a Subject in the page's Subjects list. Indicates which Subject represents the same entity as the page itself. Sharing a page is storage, not a relationship ([ADR 28](adr/028-relations-model.md)). + +*Avoid: "Child Subject" — former term for a page's other Subjects.* ## Subject diff --git a/docs/planning/Relations.md b/docs/planning/Relations.md index 6fab6e328..5cc557934 100644 --- a/docs/planning/Relations.md +++ b/docs/planning/Relations.md @@ -45,7 +45,7 @@ interlinked imports can wire relations before their targets exist. The statement ([#991](https://github.com/ProfessionalWiki/NeoWiki/issues/991)). 4. **Missing targets are red links** — legitimate forward references; a warning, not an error ([#1120](https://github.com/ProfessionalWiki/NeoWiki/issues/1120)). -5. **Same-page relationships are schema-defined** — no automatic Main/Child relation +5. **Same-page relationships are schema-defined** — no automatic relation between the Subjects on a page ([#959](https://github.com/ProfessionalWiki/NeoWiki/issues/959)). 6. **Name a relation once, on the property** — proposed, least settled and the item most open to feedback: key edges and predicates on the property name, dropping the separate relation-type name (the status-quo case for keeping both @@ -56,12 +56,12 @@ interlinked imports can wire relations before their targets exist. The statement ### Nested vs flat authoring of intermediate structures CIDOC-CRM-style intermediate nodes — a birth event; a dimension with unit, upper and lower bound, source — can be -expressed today as Child Subjects or a separately linked Subject. The open question is how they are *authored*: +expressed today as Subjects of their own, on the same page or another. The open question is how they are *authored*: - **Route A — flat schemas, mapping synthesizes.** Schemas stay flat; the ontology mapping assembles the intermediate node at RDF-projection time. Cost: the mapping must coordinate several flat fields into one shared node. -- **Route B — Child Subjects as the native representation.** The nesting is real Subjects, with inline editing UX that - projects the structure down into a form. Cost: editor complexity and lazy-loading performance. +- **Route B — Subjects as the native representation.** The intermediate nodes are real Subjects, with inline editing + UX that projects the structure down into a form. Cost: editor complexity and lazy-loading performance. Public positions lean toward Route B ([discussion #996](https://github.com/ProfessionalWiki/NeoWiki/discussions/996), [#999](https://github.com/ProfessionalWiki/NeoWiki/discussions/999)). The decision follows the neutral-person → EDM @@ -101,6 +101,15 @@ without restructuring it ([#904](https://github.com/ProfessionalWiki/NeoWiki/iss With Property Definitions local to their Schema, where relation-target autocomplete draws candidates beyond target-Schema filtering is open ([#1122](https://github.com/ProfessionalWiki/NeoWiki/issues/1122)). +### Page-scoped vs free-standing Subjects + +Early external feedback distinguished two kinds of Subject sharing a page: page-scoped dependents that live and die +with their host page, and free-standing Subjects merely stored there, which must outlive the page and whose home should +stay knowable. Nothing marks which is which: today both go with their page — deleting it removes them (referenced +ones survive as stubs), moving it carries them along. Open: whether the distinction needs a mechanism — a Schema-level +flag, a per-Subject flag, or derivation from the Subject's relations — and what deleting or moving a page should then +do to each ([#959](https://github.com/ProfessionalWiki/NeoWiki/issues/959)). + ### Parked Unconstrained ("any Subject") targets; cardinality beyond single/multiple; no-value / some-value markers @@ -110,13 +119,16 @@ Unconstrained ("any Subject") targets; cardinality beyond single/multiple; no-va ### Editing +- In-flow creation and editing of relation targets ([#971](https://github.com/ProfessionalWiki/NeoWiki/issues/971)). + A Subject created in flow lands on the page being edited; since it keeps its id when moved + ([#1356](https://github.com/ProfessionalWiki/NeoWiki/pull/1356)), a wrong home is cheap to fix. - Red-link create affordance for missing targets ([#1120](https://github.com/ProfessionalWiki/NeoWiki/issues/1120)). - Main-Subject prefill as editing sugar (model decision 5). ### Display - Incoming / inverse relations ([#904](https://github.com/ProfessionalWiki/NeoWiki/issues/904)). -- A built-in incoming-relations section — the smallest non-Lua path to reach related and Child Subjects. +- A built-in incoming-relations section — the smallest non-Lua path to reach the Subjects that point at this one. - Relation hover card ([#377](https://github.com/ProfessionalWiki/NeoWiki/issues/377)). - Target links in the Schema view ([#519](https://github.com/ProfessionalWiki/NeoWiki/issues/519)). - Where-used over incoming relations ([#1039](https://github.com/ProfessionalWiki/NeoWiki/issues/1039)). @@ -133,6 +145,11 @@ Unconstrained ("any Subject") targets; cardinality beyond single/multiple; no-va graceful degradation — follows the [Subject Sources](SubjectSources.md) track ([#993](https://github.com/ProfessionalWiki/NeoWiki/issues/993), [ADR 23](../adr/023-subject-sources.md)). +### Naming + +- Rename the API and code identifiers that still say "child subject" + ([#1367](https://github.com/ProfessionalWiki/NeoWiki/issues/1367)). + ## Track coordination Relations intersect three tracks in flight. [Subject Sources](SubjectSources.md) From 204d703f8978c9044459be6cb90f75e25eb03b01 Mon Sep 17 00:00:00 2001 From: Jeroen De Dauw Date: Mon, 7 Sep 2026 19:25:58 +0200 Subject: [PATCH 2/2] Update glossary.md --- docs/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/glossary.md b/docs/glossary.md index 2fc9c4b23..9984b06af 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -17,7 +17,7 @@ Pages have * An **id**: persistent numeric ID. * **Content**: wikitext * **Subjects**: list of Subjects, can be empty ([ADR 7](adr/007-multiple-subjects-per-page.md)) -* **Main Subject**: optional identifier of a Subject in the page's Subjects list. Indicates which Subject represents the same entity as the page itself. Sharing a page is storage, not a relationship ([ADR 28](adr/028-relations-model.md)). +* **Main Subject**: optional identifier of a Subject in the page's Subjects list. Indicates which Subject represents the same entity as the page itself. *Avoid: "Child Subject" — former term for a page's other Subjects.*