Solid Memo keeps everything a learner makes and studies in their own Solid Pod, as linked data files in one folder, the instance. This page says which file holds what, how the app finds the files after a login, and how it writes them without losing a change made on another device.
The code is in packages/solid/src/: the vocabulary in
vocab.ts, discovery in
typeIndex.ts. The app reads and
writes the pod by the Solid
Protocol, and finds Solid Memo's
data through the type indexes,
an editor's draft
(standards.md).
Solid Memo mints its own terms under
https://solid-memo.com/ns/vocab/v1.ttl# (prefix sm: below); no
existing RDF vocabulary covers spaced repetition.
ns/vocab/v1.ttl defines them
(vocab.md), and a SHACL shape under
ns/shapes/ says what a valid subject of each class
looks like, version by version (shapes.md). The site
publishes both, and the app's constants, record types and descriptors
are generated from them. Readers ignore unknown triples, and writers
never delete triples they don't understand.
Every subject Solid Memo writes carries sm:formatVersion. A subject
with neither that stamp nor a Solid Memo class is another app's, unless
it's the catalog or a subject of Solid Memo's names it as its creator,
publisher or distribution. Another scheduler's review state is another
app's too. The data check only warns about them
(validation.md).
flowchart LR
accTitle: From pod data to the domain model
accDescr: A subject is read as a versioned shape record, migrated to the latest record and mapped to the domain model, and a model is written back the same way in reverse.
thing["Subject<br/>(client/rdf.ts)"] -->|readVersioned| record["shape record<br/>e.g. CardV1"]
record -->|migrate| latest["latest record<br/>CardV2"]
latest -->|cardFromRecord| model["domain model<br/>Card"]
model -->|cardToRecord| latest
latest -->|recordThing| thing
flowchart LR
accTitle: The discovery chain
accDescr: From the WebID, the app follows the storage and the private and public type indexes to the instance container, and from the instance's folder to the rest of its data.
W[WebID] -->|pim:storage| S[Storage root]
W -->|solid:privateTypeIndex<br/>directly and via pim:preferencesFile| PTI[Private type indexes]
W -->|solid:publicTypeIndex| PUB[Public type indexes]
PTI -->|solid:TypeRegistration<br/>forClass sm:Instance| I1[Instance container]
PUB -->|solid:TypeRegistration<br/>forClass sm:Instance| I2[Instance container]
I1 -->|the folder's layout| D1["catalog.ttl, decks/, reviews/,<br/>history/, drafts/"]
I2 -->|the folder's layout| D1
-
Storage:
pim:storagetriples in the (extended) profile. That's the WebID document and the documents it names as more of the profile (rdfs:seeAlso,foaf:isPrimaryTopicOf,foaf:primaryTopic). The WebID document is read underPROFILE_LIMITS, and the others under them all together, no more thanMAX_PROFILE_DOCUMENTSof them (readLimits.ts). Else the Solid Protocol's Link-header walk-up from the WebID URL (rel="type"targetingpim:Storage, capital S), which asks the WebID document and its nearestMAX_STORAGE_ANCESTORS(8) containers (solidStorageGateway.ts); else a URL typed by hand. 0, 1 or N storages are handled. -
Instances: one
solid:TypeRegistrationper instance,solid:forClass sm:Instance, in the type index the user chooses (below), itsdcterms:titlenaming the instance (harmless extra triples): the only registration Solid Memo reads to find its instances. Reading acceptssolid:instanceContainerorsolid:instancenaming an http(s) address with no query, fragment, dot segment (..,%2e%2ein any case) or empty segment (//;isInstanceAddressin instanceLayout.ts). The address is taken as written: another spelling of a folder (its host's case, a name outside ASCII) is that folder (below). An instance created, attached by URL or moved to from a guest's pod is registered at its address as a request sends it (instanceAddressOf):HTTPS://Pod.example:443/kortlekar-åishttps://pod.example/kortlekar-%C3%A5/. An address thatisInstanceAddressrefuses as a request sends it isn't an instance to attach (notAnInstanceNoMeta). An instance with no title is named after its folder, with its percent-encoding undone; a name whose escapes don't decode, such ascaf%E9, is shown as written (lastPathSegmentin urls.ts). A registration that still can't be read as an instance is left out, and the rest of the list still loads. An index, a preferences file or an extended profile counts as none only when it isn't there (404, 410), can't be parsed or goes past the read's limits, even before it's sent (readsAsNonein datasets.ts). One outside the profile's own places, or past theMAX_PROFILE_DOCUMENTSa profile is read in, isn't read at all and holds none either. One that can't be read right now fails the list. That's a refusal (401, 403), any other status, no answer in time (podNoAnswer) or any other of the app's errors, an abort whatever its reason, no answer at all, or an error caused by one of these. An address the app doesn't send the user's login to (credentialsRefused), such as an index whose path names another server, fails the list too, each time it's read, until the link to the index is fixed. An access token may expire while the app is in the background, or a pod may be slow to answer. A list read again then must not come back empty, which would offer to create an instance the user already has. The app keeps the list it read before, and shows the error only when it has none. A type index is data another app may have written, and every instance listed is read. So the app follows the firstMAX_CATALOG_LINKS(1,000) instances of all the indexes, the private ones first, and the list says when it is that long. -
The rest of an instance's data has no registration: the catalog, the decks, cards, review states, answers and drafts are reached from the instance, at the places its folder's layout gives them (Instance layout). Earlier versions of the app wrote one registration per class of that data beside the
sm:Instanceone (examples below). The app no longer writes them, and still recognizes them: removing or deleting an instance removes them, renaming it retitles them, and the user can remove them from Preferences, keeping the instance. -
Writing a type index saves it with
If-Matchthe version read; on a 412 it tries again, three attempts in all (changeIndexin typeIndex.ts). The registration is added only when no equal one is there:sm:Instance, naming the container under either predicate, with or without its trailing slash (addInstanceRegistration). typeIndex.integration.test.ts reads the registration back from real servers. -
Type index links are read from the WebID subject in the WebID document and in every extended profile document (
rdfs:seeAlso/foaf:isPrimaryTopicOf), and private ones in thepim:preferencesFiletoo, where the Type Indexes specification keeps them. A public link in the preferences file is left out: the file is private, so no other app finds it there. A pod made long ago may link several indexes of a kind, such as one an app wrote at/settings/privateTypeIndexand one the preferences file names at/settings/privateTypeIndex.ttl. So every link is kept, each kind's once by address and no more thanMAX_PROFILE_DOCUMENTSof them (locateTypeIndexes). Only the documents on the WebID's origin, on its document's origin or in a storage the profile names are read; a link to one anywhere else is left alone (boundaries.md). The preferences file is read only in one of the user's own storages, those their profile names (pim:storage) or else the one their WebID is in, or in those places when no storage is found. Each is read underPROFILE_LIMITS, no more thanMAX_PROFILE_DOCUMENTSextended profile documents: a WebID document past them fails the lookup, and any other is left out. An index outside the user's own storages may be someone else's, even on the WebID's origin, since one server may keep many users' pods on it. So the app leaves a link to it out: nothing in it is read or written, no instance it registers is listed, and the user may create their own. Such a server shows each user's storage. When the storage lookup fails or finds none, the app still reads every index linked in the profile's own places, and lists the instances they register, but writes less:- When the WebID leads to no storage, the app writes only to an index
in the WebID's own pod: the folder of the WebID document, or the
folder above it when that's
profile/. Only such an index is chosen by kind, accepted by its address, registered in, retitled on a rename or cleaned of an instance's registrations. - When the lookup fails, the app writes to no index. Choosing one to register in, retitling an instance's registrations and removing them fail as the lookup did, and work when it works again.
- When the WebID leads to no storage, the app writes only to an index
in the WebID's own pod: the folder of the WebID document, or the
folder above it when that's
-
Missing indexes are normal on Community Solid Server pods. The app warns the user, who chooses to create the private index (a document under
<storage>settings/plus a profile link) or to register publicly. A kind counts as missing when no index of it is there or readable by the user (401, 403 count as not readable); any other failed read fails the choice. A public index the app creates is made readable by everyone with the public-read grant, as a published release is (boundaries.md). Other apps then find what it registers. When the grant fails, the index is kept as it is, and the choice says no one else can read it. The index goes in a storage the WebID leads to (never one typed by hand): the instance's, else the first. It never goes on the server of an instance elsewhere (attached by URL, or in a storage typed by hand). Without such a storage the index isn't created (typeIndexNoStorage,ownStorageForintypeIndex.ts). The link goes in the WebID document when it's writable, else in the first extended profile in one of the user's own storages that accepts it (on Inrupt PodSpaces the WebID document onid.inrupt.comis read-only, and<storage>profileis writable). A document already at the target URL is adopted when it's typedsolid:TypeIndex(notATypeIndexotherwise), not overwritten, and who may read it is left as it is: only an index the app writes gets the public-read grant. If registration fails, instance creation fails loudly, with no local fallback, and the new container is cleaned up. An instance is registered in the index the user chose, and in no other. -
An index entered by its address must be in one of the user's own storages, those their profile names (
pim:storage) or else the one their WebID is in (typeIndexOutsidePod), linked from the profile or not. The WebID's origin isn't enough: one server may keep many users' pods on it. Without a storage, the WebID's own pod stands in, as above. One the profile links is used as it is. Any other must also be readable by the user and typedsolid:TypeIndex(notATypeIndex). The app finds its instances only in the indexes the profile links, so it then links this one from the profile: as public when it's typedsolid:ListedDocument, as private otherwise (adoptTypeIndex). -
Deleting an instance deletes what Solid Memo wrote in its container and nothing else (
deleteInstanceDatain instanceData.ts). Then it removes its registrations from every type index of the user's: itssm:Instanceone and any an earlier version wrote for its data (below). In order:- each deck's cards and reviews documents as the catalog names them,
if they're the deck's: they say so, or they're in the instance's
own folder (below). A release (a document whose
<>is ansm:Deck) or a draft's document is never a deck's, wherever it is, and nothing in it is removed; - the answer log's months (
history/<YYYY-MM>.ttl), ashistory/itself lists them; - the drafts the catalog links that are in the instance's
drafts/(Drafts and releases); preferences.ttl,palettes.ttl,digest.ttlandcatalog.ttl, in that order, so a failed delete can be retried and find the decks and drafts again. A catalog the pod serves but that can't be read is kept, with the decks' documents and the drafts; the rest goes;decks/,reviews/,history/anddrafts/, each only if then empty;meta.ttl, last of the documents, so a half-deleted instance still attaches by URL;- the container, only if then empty.
From each document only what's Solid Memo's of its kind is removed (Write discipline,
removeOwned):- a deck's cards, their distractors, its review states and the document's saying it's the deck's;
- a month's answers (
sm:Answer); - the preferences (
sm:Preferences); - the palettes (
sm:Palette,sm:ColorSet); - the digest's receipts, schedules and month summaries;
- the catalog's subjects (the catalog, its decks, groups, agents and distributions);
- the instance's
#it; - a draft's subjects and what they lead to.
A document holding another app's subjects too is kept with those alone, and the result names it (
keptDocuments), for an instance registered at the pod's root too. A document's ACL goes with it (the Solid Protocol has the server delete it). A document that's missing, or goes before the delete, counts as deleted.Anything else in the folder is another app's, and kept, as is every container on the folder's path. The releases published from the instance, which others may have added by their address, are kept too: those in
releases/, those the catalog links (sm:publishedRelease) in another folder of the instance, and any the catalog names as a deck's document. A notice (KeptFolderNotice) links the kept folder, says why it was kept (another app's files, or the releases,keptReleases) and how many documents were kept for another app's data. The delete's confirmation says both are kept. Data goes before registration, so a failure leaves the instance listed and the delete retryable.Every blocking server the end-to-end tests start (testing.md), and Pivot and Community Solid Server 8 (with LWS too), keep another app's file and its folder, and delete a folder holding only Solid Memo's documents with its access rules (foreignData.integration.test.ts). Solid-Nextcloud lists a folder's ACL among its contents, so there such a folder is kept, its access rules in it. What the advisory servers fail, and why, is in interop.md; this one is
nc-acl-member.Only an instance in the user's own storages (what
discoverStoragesfinds,isInStorages; a folder entered by hand isn't one) has its data deleted. Any other is someone else's, or a server's that may refuse or be gone: the picker doesn't offer the delete and says why, and the use case refuses it (instanceOutsideStorages) with nothing sent there. - each deck's cards and reviews documents as the catalog names them,
if they're the deck's: they say so, or they're in the instance's
own folder (below). A release (a document whose
-
Removing an instance from the list (
detachInstance) removes its registrations from every type index of the user's, as deleting does (below), and nothing else. An instance found in any of them is removed from all of them. It reads and writes only those indexes, so no request goes to the instance's server and it works whatever that server answers. Each index is tried whatever the others answer, and one that's missing has nothing to remove; a failure is reported once both were tried, and the list is read again either way.The picker offers it for every instance but a guest's own, which is on no other server and can only be deleted; the use case refuses to remove that one too. The data stays where it is, and attaching by its address brings the instance back; a new instance in that folder is refused (
instanceAlreadyThere).Once it's gone from the indexes, this page's credential gate no longer counts the folder as the user's, so reads there go as no one and writes are refused. A folder the user entered by hand still counts until the page reloads, as does the folder in another open tab. An instance's meta document is always read as the user, but once the instance is off the list, only attaching it again reads that document.
Creating an instance, adding one by its address or moving a guest's
study offers every type index of the user's they can read now
(getRegistrationOptions, readTypeIndexChoices in
typeIndex.ts), ranked
(rankedFor in
typeIndexChoice.ts). One
that isn't there, or that the user may not read (401, 403), isn't
offered. Any other failed read (a timeout, a server error) fails the
choices, as it may work when tried again: an index left out for it
would be offered as one to create. Each index of a kind is ranked in
this order:
- one that already holds a Solid Memo instance;
- the one the preferences file links (private only);
- one typed as its kind (
solid:UnlistedDocumentfor private,solid:ListedDocumentfor public) before one that says neither; - otherwise by address, never by the order of a profile's triples.
Three things move an index to the end of its kind. From last: a type
that says it's the other kind, a document linked as both kinds, and a
public index no one else can read. The best
private index is preselected as Recommended
(RegistrationTargetChooser.tsx).
A kind the user has none of is offered as one to create. The user may
enter any other type index of theirs by its address
(above). A target of a kind alone ("private",
"public") registers in the best index of that kind, or creates one
(ensureTypeIndex).
Each index is also read as no one (HEAD, readableByAnyone), and the
chooser says what may make it the wrong one:
- a public index no one else can read: other apps don't find what it registers;
- a private index anyone can read: everything it registers can be seen by anyone;
- an index typed as the other kind;
- one document linked as both kinds, offered once: who may read it is unclear.
Each public choice says what public means: anyone can see that the instance exists, its name and where it is, and who can open it is still decided by its access settings.
In the type index, the instance's one registration, by which Solid Memo finds it:
<#sm-inst-9f3c1a> a solid:TypeRegistration ;
solid:forClass sm:Instance ;
solid:instanceContainer <https://pod.example/solid-memo/main/> ;
dcterms:title "Japanese study" .
Earlier versions of the app wrote one more for each class of the
instance's data, titled with the instance's name, so a pod may still
hold them. Each index that registered the instance got dcat:Catalog
naming catalog.ttl#catalog, sm:Deck naming catalog.ttl (both
with solid:instance) and sm:Card naming decks/ (with
solid:instanceContainer). The private index alone got
sm:ReviewState naming reviews/, sm:Answer naming history/ and
sm:Deck naming drafts/. Their ids start #sm-cat-, #sm-deck-,
#sm-card-, #sm-review-, #sm-answer- and #sm-draft-:
<#sm-card-7a21d9> a solid:TypeRegistration ;
solid:forClass sm:Card ;
solid:instanceContainer <https://pod.example/solid-memo/main/decks/> ;
dcterms:title "Japanese study" .
meta.ttl makes a container self-describing: attach-by-URL reads it to
recover an instance that lost its registration. Deleting an instance,
or removing it from the list, removes the sm:Instance registration by
its container, and each one an earlier version wrote
by the exact IRI it names (<container>catalog.ttl#catalog,
<container>catalog.ttl, <container>decks/, <container>reviews/,
<container>history/, <container>drafts/). None is removed by what
lies under the container, where another app may have registered its own
data. A registration that registers something else too keeps it, and
loses only the link to the instance's data. Those an earlier version
wrote for an instance whose sm:Instance registration went some other
way stay, as the app no longer lists that instance to remove.
From Preferences, the user can remove those an earlier version wrote
for the open instance on the list, keeping the instance. "Old
registrations" is offered when an index holds any, never to a guest
and never on its own (removeOldRegistrations in
typeIndex.ts). It reads and writes
only the user's own type indexes, and takes a registration for one of
the app's old ones only when all of these hold:
- it's a
solid:TypeRegistrationfor one of the classes above; - it names that class's exact IRI for this instance, under either predicate;
- its id is in the index document, with a fragment that starts with
that class's prefix and a dash, such as
#sm-card-.
A registration that names the same IRI under another id stays: it may
be another app's. An sm:Instance registration is never removed or
changed, even one that also registers a class above. A registration
that names something else too loses only the link to the instance's
data. Each index is written once, with If-Match as above, and only
when it holds one. An index that can't be read is said to be so, and
isn't written.
<storage>solid-memo/<name>/ (default path; user-editable)
├── meta.ttl #it: a sm:Instance; dcterms:title; dcterms:created;
│ on an instance an earlier version's format
│ update made, dcterms:replaces and
│ dcterms:modified, ignored and kept;
│ sm:formatVersion 2
├── preferences.ttl #it: a sm:Preferences (created with the instance,
│ FSRS-6 its scheduler; an instance made before
│ has none until its first save, and reads as
│ SM-2): study caps, sm:answerScale,
│ sm:developerMode, sm:invalidDataPolicy, sm:theme,
│ sm:studyScheduler (sm:sm2 or sm:fsrs6),
│ sm:desiredRetention,
│ sm:schedulerInvitationDismissed, sm:palette
│ (a concept of sm:Palettes, or another IRI,
│ kept), sm:textSize, sm:formatVersion 6;
│ whether logging in skips the Connected
│ screen (sm:connectedScreenSkipped true,
│ outside the shape)
├── palettes.ttl the palettes the user designed, if any: one
│ sm:Palette per palette (#palette-<id>),
│ dcterms:title, sm:basedOn, sm:lightColors and
│ sm:darkColors, its sm:ColorSet subjects beside
│ it (#palette-<id>-light, #palette-<id>-dark),
│ a #rrggbb color for each role it sets;
│ sm:formatVersion 1 (docs/theme.md)
├── catalog.ttl one subject per deck (titles live ONLY here), a
│ sm:Deck and dcat:Dataset: sm:formatVersion 6,
│ dcterms:description, sm:studyDirection, optional
│ dcterms:creator/license, dcat:theme,
│ dcat:keyword (language-tagged),
│ prov:wasDerivedFrom, the deck's own study caps
│ (sm:deckNewCardsPerDay/MaxReviewsPerDay), and
│ for a course the chapters completed
│ (sm:completedChapter); the language its
│ card text (and a course's text) is shown
│ in first (sm:deckCardLanguage, outside the
│ shape); the hosts whose pictures it shows
│ (sm:deckPictureHost, outside the shape);
│ beside each deck its
│ dcat:Distribution (#deck-X-cards) and the
│ foaf:Agent nodes of its creators (#agent-…);
│ and the deck groups (#group-…), a sm:DeckGroup
│ and dcat:Catalog each: sm:formatVersion 1;
│ on the catalog, its drafts (sm:releaseDraft)
├── decks/<deckId>.ttl card corpus: one sm:Card per fragment (slow churn),
│ sm:front/back text and/or sm:frontImage/backImage
│ IRIs, optional sm:frontImageDescription/
│ backImageDescription (a picture's alt text),
│ sm:frontNote/backNote under each
│ side and sm:frontLabel/backLabel above it,
│ dcterms:subject (what it is about), the
│ release it was taken from (sm:fromRelease,
│ outside the card format), each
│ with sm:formatVersion; a retired card
│ (owl:deprecated true) is kept but not studied;
│ a card names its wrong options
│ (sm:distractor, and schema:suggestedAnswer),
│ sm:Distractor subjects beside it; a retired
│ one (owl:deprecated true) is kept but never
│ offered; the document itself (<>)
│ dcterms:isPartOf the deck's entry
├── reviews/<deckId>.ttl SM-2 state: one sm:ReviewState per card and
│ direction (fast churn) — #<cardId> front→back,
│ #<cardId>@back-to-front the other way — naming
│ its card (sm:reviewOf), its direction
│ (sm:reviewDirection) and sm:scheduler sm:sm2;
│ optional sm:previous* snapshot = state before
│ the day's first review (restored by "reset the
│ day"); sm:formatVersion 2. Beside it, once FSRS-6
│ has scheduled the prompt, its FSRS-6 state:
│ sm:scheduler sm:fsrs6, #<cardId>@fsrs6 or
│ #<cardId>@back-to-front@fsrs6, stability,
│ difficulty, due day, its own snapshot;
│ sm:formatVersion 1; the document itself (<>)
│ dcterms:isPartOf the deck's entry
├── history/<YYYY-MM>.ttl the answer log (below): one sm:Answer per grade
│ given in study or a course that month,
│ appended, never edited; sm:formatVersion 1
├── drafts/<name>/v<N>/ a draft of a release, linked from the catalog
│ (sm:releaseDraft): release.ttl, its root (the
│ draft deck, sm:formatVersion 1), agents, sources
│ and how it was made; chapter-<id>.ttl per
│ chapter; cards.ttl, the cards no chapter asks
│ ([below](#drafts-and-releases))
├── releases/<name>/v<N>.ttl a release published from a draft, linked
│ from the catalog (sm:publishedRelease): one
│ document, readable by everyone, never written
│ again (the user may publish elsewhere instead)
└── digest.ttl derived data (below): a sm:DocumentReceipt per document
(#receipt-<path>), a sm:DeckSchedule per deck
(#schedule-<path>) and a sm:MonthSummary per past
month of the answer log (#month-<path>), each
stamped with the versions it was learned from;
a path past 256 characters is named by its
hash instead, #<kind>~sha256-<hash>;
sm:formatVersion 1 (a receipt or a month
summary), 2 (a schedule)
A deck's documents are found through its catalog entry
(sm:cardsDocument, sm:reviewsDocument), never by name: an earlier
version's library upgrade moved them to decks/<deckId>-<uuid>.ttl and
reviews/<deckId>-<uuid>.ttl. Today's upgrade writes them where they
are (migrations).
A catalog, a type index and every link in them are untrusted data
(markdown.md). An address they name is used only
where Solid Memo keeps such documents, or, for a deck's documents, only
as they allow (below). The address and the folder are first taken as a
request sends them (new URL(…).href, canonicalUrlOf), which resolves
a dot segment (.., %2e%2e in any case) and spells the host and any
character outside ASCII one way. Then the address is checked to be in
the folder (isDocumentIn in
instanceLayout.ts; the
graph does the same). An instance written otherwise,
https://Pod.example/kortlekar-å/, keeps its decks, and a link that
climbs out of it doesn't lead there.
After the folder, an address may hold nothing a server might read as a step out of it, though a request leaves it as it is:
- a query or a fragment;
- a
;; - an encoded slash, backslash or percent sign (
%2F,%5C,%25); - a NUL, an overlong UTF-8 byte (
%C0,%C1) or a%uescape; - a segment that begins with a dot, or an empty one (
//, which a client may merge into one slash).
No document Solid Memo names has any.
-
A deck's documents are read wherever its entry names them. Their folders and names are free: a user or a tool may rename
decks/andreviews/, move the documents elsewhere in the pod, or lay the pod out flat, with the instance at the pod's root. A moved document's subjects are to name its new address. The app writes them as absolute IRIs, so a copy byte for byte still names the old one. Its cards and review states are then another document's subjects, which are never read as the deck's. Relative IRIs (<#card-1>) move with the document. A deck can be used when its entry is a subject of the instance'scatalog.ttland each document is at an address a deck's may be (isDeckInPlace,isDeckDocumentAddressin deckAddress.ts). That's plain http(s), with nothing a server might read as a step elsewhere (as above). It isn't a folder, an access control or metadata resource (.acl,.acr,.meta), or one of the instance's own documents (its meta, preferences, palettes, catalog and digest,history/,drafts/,releases/). It's in a guest's pod exactly when the catalog is: only a guest's own instance names that pod, which is this browser's (guest-mode.md). New decks are made indecks/andreviews/. One outside the user's own pod (their storages and the instances they registered) is read as no one, and nothing is written to or deleted there, whatever it says (writeOutsidePod, boundaries.md). Removing its deck, or deleting its instance, keeps it. One in the instance's storage that says it's the deck's is named as kept. In an instance from someone else's pod, only documents in the instance's folder are the user's: a deck whose documents lie elsewhere in that pod can be read only if they're public, and can't be studied. -
A deck's document is written to, or deleted, only when it says it is the deck's: the document states
<> dcterms:isPartOf <catalog.ttl#deck-X>, naming this deck's entry (ownsDocument; below). Anyone who may append to a document can state that, so the statement alone doesn't make a document safe to change. It counts only for a document in the instance's folder or in the storage the instance is in. When one of the user's storages holds the document or the instance, that decides it: both must be in the same one. Those are the storages their profile names (pim:storage), or else the storage's root the server shows above their WebID (discovery chain). Otherwise both must be under the same storage's root that the server shows (typedpim:Storage, or named by a Linked Web Storage server), with no other root between it and either of them. A folder that holds both isn't enough: a server may hold many users' pods under one root it doesn't type. Anywhere else it's unclaimed, whatever it says, and nothing is written to or deleted there for the deck. A deck whose documents are in another storage, even one of the user's own, is read-only until they're moved into the instance's storage. When the profile can't be read, or the pod doesn't answer for a folder on the way, a write fails and can be retried; the data check and a removal take the document for unclaimed that time. The storage rule doesn't tell who made the instance. So what keeps the rest of the document safe is what a removal takes out of it: only subjects that say nothing but what Solid Memo writes of a card, distractor or review state (below). A draft made from a release holds what others wrote, so it never keeps a statement that one of its documents isdcterms:isPartOfanything (draftEntries). A release (<> a sm:Deck) is never a deck's document, whatever it says, nor is a draft's own document in its folder: its release document,cards.ttlor a chapter's. It's unclaimed, and claiming leaves it as it is (isDeckItselfin ownership.ts andisDraftDocumentin deckPlace.ts). -
An older document that doesn't say so (from an earlier version, a repair or a copy) is the deck's in the instance's own folder. That folder isn't the instance's own when it's the root of a pod or a storage, or a folder above one. Such a root is one of the user's storages (as above), which a server may leave untyped, or a root the server shows (typed
pim:Storage, or named by a Linked Web Storage server). In the instance's own folder the next write states it. When the profile can't be read, a write fails and can be retried. The data check and a removal then read the document, and take it for unclaimed unless it says it's the deck's. One that names any other catalog's entry (such as a nested instance's) isn't the deck's: the app never adds a second owner on its own, and refuses the write (deckDocumentUnclaimed). The data check doesn't read a document in the instance's own folder to list it as unclaimed; it leaves one out once it has read it and found it isn't the deck's, and a repair makes the same decision. The folder is asked once a session; when the pod doesn't answer (an error or a refusal,cannotCheck), the write fails and can be retried, and the folder is asked again; the document isn't taken for unclaimed. A refusal before anything is sent,deckDocumentUnclaimedamong them, leaves a library upgrade saying nothing was changed. A document not yet made is made only in the instance's folder.Anywhere else the app never states it on its own: the document is unclaimed. The deck is read and studied, but each answer, edit or removal that would touch the document is refused with
deckDocumentUnclaimedbefore anything is sent, and removing the deck removes only its entry. The instance check names such a deck with its documents' addresses, in the data check and the Studio's Health screen, with "These are this deck's documents". Once the user confirms, each document is made to say it's the deck's: one write made only while it's as read (If-Match), or only where there's none (claimDeckDocuments;createDeckDocumentGuardindeckPlace.ts). The claim is only for documents in the instance's folder, or in one of the user's storages, as found at that moment, that holds the instance too (isInInstancePod). An instance attached from someone else's pod may name a document of the user's own, and writes to that document go out as the user. Any other document is refused (claimOutsidePod), and the deck is shown without the button. A document in the instance's storage that already says it's the deck's stays the deck's. Removing a deck, or deleting its instance, takes out a document's cards, distractors and review states only when every deck it names is leaving; otherwise only the leaving deck'sdcterms:isPartOfgoes (deckDocumentSubjectsinownership.ts). A subject goes only when it's a card, distractor or review state of Solid Memo's (not one of another scheduler) and says nothing else. Each class it states issm:Card,sm:Distractor,sm:ReviewStateor a distractor'sschema:Answer. Each property isrdf:type, one of the card, distractor, review state or FSRS review state shapes at any version,sm:formatVersion,sm:fromReleaseorschema:suggestedAnswer. A subject with any other class or property, Solid Memo's own too, such as preferences that also say they're a card, stays whole. Nothing they link to goes with them, and the document's own subject goes only when all it says is that it's the deck's. A failed read (refused, a server error, no answer, a download cut off) of a deck's document in the instance's folder stops the removal, or the instance's deletion, before the catalog is written. The entry stays, the error is shown, and trying again finishes it, a document already gone (404, 410) counting as removed. A deck's removal makes the new catalog before it deletes any document, so an entry, a distribution, an agent only the removed decks name or the catalog node a newer version wrote refuses it (writtenByNewerApp) with every document still there. A document outside the instance's folder may be anyone's and may never answer, so a failed read doesn't hold the deck back: it's kept whole, the result names it (keptDocuments), and the entry goes. The same holds for one the pod serves that can't be read as RDF. -
Any other deck is left alone. It isn't listed (
toDecksin deckMapper.ts), so nothing reads, writes or deletes through it, whatever the invalid data policy. The instance check reports its entry as not conforming (DeckPlace). Removing it there, like any problem with no repair, removes the entry from the catalog and no document it names. A deck handed to the adapters from anywhere else is held to the same rule: a write through it isdeckGone, with nothing written, and removing it removes only its entry (removeDecksin solidDeckRepository.ts). -
A draft the catalog links (
sm:releaseDraft) is one only at<instance>drafts/<name>/v<N>/release.ttl, in the instance'sdrafts/as a request sends it, with no dot segment, and with N a safe integer, so the address names the same draft again (draftPlaceOf). A name that's a dot segment is no draft's. -
A release the catalog links (
sm:publishedRelease) is listed only at an http(s) address named as a release is,…/<name>/v<N>.ttl, written as a request sends it, like the folder it's published in (studio.md). That address has no empty segment (//) and no user info (isPublishedReleaseUrl). It's made public again only when the catalog lists it, its document is a release, and it's in the instance or in a storage of the user's that holds the instance. An instance attached from another's pod may list the user's own. Its next version, written into the instance, is made from it read as the user only by the same place rule, and from it read as no one otherwise. So is a draft made from a deck, from the deck's cards, and so are the deck list's counts and the format update's plan, from a deck's cards and reviews documents. The digest keeps nothing of a deck unless both are the instance's.
Reading a whole deck is one GET (the N+1 problem: Solid servers have no batch requests or SPARQL), and a study session never rewrites card content.
graph LR
accTitle: An instance's documents
accDescr: A deck in the catalog links its creator, its distribution, its cards document and its reviews document, and each review state points to its card.
C["catalog.ttl#deck-X<br/>a sm:Deck, dcat:Dataset<br/>dcterms:title, dcterms:description<br/>sm:formatVersion<br/>sm:studyDirection<br/>sm:cardsDocument<br/>sm:reviewsDocument"]
A["catalog.ttl#agent-…<br/>a foaf:Agent<br/>foaf:name, foaf:mbox"]
X["catalog.ttl#deck-X-cards<br/>a dcat:Distribution<br/>dcat:accessURL"]
C -->|dcterms:creator| A
C -->|dcat:distribution| X
D["decks/deck-X.ttl#card-N<br/>a sm:Card<br/>sm:front / sm:back<br/>sm:frontImage / sm:backImage<br/>sm:formatVersion<br/>owl:deprecated (retired)"]
R["reviews/deck-X.ttl#card-N<br/>reviews/deck-X.ttl#card-N@back-to-front<br/>a sm:ReviewState<br/>SM-2 fields<br/>sm:reviewDirection, sm:scheduler"]
C -->|sm:cardsDocument| D
C -->|sm:reviewsDocument| R
D -.->|the document: dcterms:isPartOf| C
R -->|sm:reviewOf, else the same fragment id| D
-
The catalog holds one subject per deck with its title and links to the two documents, so the deck list renders from one fetch. A deck's title and description are language-tagged text, one value per language, in any language the user states since deck format 5 (format 4 required English; i18n.md). Since deck format 3 a deck is a DCAT dataset (
dcat:Dataset, vocab.md, validation.md):- It always has a description (
dcterms:description): what it covers and where its content came from. It's shown on the deck page, its URLs as links. A deck without one gets"Flashcards: <title>."@enand"Kortlek: <title>."@sv(app-written text for any title). A title too long for the description to fit the bound on a term is cut short in it, with an ellipsis after it (migrations.md). - It may name its authors (
dcterms:creator), each afoaf:Agentnode#agent-<slug>beside the deck, withfoaf:nameand amailto:foaf:mbox, shown asName <email>. Only a bare address counts as the email: one with,,;,?,#,%or&in it leaves the whole author a name, shown without a link. A subject that also has another class a shape describes, as a deck itself does, names no author: the app shows the author's address. The slug is the author folded to ASCII,unnamedwhen nothing is left of it. An author the folding loses letters or digits of, such as 김민수 or "Kim 민수", or that has none to lose, such as "—", gets six hex digits of a hash of the whole author after it (#agent-unnamed-5a5e6e,#agent-kim-ad54ba). Two such authors stay two agents. Every deck of the catalog names its authors' nodes, so a node that already holds another name or email is never written over. An author whose slug another author holds, such asJane Doe (jane example org)besideJane Doe <jane@example.org>, gets the hash after the slug instead (#agent-jane-doe-jane-example-org-<hash>). When that node is taken too, a count follows the hash: the lowest whose node is free or holds that author. The counted nodes of one such name are looked at once for all the authors that share it, so the time grows with the authors and the nodes, not their product. A node's URL, joined from the document and the name, can be longer than any term, so the app keys it by its pieces (TextMapinpathKeys.ts) and refuses to write a deck or draft that would hold one. An agent is read by the IRI the deck names (one written under an older rule is replaced on the deck's next save). A deck save, rename, import, format upgrade or removal takes out the agent nodes no deck names any longer, but only Solid Memo's own. Another app's subject at an#agent-…fragment stays, and of Solid Memo's node only its agent statements go. A node that lost Solid Memo's format stamp counts as another app's, so it stays too. - It may name a license (
dcterms:license, a URL), topics (dcat:theme, concepts of the topics scheme) and keywords (dcat:keyword), language-tagged since deck format 6, several per language; untagged ones saved before are kept, their language unknown. - No shape bounds how many authors, topics, keywords or languages of
its title and description an entry holds, or how long they are, and
the catalog is read and written whole. So the app keeps at most
MAX_DECK_METADATA(100) of each: authors, topics, languages of the title, of the description and of the keywords, and keywords in one language. It keeps at mostMAX_DECK_KEYWORDS(1,000) keywords in all, and at mostMAX_DECK_METADATA_CHARACTERS(65,536) characters of them all together, the first language of the title and of the description always, as the shape requires both (withBoundedMetadata, deck.ts). All are far more than any deck indecks/has. Past the bound it keeps the first values that fit: the title's languages, the description's, the authors, topics and keywords, in that order and in their stored order, and a keywords' language only with a keyword. A release's content, a deck file's import, a new entry, an upgrade and a read keep them so. Every write of an entry leaves out what it held past the bound, so an entry saved before holds it until the deck is next saved. - Its cards document is its
dcat:distribution(#deck-X-cards, withdcat:accessURL). - A deck copied from the deck library, or from a
release added from a link, names the
release it came from with
prov:wasDerivedFrom(dcterms:sourcebefore format 3), wherever that release is; it's read, never written. A link the URL parser doesn't take reads as none, so the deck is a copy of no release, and the next write of that deck's entry leaves the link out.
Agents no deck names any more go with the deck that named them. The Studio edits the authors and the license (
setDeckProvenance, deckProvenance.ts). Two authors that would share an agent node are refused, and a license is one ofKNOWN_LICENSES(license.ts) or the one the deck has. - It always has a description (
-
Card sides: each side is text (
sm:front/sm:back, a literal), a picture (sm:frontImage/sm:backImage, always an IRI; a string there is ignored) or both; a side with neither makes the subject not a card. A side's text is language-tagged, one value per language (zxxfor codes, numbers and symbols), or, as saved before card format 5, one untagged literal of unknown language, never both; untagged text is kept only while untouched. A note under a side (sm:frontNote/sm:backNote) and the label above it (sm:frontLabel/sm:backLabel, the front's since card format 6) are language-tagged text in any language.Pictures are shown only when their URL is http(s). A picture may have a language-tagged description (
sm:frontImageDescription/sm:backImageDescription), read to whoever can't see it, in its place, while its side is asked, so it never gives the answer away. Without one it's named by its side ("Picture on the front of the card").A card may say how its texts are written,
sm:textFormat(sm:markdownorsm:plainText, vocab.md), for the sides, the notes, the labels and the card's distractors, never the pictures' descriptions; without it the text is plain. A card copied from a library release keeps what it's about,dcterms:subject(card format 7, deck-library.md), which the app neither shows nor edits. Every edit and copy keeps both, an import or a course question joining the deck included. An edit trims plain text; text in any other format loses only the blank lines before it and the white space after it, so the spaces that start a Markdown code block survive.Wherever a side is shown whole (study, a library preview, a card's page, a library card), a tap, or Enter or Space on the button over it, enlarges its picture to the viewport's width or height, keeping its shape. Enlarged, a pinch zooms the picture, not the page, up to four times; a double tap zooms in on the spot tapped and another zooms back out; a drag moves it while zoomed in. Pinched out past its fit, it springs back. A single tap, Escape, throwing it up or down, the focus moving on or a scroll puts it back (ZoomableImage). In study, Space on a picture's button doesn't reveal the answer; a grade's key still answers.
-
Direction: a deck's
sm:studyDirectionis a concept ofsm:StudyDirections:sm:frontToBack,sm:backToFrontorsm:bidirectional(every card asked both ways). Formats 1 and 2 used the stringsm:direction, absent meaning front→back. It's changed in the Browser; a library deck brings its own. -
Study pace: a deck may set its own daily limits,
sm:deckNewCardsPerDayandsm:deckMaxReviewsPerDay, in place of the instance'ssm:newCardsPerDayandsm:maxReviewsPerDay; a limit it doesn't set follows the preferences. -
Card language: a deck may name the language its card text is shown in first,
sm:deckCardLanguage, one lower-case language tag. Its fronts, backs, notes, labels, picture descriptions and wrong options then rank that language ahead of the app's; a card without text in it shows as usual (i18n.md). On a course's deck it ranks the course's text too, on the course's own screens: the course's title and description, its chapters' titles and descriptions and its steps' theory. The keywords, and a plain deck's title and description, don't follow it.Like
sm:positionandsm:completedChapterit belongs to no shape (DeckV6is unchanged). Every other write of the deck keeps it as the entry has it (withDeck), so a deck read before it changed can't undo it. OnlysetCardLanguagesets or removes it, on the entry as it is then (If-Match), ascompleteChapteradds a chapter. A new entry (an import, a guest's deck moved) is written with the deck's, and a reader drops a value that names no language. It's chosen from the languages its cards state, and a release drafted from the deck leaves it behind.The study pace and the card language are set on the deck's own Preferences page (
#/deck-preferences, from the deck's page). A library release never sets them, and a library upgrade keeps the copy's. -
Picture hosts: a deck copied from a release outside the library's index shows a card's picture only from a host the learner chose for it (privacy.md). Each is one
sm:deckPictureHost, as a URL writes it with any port that isn't the default. Likesm:deckCardLanguageit belongs to no shape, every other write of the deck keeps it as the entry has it, and onlysetPictureHostadds or removes one, on the entry as it is then (If-Match). A new entry is written with the deck's, a reader drops a value that's no host, a library upgrade keeps them, and a release drafted from the deck leaves them behind. A release never sets them: reading one doesn't read the term. In a catalog outside the learner's own pod the term isn't believed, as that pod's owner writes it, and nothing is written of a choice there. -
Format versions: every subject the app writes carries
sm:formatVersion, the version of its class's shape it conforms to. The instance is at 1, decks at 3 (DCAT), cards at 2 (pictures), review states at 2, preferences at 6 (the palette and the text size) and deck schedules at 2 (the scheduler). The catalog, agent and distribution nodes, and a palette of the user's own and its color sets, are at 1. Readers treat a missing version as 1, read older versions as they are, and pass a newer one through unchanged. Bringing a pod up to date is the user's call (migrations.md). A developer can check an instance against the shapes in the browser. -
Cards are hash-fragment subjects (
#card-<uuid>, or the library's own ids such as#swedenfor imported decks) inside one document per deck. Fragment ids are generated once at creation and never re-derived. A card's id is its fragment, so only the document's own subjects are its cards (ownSubjectsOfin records.ts). Their address is spelled exactly as the deck's entry spells it, where the app writes them, or as the document is fetched, as a relative IRI such as<#card-1>is read. A fragment at both is the one the entry spells. A subject at another document, or at another spelling of the same address (another host case, the default port, a dot segment), is never read as a card, though it shares a card's fragment. Card edits and removals never reach it. -
Review state lives in a separate document per deck, one subject per card and direction:
#<cardId>for front→back (as was every state written before directions existed), and#<cardId>@back-to-frontfor the other way. Since vocabulary 1.16 every state the app writes says what it's of:sm:reviewOfnames the card (<cards document>#<cardId>),sm:reviewDirectionthe direction (sm:frontToBackorsm:backToFront) andsm:scheduler sm:sm2the algorithm of its fields. A reader joins a state to its card in reviewStateMapper.ts and reviewRecord.ts:- What the state says wins. The card is the one
sm:reviewOfnames and the direction the onesm:reviewDirectionnames; what the state leaves out comes from the fragment rule above (no@back-to-frontsuffix: front→back). A state another app named#state-7f3ais read when it names its card, and#card-1naming card 2 is a state of card 2. - A link into a cards document the deck had names its card too
(an earlier library
upgrade moved the cards).
sm:reviewOfinto any document beside the cards named<deckId>.ttlor<deckId>-<…>.ttlis read by its fragment. The state's next write names the current cards document. - What isn't read: a subject that isn't the reviews document's
own, by the cards' rule above, whatever it says, which removing a
card leaves too. A state whose
sm:reviewOfnames a subject outside the deck's cards documents (another deck's card, or the document's own subject). Nor one whose direction is neither way (saysm:bidirectional), or of another scheduler: any value ofsm:schedulerbut thesm:sm2andsm:fsrs6IRIs, a literal too. Absent means SM-2. Another scheduler's state is never read, written over or removed, the check only warns about it, and the app schedules the card beside it. - An FSRS-6 state is the app's own (vocabulary 1.21): an
sm:ReviewStatenamingsm:scheduler sm:fsrs6and nothing else, beside the SM-2 state of the same prompt. The app keeps that one up to date on every review, whichever scheduler sets the due days (srs.md). It's read by itssm:reviewOfandsm:reviewDirectionalone, which its shape requires, and written at#<cardId>@fsrs6(front→back) or#<cardId>@back-to-front@fsrs6, from which the fragment rule reads no card. One per card and direction counts, by SM-2's rule (the one at the subject the app names for it first), and only while fresh (the SM-2 state has the samesm:lastReviewedAt). A stale one (an older app graded SM-2 alone, the day was reset, the card forgotten) and an orphan (no SM-2 state beside it) set no due day; the next review under FSRS-6 replaces it, estimated from the SM-2 state. A change to the SM-2 state that keeps its last review goes unseen. An older app's Set due date in the Studio moves the SM-2 due day alone, and under FSRS-6 the FSRS-6 due day still counts until the card's next review. - One state per card and direction. Where several are of the same, the one at the subject the fragment rule names counts, else the first by subject IRI (code-unit order); the others stay, unread.
- Writing a state goes onto the subject read for it, so a review
of another app's
#state-7f3aedits it in place. A state not yet in the document goes to the subject the fragment rule names, unless that subject is another's (another card's state, another scheduler's, any other app's subject) or is too long. A card id that fills the card's address, as a deck file or release can carry, makes the named subject, with@back-to-frontand@fsrs6after it, longer than a term may be (write discipline). Then the state goes to a new#review-<uuid>that names its card, and is read and written there from then on. A subject the fragment rule names for the same card and direction that can't be read (half a snapshot, say) is written over. An FSRS-6 state goes the same way, to the subject named for it. A grade under FSRS-6 writes both states in the one PATCH it makes under SM-2; under SM-2 the FSRS-6 state is left as it is, and goes stale. foreignData.integration.test.ts reviews, on real servers, a state another app named its own way, beside another scheduler's state. - Resetting the day removes only the state read for each card and direction it undoes; a second state of the same stays, and is read from then on. FSRS-6's states of the day go back in the same save: restored to their snapshot, or removed when introduced that day or without one (srs.md).
Card edits and review updates never touch each other's documents.
- What the state says wins. The card is the one
-
Cards and reviews documents are created lazily on first write. Deck removal deletes both documents and the catalog subject. Card removal removes every
sm:ReviewStateof the card, both ways and read or not (SM-2's bysm:reviewOfor the fragment rule, FSRS-6's by their links), and no other subject (another scheduler's state stays). The Studio's edits do the same (studio.md), as does a card moved away or forgotten (applyReviewChangeswithevery). -
The cards and reviews documents say whose they are. Every write of a deck's cards or reviews document by the deck's own operations adds
<> dcterms:isPartOf <catalog.ttl#deck-X>once, on the document's own subject, never on a card or a review state. Those operations are:- import;
- adding, editing or removing a card, and stating its languages;
- an answer, and a day reset;
- a course's question joining the deck;
- the format update's rewrite of outdated cards and states;
- a library upgrade's write of the cards and states;
- a guest's deck added to an instance.
It tells Solid Memo it may change the document (above). An import or a library upgrade reads and writes the cards and states as without it, and a release is never written. A repair from the data check and a copy of the instance (a guest's study moved into a new instance) leave the document as it was. One untouched since vocabulary 1.16 (a reviews document, since this version) doesn't say it yet. Another
dcterms:isPartOfthere stays (another app may point two decks at one document). One naming another deck's entry is added to only when the user claims the document for this deck too. The subject has no class, so no shape checks it. When it says no more than that, it's Solid Memo's (isDeckBackLinkin ownership.ts), and the data check doesn't list it as a stray.
An instance's URL is permanent, and so is every document's and subject's in it: the format update and the library upgrade write the documents where they are, and change no registration: the format update writes nothing outside the instance. Another app may keep a link to the instance, a deck, a card or a review state.
catalog.ttl#catalog is a dcat:Catalog (shape CatalogV1) of the
instance's decks. It has a dcterms:title (the instance's name), a
dcterms:description and a dcterms:publisher: the pod owner's WebID,
described in the same document as a foaf:Agent with their profile's
foaf:name. Its dcat:themeTaxonomy names the topics scheme and the EU
data themes, and its dcat:dataset each deck. It may state a license
(dcterms:license), which the document then types a
dcterms:LicenseDocument, as DCAT-AP asks; a license it no longer
states loses that type.
Saving a deck adds only that deck's link, and removing a deck removes
only its own. A dataset another app listed in the catalog stays listed
through every deck save and every write of the whole catalog. The one
link a whole write drops is one to a subject of the catalog's own
document that's no dcat:Dataset, left by a deck removed some other
way (it would fail DCAT-AP's class check). A member another app
described in the document keeps its link whatever its class; the check
only warns about it
(validation.md). A dataset in
another document isn't held to its class
(validation.md), and an
instance listing one stays valid on real servers
(foreignData.integration.test.ts).
A catalog is data anyone may have written, so the app reads at most
MAX_CATALOG_LINKS (1,000) decks of it, in the deck list and its
arrangement, the statistics and the format update as in the Studio
(catalogLinks.ts). Past that,
it reads none of them and says why (catalogTooManyLinks). So no deck
is added past it. A new deck, a copy from a link or a course, or a
deck file is refused before anything is written once the catalog has
that many (catalogFull). A guest's decks that would take it past
them are refused too (guestMergeTooManyDecks).
The same limit holds for its links to drafts and releases
(Drafts and releases). The deck list works out
the study counts of three decks at a time (getStudyCounts in
study.ts), each reading the
deck's two documents, so a long list never reads all of them at once.
The catalog is written when an instance is created, and by the format
update for an instance made before there were catalogs;
it has no registration of its own (Discovery
chain). A catalog that doesn't fit its shape is
invalid data, which no write replaces with another. The whole document
conforms to DCAT-AP, a course's deck typed schema:Course too
(Courses), and a test holds what the app writes to it.
The instance's name is in the meta document's dcterms:title, the
catalog's dcterms:title, and the dcterms:title of its registrations
in each type index. Its sm:Instance one names it in the instance
list, beside any an earlier version wrote for its data. Renaming it in
the Studio (renameInstance, studio.md)
writes them all, each document read and written again on a 412. A
catalog description the old name gave (defaultCatalogDescription)
follows the new name; one the user wrote stays. A name too long for that
description to fit the bound on a term is cut short in it, with an
ellipsis after it.
A deck's description, topics and keywords are edited in its Browser ("Describe deck") and on its about screen in the Studio, the keywords as one comma-separated list per language the user states. The description is required, as DCAT-AP asks. Only the keyword languages the user states in an edit are checked and stored in their canonical form ("iw" → "he"). A tag the deck already has is kept as stored, even one another app wrote that the app wouldn't accept from the user.
The user arranges the deck list into named groups that can nest. A group
is a subject of catalog.ttl beside the decks, a sm:DeckGroup and a
dcat:Catalog (shape DeckGroupV1), never a dcat:Dataset, listing
sub-catalogs with dcat:catalog and datasets with dcat:dataset, as
DCAT-AP allows. The order is Solid Memo's own sm:position (DCAT's
dcat:prev/next are series versions, and the library uses them as
such).
<#catalog> a dcat:Catalog ; …
dcat:dataset <#deck-a>, <#deck-b>, <#deck-c> ; # still every deck
dcat:catalog <#group-x1> . # the top-level groups
<#group-x1> a sm:DeckGroup, dcat:Catalog ;
sm:formatVersion 1 ;
dcterms:title "Languages"@en ; # one name, in the UI's language
dcterms:description "Deck group: Languages."@en, "Kortleksgrupp: Languages."@sv ; # generated
dcterms:publisher <https://alice.example/profile/card#me> ; # the catalog's
dcat:dataset <#deck-a>, <#deck-b> ;
dcat:catalog <#group-y2> ;
sm:position 0 .
<#deck-a> sm:position 0 .
- The catalog still lists every deck with
dcat:dataset; a group lists only its own members, and the catalog'sdcat:catalogthe top-level groups. An edit writes only the links to the decks and groups the arrangement places; a member link to a dataset or catalog in another document, or to one the app can't read, stays. - A deck or group is in one parent: the catalog (top level) or one group; a deck no group lists is at the top level.
- Positions count within one parent, decks and groups in one sequence, 0 first. Members sort by position, those without one last, in document order. The first arrangement of a level writes positions 0…n−1 for every member at that level; new and imported decks get none.
- An empty group stays until the user removes it; removing a group moves its members, in order, into its place in its parent.
- A group's description is generated:
"Deck group: <name>."@enand"Kortleksgrupp: <name>."@sv, written anew whenever an edit writes the group, unless it holds text the user wrote. A name too long for the description to fit the bound on a term is cut short in it, with an ellipsis after it, as in a deck's. The whole text an earlier version wrote still counts as the generated one. sm:positionon a deck and the catalog'sdcat:catalogbelong to no shape (DeckV6andCatalogV1are unchanged), so writing a deck or the catalog keeps them.
What isn't one valid tree is read as one, not refused. A link to
nothing, from a group to itself, or of the wrong kind (a dcat:dataset
link to a group, a dcat:catalog link to a deck) is ignored. A
subject the app reads as a deck is a deck only, even when it's also
typed as a group: it's never a group too, and its own links to members
are ignored. A node several parents list goes to the group with the
lowest URL, except a group the catalog's dcat:catalog lists, which
stays at the top level.
A cycle is broken by moving its lowest-URL group to the top level. A
group nested deeper than 16 groups (MAX_GROUP_DEPTH) is read at the
top level, with the groups it holds counting their depth from there.
The editor doesn't stop a move that nests a group deeper, so the next
read shows that group at the top level. A negative position counts as
none, and so does one larger than the app holds exactly (2^53 − 1):
the node sorts last, and a group written again is written without it,
or renumbered when its level is reordered. On a tie of positions,
decks come before groups, each kind in document order. A group in a
format newer
than the app's makes the arrangement read-only. So does, under the
"Set invalid data aside" policy (sm:blockSubject, the default), a
catalog or group that doesn't conform, or that check still running
(validation.md). A group the
app can't read is never edited: its members show at the top level, and
the catalog's dcat:catalog keeps its link.
Writing an arrangement. The screen sends an edit, not a finished
layout (DeckTreeEdit in
deckTree.ts). An edit moves a
node after a sibling, combines two into a new group, renames or removes
a group, or gathers decks at the end of a group (the Studio's bulk
move).
Keeping a guest's study grafts
new groups around decks the tree has at the end of the top level, a
no-op once one of its groups is there. The repository
(editDeckTree in
solidDeckRepository.ts)
applies the edit to catalog.ttl as the pod holds it then:
- read, apply, write once: what changed is written in one PATCH with
If-Match(write discipline); an edit that changes nothing sends nothing; - on 412 the edit is applied again to the document as it is now,
three attempts in all, so another tab's change is kept. A move names
its neighbor, not an index, and the screen mints a new group's URL
(
newDeckGroup), so an edit means the same on the fresh tree, and a retried combine is a no-op. An edit that no longer fits (its group or node gone) fails withdeckTreeChanged; - a PATCH, never a whole PUT: where the pod has no strong ETag, a PUT would undo what changed since the read;
- only the groups written and the catalog are checked before the
write (
checkWrite), so a deck set aside beside the one moved doesn't stop the move; - removing a deck removes it from every group's
dcat:datasettoo, in the same write; its siblings keep their positions, and the next arrangement closes the gap. A group a newer version wrote keeps its link, which reads as no member once the deck is gone.
Several decks at once. The Studio changes several decks in one write
of catalog.ttl (studio.md). A move into a group is one
gather edit, which leaves a deck already in the group where it is, so
a retry changes nothing. A
pace or a direction is one save of every entry (saveDecks). Removing
decks first removes their cards and review states from their documents,
deleting each document that then holds nothing else (one holding
another app's data too is kept, keptDocuments), then their entries in
one save (removeDecks). Either way the catalog document is rewritten
once for all the decks (withDecks, withoutDecks), not once per deck,
so a change to many decks takes time that grows with them, not their
square. A link of the catalog or of a deck group that is no URL the app
can write (another app may have written one) stays as it is, and the
rest of the links are changed around it. The same holds when the deck
list is rearranged: such a link is no member of the arrangement, and
renaming, moving or combining groups keeps it.
Any card may have wrong options, shown beside its back in a
multiple-choice question (courses.md). Each is an
sm:Distractor subject of the card's document, typed schema:Answer
too, with sm:formatVersion 1, its text (sm:distractorText) and,
optionally, why it's wrong (sm:distractorNote). The card names each
with sm:distractor and, since vocabulary 1.16,
schema:suggestedAnswer (below), in step through every
write of a card (bulk edits, moves, copies and imports, a course's
question joining the deck included). Solid Memo's card editor and the
Studio's card inspector edit them
(studio.md; the domain is
distractors.ts):
- A new one is written once it has text, as
#<card>-d<n>.nis one more than the highest such id of up to 15 digits the card or the release the deck came from has used, or the first free one after it. An id the release published is never used again (a learner's answers may name it,sm:chosenDistractor); one deleted before it was published may be. A card is never saved with two of one id, which would be one subject: a write of such a card, an imported deck file's too, is refused before anything is sent (writeDistractors). - Retiring one writes
owl:deprecated trueon its subject, and restoring it removes that. A retired one stays named by the card, is read marked retired (toDistractor) and kept by every write, and only a question's choices leave it out (choicesOf). - Deleting one removes its subject and the card's link to it, in the one write of the card, and only one the deck's release never published; one it did is retired instead.
- Each change is a write of the card (
updateCard): the card and its distractors are written, those it names no more removed unless another card names them (withoutUnnamedDistractors), and triples the app doesn't know kept (withDistractors). - A wrong option not in the back's languages is a warning in a pod's deck, never a refusal. It names the first three languages the option lacks, or has that the back lacks, and counts the rest.
- A card and a distractor never share an id. Both are subjects of
the cards document at their ids. A write of a card onto an
sm:Distractorsubject, or of a distractor onto ansm:Cardsubject, is refused before anything is sent (idTakenInDeck), and the deck is left as it was. - A distractor belongs to one card. A write that leaves a
distractor it writes named (
sm:distractor) by two cards is refused the same way (assertDistractorsOwnedOnce), so an upgrade never gives a distractor a card keeps to another card. Removing a card, or a distractor it no longer names, never removes one another card still names, nor any subject that isn't a distractor. A card'ssm:distractorlink to another card, or to a subject the app can't read as a distractor, leaves the card in its next write, and the subject it named stays. A link to an IRI that is no URL names no subject the app reads (getThingfinds nothing there), so the card and the rest of its document are still read. - A deck an earlier version left mixed up may have a subject typed
both
sm:Cardandsm:Distractor, or a distractor two cards name. A write of such a card is refused (idTakenInDeck) rather than made onto the other's subject. While another card names the subject as its distractor, removing the card that took it over, by hand or in an upgrade, removes only the card statements: thesm:Cardtype and the card properties (withoutCardSubject). The other card keeps its distractor and is editable again. A card may also name two distractors of one id, subjects of two documents, as only a document written by hand can. It still reads, and the document's other cards can be edited. A write of that card is refused (distractorIdRepeated), and so is an upgrade of its document to this app's format, which stays as it is until the user deletes one of the two (deleteDistractor, by position) and saves the card.
A course is a library release with an outline of chapters and steps. Its state uses the documents above and no new type-index entries:
- The outline stays in the release. Chapters and steps are never
copied: the app reads them from the release the deck's
prov:wasDerivedFromnames. - The deck holds only the cards answered. Starting a course writes
an empty deck. A question answered for the first time writes its card,
its
sm:Distractorsubjects and its first review state, under the release's fragment ids (#q-why-solid-1a,#q-why-solid-1a-d1), and itssm:textFormatwhen the release states one. The app reads onlysm:distractor; a write of the card adds or removes only theschema:suggestedAnswers that are its own distractors, so another app's stay.schema:suggestedAnswerbelongs to no shape, and only the copy in the pod states it, never a library release. Removing a card removes the distractors it names. - The entry says it is a course's deck. Starting a course types its
catalog entry
schema:Coursetoo, besidesm:Deckanddcat:Dataset, as its release is typed (Deck.course). The deck shape asks only that the entry be adcat:Datasetand isn't closed, so the deck format didn't move and every write of the entry keeps the type. A deck added from a guest's study and a deck file carry it, a file without the progress too. A copy made before the type lacks it; the library's index, or the copy's own release, tells it a course. - Completed chapters are on the catalog entry: one
sm:completedChapter <release#ch-…>per chapter whose final review was passed, kept by every write of the entry. It's added with an If-Match PATCH, three attempts in all, as a deck group edit is. A deck added from a guest's study (addDeck) gets the guest's completed chapters with its new entry, and the Studio marks a chapter not done, or restarts the course, the same way (setCompletedChapters), a write that passes the shape check. No shape bounds the values, so the app keeps at mostMAX_COMPLETED_CHAPTERS(1,000) of an entry, each URL once, more than any course has chapters. Past that bound, it first leaves out the values of no document of the course: the deck's release, and on an import its cards' releases too. Then it leaves out the oldest. So values of other documents never push a chapter the learner completed out. A read, a deck file's import and a new entry keep them so. An edit writes the values it keeps and those it adds in one go, by the same rule, a chapter it adds counted as the course's, and drops the values past the bound from the entry. - Answers go to the answer log, with
sm:answerMode. - Everything else is derived: a step is done when each card it's checked by has a review state, and a chapter opens when the one before it is completed.
# catalog.ttl
<#deck-x> a solid-memo:Deck , dcat:Dataset ; …
prov:wasDerivedFrom <https://solid-memo.com/decks/solid-fundamentals/v1.ttl> ;
solid-memo:completedChapter <https://solid-memo.com/decks/solid-fundamentals/v1.ttl#ch-why-solid> .
Vocabulary 1.18 and its shapes let a creator write a release in their own pod, as a draft, before publishing it (vocab.md, studio.md):
-
A draft is a container of the instance,
drafts/<name>/v<N>/(the version it drafts), holdingrelease.ttl: the release's root, the draft deck, which is the document itself (<>) as a release is its document. It holds the deck's agents, its distribution, its sources, how it was made (itsprov:Activitysubjects, license documents) and the series it describes;chapter-<id>.ttlfor each chapter: the chapter, its steps, the cards they and the chapter ask, and those cards' distractors;cards.ttl: the cards no chapter asks (a plain deck's, or questions not yet placed) and their distractors.
A subject keeps its fragment id in whichever document it's in, and moves with its place (a question moved to another chapter goes to that chapter's document); what names it names it where it is. A subject a document names otherwise isn't read as the draft's, and publishing the draft refuses it (
inPlaceInin releaseDraftMapper.ts). The names that count are those of the draft's documents:release.ttl,cards.ttlandchapter-<id>.ttl. Named otherwise is a fragment of another of them, one of them other than the release document, or the release document as a subject in the cards document or a chapter's. A fragment of a document's own address counts as named where it is, whichever document the draft gives that subject: what two documents state of one subject is read as one. A chapter's document left with nothing in it is deleted. Anything else in the container (isDraftDocumentNamein draftLayout.ts) is another app's, and left alone. Every id of a draft is letters, digits,.,_and-, starting with a letter or digit (DRAFT_ID), so a chapter's document is always in the draft's container. A draft whose documents name a subject otherwise is neither opened nor written (draftIdUnsupported). Nor is one whose documents state a subject the draft reads by its shape otherwise than its record writes it (draftHiddenValue), such as a second text in a language, or an integer or date-time not written as one. No editor shows the difference and no check sees it, but publishing would write it. A subject in a newer format than the app reads is refused as a newer app's (writtenByNewerApp), whose message asks for a reload. -
Links on the catalog.
sm:releaseDraftnames a draft's release document, andsm:publishedReleasea release published from the instance. Likesm:newcomerCourseon the library's catalog, they belong to no shape, soCatalogV1keeps them through every write. Only a link to a draft's place in the same instance is followed. A learner's app readssm:publishedReleasein a creator's shared catalog to find newer versions of a release it added from a link, only in the instance the release's address names, and only those links in it (deck-library.md). -
A draft is checked as a draft. Its deck, chapters and steps are checked against the draft shapes, which don't yet ask what only a published release needs; its cards and distractors as anywhere else (validation.md), on every write and in the instance's check. What no shape describes (how the release was made, its sources) is written as it is, and kept through every edit; the Studio's release screen writes it as the library's releases do (deck-library.md, studio.md). Of the classes another app gives a subject the draft reads by its shape, the draft keeps only those the subject's write would keep (shapes.md), so none of them stops an edit. The release published from it leaves the others out too. A draft names the release it was published as with
sm:releasedAs, and is then no longer edited. Ansm:releasedAsat an address no release can have (isPublishedReleaseUrl, as for the catalog's releases) is read as absent: the Studio neither links it nor asks it whether the release is public. Of several, one at a release's address is read. -
Writes follow the write discipline. Making a draft puts each document only where none is (
If-None-Match: *), the release document first, then links it from the catalog (If-Match, read and made again on a 412). A release document already there means the name is taken and nothing's written; the Studio tries the next name. Any later failure deletes what was written before the failure is shown, so no draft is left unlinked.An edit is one write of each document it changes, made only if the document is as it was read (
If-Match; a new chapter's document, only where none is). When one changed elsewhere, it's made again on the draft as it is then, three times in all. An edit made from a read that another edit has overtaken is refused (changedElsewhere). Each document an edit changes is one whole PUT,If-Match: Community Solid Server's in-memory store cuts text short after a PATCH, and node-solid-server stores a boolean a PATCH inserts as false. A server with no strong ETag gets noIf-Match, so there an edit made elsewhere meanwhile is written over.Deleting a draft removes its subjects from its documents, the release document last, deleting each document that then holds nothing else; subjects nothing of the draft leads to are another app's and kept with their document (
keptDocuments). Then it deletes the draft's container and the ones above it (drafts/<name>/,drafts/) where they're then empty, then the link. -
A release is frozen. It's written once, at library deck format 6, and describes its own series and publisher (deck-library.md).
assemblemakes a draft a release's text, with every subject moved to the release's address,@basethat address, and its release time set. Publishing assembles the draft from the read its checks saw, not from its documents read again. A draft's version names that read, never only its documents' ETags: a document read again is a new read unless the pod answers 304. A server can give no ETag, or the same one for other content, so ETags alone can't show the draft is unchanged. A read since, or an edit, makes publishing at that versionchangedElsewhere. -
Publishing a release (solidReleasePublisher.ts, studio.md) puts that text, as it is, at
releases/<name>/v<N>.ttlof the instance, or in another folder the user chooses, in one PUT only where nothing is (If-None-Match: *). A 412 isreleaseTaken, unless the document there states the same statements, itsdcterms:issuedanddcterms:modifiedaside, and no other draft of the instance names it: then publishing goes on from there. Next, only<release>.aclor<release>.acr(glossary), on the release's origin, gets public read and nothing else, and no other access control changes. Where a server names another one as the document's, such as the folder's, that one's left as it is and the release stays private. Then the catalog links it (sm:publishedRelease, If-Match, read and made again on a 412), and the draft names it (sm:releasedAs), If-Match on the version the draft was checked and assembled at (changedElsewhere). A failure after the PUT is finished by publishing again at the same address. The app never writes a release again, nor deletes it, and registers it in no type index: the catalog's link is how its author's releases are found.
Every grade given in study is kept for the statistics
(statistics.ts): activity by
study day, streaks, how well reviews were remembered, in all and month
by month (monthlyRetention), and the running total of prompts
introduced (introducedOverTime). How many prompts are new, young and
mature, and the reviews due ahead, come from the review states, not the
log (srs.md): a review state says only
where a card stands now, and the log is the history. Once a day has
answers, a strip above the deck list says what the day came to
(todayOf, statistics.md). The log is source data:
nothing could rebuild it.
-
One document per study month for the whole instance,
history/<YYYY-MM>.ttl(historyUrlOf, by the study day's month, so a day is never split). A year of statistics is twelve GETs whatever the number of decks; reading it again is a304for each month that didn't change. Only the month document's own subjects are its answers, by the cards' rule: a subject of another document, or at another spelling of its address, isn't one, and isn't removed as one. A document whose name isn't a month 01 to 12 of the daysshiftStudyDaykeeps in order isn't one of the log's (monthOfHistoryUrl). No read takes in a month after that of the day after tomorrow: no answer counted can be in it. The log's months are listed from one read ofhistory/alone (AnswerLog.months): a month's document is one of its own, so no folder below it is read. A month after that of the day after tomorrow is left out first. That day is by a boundary at midnight, the latest any gives, so the preferences aren't read. Then of more months than those ofCHART_YEARSand a year more (MAX_LOG_MONTHS) only the newest are taken in, since each month taken in may be read. A later month listed never pushes out an earlier one. A guest's study whose log has as many months isn't moved or added to a Pod (guestStudyTooLarge): some of its months might be left behind. The today strip keeps a summary of each past month in the digest. -
One subject per answer,
#answer-<time>-<random>(for one added from a guest's study, followed by the id of the deck it was added to; answer.ts). It names:- the deck's catalog entry and the card it was given to; either may since be removed, and a removed deck's answers stay, as a removed deck;
- the direction, and the SM-2 grade, whichever answer scale gave it;
- when it was given, and the study day it counts toward, fixed then so a later day-boundary change doesn't move it;
- the prompt's interval before (absent on its first answer, which introduced it) and after.
An answer to a course question says how it was given (
sm:answerMode sm:multipleChoice) and, when it was wrong, which wrong option was chosen (sm:chosenDistractor, the distractor in the deck's cards document). It's left out when that IRI couldn't be written: longer than a term may be, or not one Turtle writes as it is (chosenDistractorIn). A release's own address may be much shorter than the deck's, and the answer is logged without it. An answer given in study says neither, which means recalled. Since vocabulary 1.19 an answer may say how long it took, in milliseconds the app was shown. That's from the prompt to the answer revealed, or to the option chosen (sm:recallMillis), and from there to the grade (sm:gradeMillis), each left out above ten minutes. It may say the day the prompt was due before it (sm:priorDue, absent on a first answer), and the device's offset from UTC then, in minutes east of Greenwich (sm:utcOffsetMinutes). Each is optional, and an older app ignores them (migrations.md). -
The intervals and due day are those of the scheduler that set them. The grade is always the SM-2 quality, but the interval before and after an answer and the day it was due come from what set the prompt's due day then (
effectiveStates). Under FSRS-6 that's its fresh FSRS-6 state, else the SM-2 state its first FSRS-6 review is estimated from. The log's format doesn't change. -
Added without reading (
appendToDocument): one insert-only PATCH, with no precondition, since an answer names a subject no other writer does. Every server tested creates the document and its container when missing, and keeps every one of several concurrent inserts (e2e/pod/src/history.integration.test.ts). A guest's study added to an instance brings its answers the same way: a month's in one PATCH, or several where one would pass 64 KiB (appendAll). Each id is the guest's followed by the new deck's, so adding it again to the same deck changes nothing. Adding it to another deck (the guest's deck added anew) makes an entry of its own, never one naming two decks. A wrong option chosen that would be too long in the new deck's longer address is left out, not the answer. An answer to a card left out, whose IRI there would be too long, isn't added. -
After the review, not in its way:
recordReviewsaves the review state, then queues the answer, with its response times (statistics.md), to be added in the background. Each instance has its own queue, and another instance's answers never wait for a failed one. One that fails waits, with those of its instance after it, until that instance's next answer tries again, or something that reads or changes its log: the end of a study session in it, its statistics, resetting a day. An add the server hasn't answered within 10 seconds is given up and tried again later, which changes nothing if it was saved (APPEND_DEADLINE_MS). An answer refused before it's sent would be refused every time: by the write check (dataNotConforming), or for a term Turtle can't write as it is (unwritableTerm) or longer than a term may be (termTooLong). Only that answer is set aside, never logged, and those after it go on. So is one the pod refuses as a bad request (400, 413, 414 or 422) a third time. Any other failure, such as no answer from the pod, a failed login or a server error, is tried again: it says nothing of the answer, and those after it would fail alike. An answer still queued when the tab closes is lost; its review isn't. -
Resetting the day removes that deck's answers of the day (
removeDay: read, remove, save with If-Match, again on 412), and drops those still waiting to be added from the queue. Undoing an answer in a session removes that one answer by its id (removeAnswer, the same way), and drops it from the queue while it still waits there. A failed add may still have been saved, so only an answer no add was ever begun for is left out ofremoveAnswer(srs.md). An add given up on at its deadline that the pod saves only after the removal stays in the log. Nothing else removes answers. -
A card moved to another deck leaves its answers behind. A Studio move never rewrites the log: past answers keep naming the source deck and card, and in the target the card's history starts again, though its review state may come along. A copy's history starts in the target; the original keeps its own.
-
Read whole by the Studio (
loadAnswerLog): every month taken in (above), for a card's history, its lapses and the deck's leeches (studio.md). The statistics (getStatistics) read the months of their range. Both go through one cache (readLogMonths), which keeps each month's answers in the page with the version they were read at; a month is read again only once it changed (readMonthSince, a conditional GET). Months are read six at a time at most. A read adds to the cache and never replaces it; a month the log no longer lists is dropped (statistics.md). An answer counts only in its month's document. One whose study day is more than a day outside that month is left out (isOfStudyMonth; the day allows for the time zone), as is one whose study day isn't a real date. So is one outside 0100-01-04 to 9999-12-31, the daysshiftStudyDaykeeps in order (isOfStudyDayRange). A prior due day (sm:priorDue) that isn't a real date, or is outside that range, is dropped, and the answer kept. A read checks a number's datatype, not its range, so the numbers are bounded as they are read (answerFromRecord). An answer whose grade isn't a whole number from 0 to 5, or whose interval isn't a whole number of days, 0 or more, that a number holds exactly, is left out. An interval above the 36,500 days the app now caps at is kept: an answer written before that cap may carry one. A response time that isn't a whole number from 0 to ten minutes in milliseconds (MAX_RESPONSE_MILLIS), or an offset from UTC that isn't one from −840 to 840, is dropped, and the answer kept. A time from elsewhere then never makes a month's summary or the time studied anything but a number. The Studio names a deck's past answers by their card's id in its current cards document (deckAnswers), which a library upgrade may have moved. -
Checked in the full check only (validation.md), since the current month changes every session.
digest.ttl lets a visit skip what hasn't changed. It holds only what
Solid Memo learned of the other documents, each fact stamped with the
version (ETag) of the document it was learned from
(studyDigest.ts):
- a receipt per document: at that version it conformed to the shapes
(
sm:conformedTonames the rules, a hash of the shape files the site was built with) and/or nothing in it was in an older format (sm:latestFormat); - a schedule per deck, from given versions of its cards and reviews
documents: prompts due by study day (
sm:dueOnDay "2026-10-01 12"), prompts never reviewed, and the reviews and introductions of the day it was computed on. With today's preferences they give the deck list the same counts asbuildStudyQueue(srs.md). A review state whosesm:dueis no real day isn't counted on any day, and a schedule with asm:dueOnDaynot as its shape has it is dropped and computed again. It names the direction, the day boundary and the scheduler it was computed with (sm:scheduledWith, the preferences'sm:studyScheduler), and holds only while all three are the deck's and the preferences' (switching scheduler writes no review); - a month summary per past study month of the answer
log that the today strip looks back over, from a
given version of its
history/<YYYY-MM>.ttl(sm:summaryOf,sm:summarizedVersion). It holds each study day's answers, new cards, scored reviews and lapses (sm:studyDayCounts "2026-09-29 12 3 8 1"). It holds the month's reviews of young prompts and how many were remembered (sm:youngReviewCount,sm:youngRecalledCount), and how many recalled answers took each whole second (sm:recallSecondsCount "4 7", a minute or more counted at 60). The strip shows these and estimates the time left today from them (statistics.md). A summary needs no day boundary, and a month no longer looked back over is dropped. A summary is read only when itssm:summaryOfis a month's document, a path ending inhistory/<YYYY-MM>.ttlwith no query or fragment. Each of its days must be a real date of that month, or a day either side, given once, and its counts have at most 15 digits. Any other is left out, made again from the month's answers and written over the one in the digest.
sequenceDiagram
accTitle: Counting a deck through the digest
accDescr: The app reads the digest, then asks for each deck's cards with the version the digest holds, and the pod answers 304 when nothing changed or 200 with the document when it did.
participant App
participant Pod
App->>Pod: GET digest.ttl
App->>Pod: GET decks/d.ttl If-None-Match: <its version in the digest>
alt unchanged
Pod-->>App: 304 — counts from the schedule, no check
else changed (or no digest yet)
Pod-->>App: 200 + the document — counts and check from it
App->>Pod: PATCH digest.ttl (in the background)
end
- A stale digest is never wrong, only slow. Every fact is used only
after the pod says its document is still at the stamped version. A
document changed elsewhere is read and checked in full, and the digest
repaired with what that read learned; nothing else keeps it up to
date. A stored version is sent only as one entity tag of at most 512
characters. Any other counts as none, the wildcard
*among them: the document is read in full, and what that read gives replaces it. - When a study session ends (End session, leaving the screen, or the page being hidden) the deck's schedule and its reviews document's receipt are brought up to date.
- Writes are edits like any other (If-Match; write check). Changes learned while a write is under way go in the next one. On a 412 it's read and changed again, six times in all, waiting longer before each (50 ms, then 100 ms, …), since a page learning a check's documents writes the digest several times running. When the app or the pod refuses what a write says, its changes are written again one at a time, so only the refused one fails. Until one of them is written, when the pod refuses one alone with an answer it gave already, as it would every write over its quota, the rest fail with it. A failed write is dropped: the next visit learns it again. Each write is one edit of the document, made in time that grows with its subjects, not their square. What's dropped is removed from every subject it was read from, whatever that subject's name, as is any other subject that said what's written again, so none of it is read back.
- Only the instance's decks. A deck's schedule and its documents' receipts are kept only when both documents are in the instance, or in a storage of the signed-in user's that holds it (the place rule). So is a document's check receipt. An instance attached from another's pod may name the user's own documents as a deck's: the deck list's counts of such a deck come from its documents read as no one, and go into no digest. The study statistics read a deck's documents as the user, and the same rule, applied where a schedule is kept, leaves what they learn of such a deck out of the digest. An instance in a folder of the user's own storage that's shared with write access to someone else keeps the documents there in a digest that person can read too, as it keeps the instance's other documents.
- Read leniently. A subject that doesn't fit its shape is left out, and relearned. The digest isn't one of the documents an instance is checked by.
- An entry is written new. Each entry has a subject of its own
name in
digest.ttl, and a write replaces what that subject says, whether the app read it as that entry or not. Another class, a value the entry's shape doesn't have, or a newer format isn't kept, so none of it can stop the entry from being written. A value that's a blank node stays, as a write can't name one to remove it; the app neither reads it nor checks it, so it stops no write either. Unlike the instance's other documents, the digest doesn't refuse to write over an entry a newer version of the app wrote: the digest is derived data, so the newer version learns what it needs again on a later visit. - Read only for what an instance can have. A receipt is read only
for an address a document may be read at, and a schedule only for a
deck of the instance's own catalog. At most one receipt is read for
each fixed document, two for each deck, at the catalog's limit
(
MAX_CATALOG_LINKS), and one for each of the drafts' documents, at their limit together (MAX_DRAFT_DOCUMENTS_IN_ALL), and one schedule for each deck. Any other is left out, and removed at the next write. A write keeps to the same limits: past them, the entries it didn't change go first, the earliest first, so a full digest still takes what a visit learns. - Changes don't copy it. What a visit learns is made in place to the page's own copy of the digest, and the changes a write takes along are made to one copy of what it read. Learning a fact of each of many documents takes time that grows with the digest and the facts, not their product.
- It is as good as the pod's ETags. Community Solid Server 6 stamps
its ETags in whole seconds, so a document changed elsewhere in the
same second as Solid Memo read it is taken for unchanged until it
changes again (7 stamps milliseconds). The same holds for
If-Match(below). - A pod without ETags gains nothing. node-solid-server (5.x, 6.0.0) gives no ETag on a read, so nothing is kept, and every visit reads everything.
- The format update doesn't write the digest; what it says of the documents it writes is relearned on the next visit.
The Studio saves a deck as a file, and makes a deck of a file
(studio.md): Turtle or JSON-LD, one deck
to a file. The domain names its parts
(deckFile.ts), and the
DeckArchive port reads and writes it
(solidDeckArchive.ts).
An export holds triples as the pod has them, at the pod's IRIs:
- the deck's entry in
catalog.ttl, its distribution and the agents it names as its creators, its card language (sm:deckCardLanguage) and picture hosts (sm:deckPictureHost) among them. A creator goes only when it's an agent as Solid Memo writes one: afoaf:Agentof no other class a shape describes or adds, and not the catalog (isCreatorAgentin ownership.ts). Another deck's entry, adcat:Dataset, the catalog or any other node named as a creator stays behind, and so does the deck'sdcterms:creatorlink to it. No subject that goes takes itssm:positionalong, nor itssm:completedChapters unless the progress goes too; - its cards (each
sm:Cardof its cards document) and the wrong options they name, retired ones too, with whatever another app said of them; - with the progress, the review states of those cards in its reviews document.
Nothing else of either document goes: a deck may name a document that
holds more than the deck. Each of the two documents is read as the user
only when it's the instance's (isInInstancePod), as a move or copy of
cards reads its source. An instance attached from someone else's pod
may name a document of the user's own. Any other is read as no one.
Nothing is rewritten: a deck still at an older format is exported at it.
A JSON-LD file is flattened: every subject is a node of its @graph,
and its @context is the prefixes the Turtle uses too (sm, dcterms,
dcat and so on), written in full.
An import reads the file as the pod is read, with the same mappers:
- the file must hold one deck (
sm:Deck) that fits its shape; - its cards are the cards of its cards document, its review states those of its reviews document, of cards it holds;
- an older format is brought up to date as it's read
(migrations.md), and the screen says how many parts
were. A deck, card or review state in a newer format than the app
reads is refused (
deckFileTooNew, notwrittenByNewerApp, which refuses to save over pod data a newer version wrote), and nothing is written; - a subject of these kinds that can't be read is left out, and the screen says how many were;
- relative IRIs are resolved against
https://file.solid-memo.invalid/and the file's name (DECK_FILE_BASE); - a JSON-LD context named by its address (or
@import) is refused, as reading it would fetch that address. The parser reads the document as the check saw it, so a key named twice is the last one for both, and its document loader fetches nothing; - a JSON-LD context below the top level (in a term's definition, or on
a node inside the document) is refused, as is a list of more than 8
contexts (
deckFileUnreadable). The parser applies a term's context again at every use of the term, and builds each context from a copy of all the terms before it, so a small file of such contexts holds the tab for minutes. A file this app exports states its context once, at the top; - a JSON-LD context that defines a term by more than an IRI (an object,
such as one with a
@container) is refused (deckFileUnreadable). The parser reads the values of some such terms, a@graphcontainer, in time growing with their square. A context may give only strings, for its terms and for keywords such as@vocab; a file this app exports states prefixes alone; - a JSON-LD
@baseor@vocabis refused (deckFileUnreadable) under the rule for a Turtle base. One whose path has a.,..or empty segment is refused. So are those a node's contexts declare when, with the file's own address and each resolved against the one before, they come to more than 512 characters. The parser walks the whole base for each relative IRI it resolves, and the IRIs it gives can be far shorter than the base, so the limits below wouldn't bound the time. A file this app exports declares neither; - a JSON-LD term or prefix is refused (
deckFileUnreadable) unless it's defined as a keyword or as an IRI with a scheme, a plain path and at most 512 characters. So are a node's contexts when their terms and values come to more than 4,096 characters together. The parser gives a term's IRI again at every use, resolving a relative one against the base, so a long one costs its length at every use, for an IRI that may be short. A file this app exports states short namespaces with a scheme; - a JSON-LD term,
@baseor@vocabis refused (deckFileUnreadable) when it's another term of the node's contexts, or a compact IRI whose prefix, the part before its first:, is one. The parser expands such a term through the other with no bound on how deep, so two terms defined through each other, or one through itself, never end. A term defined as one that names a keyword names that keyword too, which the checks below would read as a plain term. A file this app exports states each namespace in full. With the base bounded and each term defined in full, at most 512 characters, the limits below bound the time; - the parser reads the document as it streams, each object written again with its context first. A parser that held every node to the end would match each against every typed one, in time growing with the square of the nodes. It gets the text in parts of 4,096 characters, each in a task of its own, and no more after its first error, so a parse that fails leaves the tab free after the part it failed in;
- a JSON-LD keyword given a value the parser reports as an error is
refused (
deckFileUnreadable) before it's parsed, under an alias too. These are an@idthat's no string, or a second one in an object, and a@typethat's no string or array of strings. So are an@indexthat's no string and a@reversethat's no object or holds a keyword. So are an@includedmember that's no node object, a@nestmember that's no object or holds@valueor@id, and a@listbeside any key but@index. A@setobject's members, and an array's in it, count as members of the keyword it sits under. The parser reports such an error and reads on, and each takes it far longer than a triple, which the bound on the work below doesn't count. As with the checks below, it covers the whole document, a@jsonliteral too. A file this app exports holds none; - JSON nested deeper than 12 levels is refused (
deckFileUnreadable), before anything else reads it: the JSON-LD parser takes time far beyond linear in the depth, and a file this app exports nests 5; - JSON-LD with more than 4,096 values that make no triple, or that sit
in an array in another array, is refused (
deckFileUnreadable) before it's parsed. A value makes no triple when it'snull, an empty array or object, or a string, number or boolean where a node belongs, in@graph,@includedor the top-level array. A value object whose@valueisnullcounts, and the empty array of an@list, which isrdf:nil, doesn't. A@setobject counts as the array it holds, under an alias too. The values of an array in another array outside a list may make triples, but the parser takes the longer over each the deeper the arrays nest. JSON-LD writes no array in an array but for a list of lists, which counts neither. A file this app exports holds none; - a JSON-LD RDF-star annotation (
@annotation, or a term defined as it) or triple term (an@id, or a term defined as it, given an object or an array that holds one) is refused (deckFileUnreadable). The parser is also told to read no RDF-star: it holds the annotations of the top-level nodes to the end, copying all those before it at each, in time growing with their square. The check covers the whole document: a term one node's context defines as@idis refused given an object anywhere, even as a plain key of another node, and so are these keys inside a@jsonliteral. A file this app exports holds neither; - a Turtle triple term (
<<( s p o )>>), reified triple (<< s p o >>), annotation ({| ... |}) or reifier (~) makes the file not parse (deckFileUnreadable), with limits or with none. The parser is told to read no triple term, on either client. An annotation or a reifier gives one past that option, so the parse fails at the first triple that holds one. The parser would read triple terms nested a thousand deep, building each level, while the limits below count the triple that holds them once. A file this app exports holds none of them; - a file larger than
DECK_FILE_LIMITSinsolidDeckArchive.tsis refused (deckFileTooLarge), and nothing is written. The limits are 64 MiB of text, a million triples, and 256 Mi characters in the terms of those triples, which a prefix or a context can make far longer than the text. They leave a wide margin over a deck of tens of thousands of cards with progress, which the pod holds with no limit. A Turtle file is refused the same way when it declares its base more than 16 times or more than 4,096 prefixes. So is one whose base can grow past 512 characters or has an empty segment in its path. So is one with a.or..segment, but in a relative path with no colon. So is one with an IRI longer than 512 characters, in a triple or a prefix, that's relative or may hold a.or..segment, as written or escaped. The parser removes those segments as it resolves the IRI, in time growing with the square of its length. So is one nested more than 64 levels deep in collections, blank nodes, annotations or triple terms, which the parser holds memory for without making a triple to count. Its parse stops there, as it stops at the first triple past the limits. A declaration or a bracket quoted in a card's text doesn't count. So is a file with a term longer than 16,383 characters, as every document the app reads is, and a JSON-LD file with a string or key that long, which is refused before it's parsed. So is a JSON-LD file whose values take the parser more work than 26 units for each triple the limits allow, counted before it's parsed. Each value, an array element or object member, takes 8, or 2 when it's a string, number or boolean given to@id,@type,@value,@languageor@direction. A member under a key that's no keyword takes 2 more, and any other string, number or boolean 4 more. Every value takes 1 more for each container above it, and 4 more for each array it sits in directly in another, a@setobject counting as its array. The parser takes time over each value, whether it makes a triple or not, and the more the deeper it sits. A file this app exports takes some 20 to 30 for each triple, the more the more of its literals have a language or a datatype. So such a file may be refused with somewhat fewer triples than the limits allow, still more than a deck of tens of thousands of cards holds. A file of values that make few triples or none may still take the parser about half as long again as one of the most triples allowed. A release file the Studio opens is held to a release's limits (deck-library.md); - a triple with a term Turtle can't write as it is is left out (below).
The deck is then written as a new deck of the instance (importedDeck).
It keeps the file's deck id, so a deck exported, removed and imported
again comes back at its URLs, and the log's answers name it again. It
takes a fresh id when the instance has a deck by that id or one using a
document of that name, or when the id or its distribution's
(<id>-cards) is already a subject of the catalog. So does an id the
app wouldn't give (deck-…), so no deck lands on #catalog, a group
or an agent. Its
cards keep their ids.
Only what Solid Memo knows of the deck and its cards is written, as any
deck: triples another app put there are in the file, but not imported.
Each card names its wrong options with sm:distractor and
schema:suggestedAnswer, each typed sm:Distractor and
schema:Answer. Each review state names its card in the new cards
document (sm:reviewOf), its direction and sm:sm2. Its FSRS-6 states
come too, as the app's own; a state of another scheduler isn't
imported. The deck needs no type-index registration of its own
(Registrations). The writes follow the write
discipline: the cards document is created
(If-None-Match), the reviews document written, and then the deck's entry
added to the catalog, each checked against the shapes.
What the data model holds that Solid Memo's screens don't edit. Most of it's shown in Solid Memo; the Studio closes the gaps one by one.
- Edited in the Studio:
- a deck's authors and license, and its course progress (a chapter marked not done, the course restarted);
- the instance's name, and the catalog's description and license;
- a card's wrong options and review state (forgotten, or given a due day), and the deck a card is in (moved or copied to another);
- edits of many cards at once, and several library copies upgraded at once;
- a deck exported to a file or imported from one;
- a draft of a release: what it says of itself, a course's chapters, steps and questions and their order, and its cards' wrong options.
- Shown only:
- the answer log, as statistics, and in the Studio as a card's history, the wrong options chosen, lapses and leeches;
- the schedule in the digest, as counts, and in the Studio as a forecast;
- the check of the shapes, in developer mode, and in the Studio as a deck's or the instance's health;
- a draft's release check, and a preview of its listing in the library.
- Not shown: a catalog's
dcterms:modified, which the app keeps but never writes; a library copy's release provenance beyond its authors, license and sources.
-
Writes go only where Solid Memo writes. Every pod write passes the pod fence (boundaries.md), which refuses, before anything is sent, a write to an address that's unsafe to write: one a server might read as another, or an access control or metadata resource (
.acl,.acr,.meta). No access control is written but a release's own, by the release publisher (a resource without its own ACL inherits its ancestors' access; a malformed one replaces that inheritance and can lock the owner out (WAC) or expose data). Otherwise access control stays whatever the user's server dictates. -
No write holds a term Turtle can't write as it is. Such a term is an IRI with a control character, a space or one of
<>"{}|^`\. So is a blank node label or a language tag outside Turtle's grammar, a language subtag over 8 characters, which the pod's parser refuses, text typedrdf:langStringorrdf:dirLangStringwithout a language, or a quoted triple. So is text typedrdf:dirLangStringwithout a base direction or with one other thanltrorrtl, and a direction on any other literal. JSON-LD can hold such a term, and the writers don't escape it, so a>would end an IRI and the rest be read as statements no check saw. A JSON-LD value with a@directionbut no@languageis such a term too. A PATCH, a PUT, an insert-only PATCH, a release's Turtle and an export are refused withunwritableTermbefore anything is sent (writableTerms.ts). An imported deck leaves such triples out; a release read from a file is refused, as a draft keeps its triples as they are. -
No write holds a term longer than 16,383 characters, as no read accepts one (deck-library.md). The write is refused with
termTooLongbefore anything is sent. A write gives a blank node 32 characters of room for the prefix a parser puts before its label (isTermTooLong). A Turtle read gives each blank node a short label of its own (blankNodeNamer), so the label it writes back is short and doesn't grow with each save. A JSON-LD read keeps its labels and writes them back as they are, so it holds a label to the bound with the same room as a write (BlankLabels). Either way, a term a read keeps never blocks a later save of the whole document, and what the app writes it can read again. A record brought up from an older format in memory is held to the bound as it would be written, and one that would pass it is read as not fitting its shape (migrations.md). A document saved before the bound may hold a longer text, such as a card's back, a step's theory or a catalog entry's keywords. Its read now fails with aReadLimitError. The app has no way to shorten the text, so it has to be edited outside the app. -
What is read can be written back. An IRI that
new URLrefuses, such as<http://[x>, is still an IRI to the Turtle parser, but the client library writes no such IRI. So no value the app reads into its models holds one (readIrisin records.ts): a deck's theme or source, a card's release or subject, a draft's field, or the catalog's publisher, which a new deck group takes. The next write of a subject leaves such a value out, but a value the write keeps stays as it is (setIriAll): a link of the catalog or of a deck group, a deck entry'ssm:completedChapter, and a card'ssm:fromRelease. A draft that states one is refused as one that states a value otherwise than the Studio reads it (draftHiddenValue), so it is never published with it. A literal with a base direction (RDF 1.2,"…"@ar--rtl) that another app wrote is kept with its language and direction, and written back as it was read, in a PATCH and in a PUT alike (graphsOf). A Studio draft keeps it too, as it is edited and published, and so does a deck's export, in Turtle and in JSON-LD (@direction). The app writes no direction of its own and reads no such literal as text in a language. -
A date is written as
xsd:dateTimespells it. A year past 9999 or before 0 has no plus sign and no leading zeros beyond four digits (xsdDatetimeinrecords.ts), as12345-01-01T00:00:00.000Zor-0001-01-01T00:00:00.000Z. So a date the app read is written back and passes the write check. -
Mutations always follow read → modify → save (datasets.ts:
readDatasetorgetSolidDatasetOrNull, thensaveDataset). The save sends a PATCH of the delta, or for a large edit one PUT of the whole document as read and edited (below), so unknown triples survive. Only brand-new documents are saved fromcreateSolidDataset(). The one exception is the answer log: answers are added unread, with an insert-only PATCH. -
An edit of many subjects is made to the dataset at once. Such edits are a release's cards written, cards removed, the deck groups and positions of a rearranged deck list, and cards, catalog entries and review states brought to this app's format (
setThingsandremoveThingsin client/rdf.ts,editOfin datasetEdit.ts). A subject at a time would copy the whole document at each, in time growing with the square of its subjects. A list of values of one subject, such as a card's distractors or the catalog's links to its decks, is set in one call too (setIriAllandsetStringAllof a subject's builder). An add at each value would copy the list so far. The edit and its save then take time that grows with the document. -
A card moved to another deck in the Studio is written afresh in the target with only what Solid Memo knows of it. Its subject and its wrong options' are removed from the source, triples another app put on them included. A copy leaves those triples in the source and doesn't carry them over.
-
A palette's color set is written afresh too, with only its colors: its shape is the one closed shape, so a triple another app added would have every later save refused. It's written only at a subject that's a color set and nothing else, which no other palette names (theme.md). For the same reason, a palette, and any other subject written through
recordThing, drops the color set's class if another app gave it one. It drops every other class that isn't its own and that a shape, or the DCAT-AP profile, asks something of (shapes.md). The checked edits that change a subject in place drop them too: a deck's card language or completed chapters, the deck tree's catalog on any edit of the tree, and the preferences when the Connected screen is marked seen. The deck tree leaves a catalog a newer app wrote as it is when the edit leaves its links alone. A class no shape asks anything of stays, up to the number of classes the check reads a subject by; the ones past that go too, and so does a value ofrdf:typethat is no IRI. -
Every write states what it expects to find, as an HTTP precondition:
- an edit is sent with
If-Match: <the ETag the document was read with>; if the document changed since, the pod answers 412 and nothing is written. An edit is a PATCH, or one PUT of the whole document when the PATCH would be larger than 64 KiB (a PATCH larger than 100 kB fails on node-solid-server, and a format update of a large deck exceeds it). WithoutIf-Match(no strong ETag, below), such a PUT undoes a change made elsewhere since the read. Two edits are always one PUT (saveDataset'swhole): stating the language of a deck's untagged card sides (stateCardLanguages), and the Studio's bulk edits of cards (editCards, studio.md). Community Solid Server's in-memory store cuts a document short after a PATCH holding text beyond ASCII. A save of the preferences is always one PUT too, since node-solid-server stores a boolean a PATCH inserts as false (the preferences hold two, the developer settings and "Not now" to switching to FSRS-6); - a creation is sent with
If-None-Match: *(by the Solid client library, behindclient/resources.ts, for datasets and containers, by the copier for files); had something appeared there meanwhile, 412; - deleting a document read before sends
If-Matchtoo. Every removal of Solid Memo's data from a document (deleting an instance, a deck or a draft, or taking back what a failed creation wrote) goes throughremoveOwnedindatasets.ts. It has a rule for what of each kind of document is Solid Memo's (ownership.ts). It reads the document afresh, takes out Solid Memo's subjects of that kind, less any a newer version of the app wrote, and the blank nodes only they name. It deletes the document only when nothing else is left in it; otherwise it writes back what's left: a PATCH ofDELETE DATA, or, where a blank node goes, one PUT of the rest, eachIf-Matchits read. A document that isn't RDF, or holds nothing of Solid Memo's, is kept and nothing is sent. On a 412 it reads and removes again, once; a second 412 ischangedElsewhere. Where the pod gives no strong ETag, the delete and the PATCH go withoutIf-Match; a PUT, or a PATCH too large to send as one, isn't sent, and the document is kept as it is. A deck's cards or reviews document is removed from only when it's the deck's (where an instance's documents are). A deck another tab adds meanwhile is missed, and keeps the folder in place.
An edit or a delete is matched to its read by the document's address as a request sends it (
isSameUrl), so one spelled another way than the pod answered with still carries theIf-Matchof that read.A 412 surfaces as a
PreconditionFailedErrornaming the document ("changed elsewhere … Reload and try again"). Nothing retries on its own, except the writes that re-apply a change to the document as it is then:- the digest;
- an edit of the deck groups, and the Studio's edits of metadata (a deck's authors and license, the instance's name, the catalog, a course's chapters completed), three times in all;
- a bulk edit of cards, planned again on the cards as they are, three times in all, stopping when that plan isn't the one previewed.
A grade's edit of the reviews document is made from the document as last read or written, at the version that left (srs.md); on a 412 it's read and graded again, once. Weak ETags (
W/"…") are never sent inIf-Match, whose comparison is strong; a document the pod gives no ETag is written withoutIf-Match. When the pod answers a write made on a precondition (If-Match, orIf-None-Match: *) with a strong ETag, the app keeps the written dataset at that version, as a read keeps what it read. The next edit sendsIf-Matchwith it, and the next readIf-None-Match. Without it (Community Solid Server 7 answers a PATCH with none), nothing is kept, and the next read downloads the document. Either way the read that edit was made from is out of date. A later save from it, of the dataset saved or another edit of the same read, is refused with aPreconditionFailedErrorbefore anything is sent, and so is a delete made on it. Sent withoutIf-Match, either could undo the first save and a change made elsewhere since. A read saved to another document isn't out of date where it was read: an edit or delete of it there still sends itsIf-Match. A read without a strong ETag has no precondition to lose: an edit of it is still written again withoutIf-Match, and deleted without one. node-solid-server gives no ETag on a read and ignoresIf-Match; 5.7.4 ignoresIf-None-Match: *too, which 5.8.8 and 6.0.0 enforce. There no edit is conditional: a PATCH still keeps a change made elsewhere, a large edit's PUT doesn't. Community Solid Server 6's whole-second ETags miss a change made in the same second as the read (as in the digest). The end-to-end tests hold all of this against real servers, that one included (testing.md). - an edit is sent with
-
An edit's PATCH body is written by Solid Memo (
patchBodyin client/sparqlUpdate.ts, sent bywriteDocumentinclient/resources.ts), not by@inrupt/solid-client: one triple a line, a space before each.. node-solid-server's parser fails on a triple whose closing.touches the term before it (<#a> <#b> 1.}), as@inrupt/solid-clientwrites them. That server finds a decimal only as JavaScript spells its number (1,2.5), though it serves a whole one as1.0and another app may have written2.50. A PATCH it refuses (409) for a deletion spelled as read is sent once more, its deleted decimals so spelled. A triple gone is refused the second time too; one found then holds the same number. -
A document is downloaded once while it is unchanged, though a screen asks for it several times (a deck's cards for its study queue, the format check and the data check). A read already under way is shared, and a document read before is asked for with
If-None-Match: <its ETag>; on 304 the dataset read then is returned (datasets are immutable). A write to the document forgets both, unless it kept what it wrote at the version the pod answered with (above). It's kept in memory for the open page only. Logged in, the browser's own cache doesn't do this: without it a login downloaded every deck three times. That cache is never asked (cache: "no-store"), since it may keep a document the pod gives a modification time and noCache-Controlfor days, and answer a plain read with it. -
Reading builds the dataset in one pass (linearDataset.ts):
@inrupt/solid-clientcopies the whole graph for every quad, which took 9 s for a deck of 3,000 cards. -
404 is a normal state for not-yet-created documents; repositories treat it as empty, not as an error.
-
What Solid Memo didn't write, it doesn't delete or unlink. A write touches only the triples it changes, and a delete only resources Solid Memo knows it wrote (deleting an instance). A guest's deck may be added to a newly created instance: when that fails before the deck's entry names them, its cards and reviews documents are deleted, each as read, with
If-Match. Only a folder Solid Memo made whole, at a URL it found free, and nothing names yet is deleted recursively: the guest's study moved into a new instance, when that fails half-way or a closed tab leaves it behind. A folder a closed tab left that the type index now names, or that holds anything the move didn't copy, isn't deleted. -
An update writes each document in one edit, held to its read. The format update and the library upgrade write each document where it is, in one edit made only if the document is still at the version read (
If-Match). The edit is made from that same read or, for an upgrade's cards, from the changes planned on it (migrations.md). A document whose write fails is as it was, and nothing is put back. No write puts an older format over a subject a newer version of the app wrote (migrations.md).