Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/adr/028-relations-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
19 changes: 10 additions & 9 deletions docs/adr/031-optional-subject-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
4 changes: 3 additions & 1 deletion docs/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

*Avoid: "Child Subject" — former term for a page's other Subjects.*

## Subject

Expand Down
27 changes: 22 additions & 5 deletions docs/planning/Relations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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)).
Expand All @@ -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)
Expand Down