Shapes

A shape is a machine-readable description of what valid Solid Memo data looks like: which properties a thing has, and of what kind. There is one shape for each kind of data and each format version. The app uses them to check data, to generate code, and to tell an old format from a new one.

What a valid Solid Memo subject looks like, version by version, as SHACL; and how those shapes drive the code. One shape file per class per format version under ns/shapes/, published with the site at https://solid-memo.com/ns/shapes/ (ns.ts, deployment.md).

Files and IRIs

instance/v1.ttl, v2.ttl       https://solid-memo.com/ns/shapes/instance/v1.ttl#shape
deck/v1.ttl … v6.ttl          …/deck/v2.ttl#inPod  and  …/deck/v2.ttl#inLibrary
library-deck/v5.ttl, v6.ttl   …/library-deck/v5.ttl#inLibrary  (library deck 5 on)
deck-series/v1.ttl … v3.ttl
card/v1.ttl … v6.ttl
review-state/v1.ttl, v2.ttl
preferences/v1.ttl … v4.ttl
document-receipt/v1.ttl, deck-schedule/v1.ttl   (the digest)
deck-group/v1.ttl             …/deck-group/v1.ttl#inPod  (the arranged deck list)
chapter/v1.ttl, step/v1.ttl   …/chapter/v1.ttl#inLibrary  (a course's outline)
distractor/v1.ttl             …/distractor/v1.ttl#shape  (a wrong option, in a pod or the library)
draft-deck/v1.ttl, draft-chapter/v1.ttl, draft-step/v1.ttl
                              …/draft-deck/v1.ttl#inDraft  (a release's draft)

Each file's address is its IRI and its @base. The IRIs keep .ttl on purpose: GitHub Pages serves the file as text/turtle but negotiates no content, so an address without the extension would be a 404. npm run generate finds every version by reading the folders (sources.ts). A deck is shaped two ways because it lives in two places: <#inPod> (a catalog entry, with the links to its two documents) and <#inLibrary> (a deck library document, which has no pod documents and may list its sources). Up to format 4 both share one document and its named property shapes; library deck 5, a version the pod's deck does not share, has a self-contained file of its own (library-deck/v5.ttl), since a shape's sh:name version must match its file's, and so has library deck 6. A third place is a release's draft, while its author writes it in a pod: <#inDraft> shapes its deck, chapters and steps (DraftDeckV1, DraftChapterV1, DraftStepV1), each in a file of its own. Their property shapes are copies of the release's (library deck 6, chapter 1, step 1), with only what a release needs once it is published relaxed; a draft's cards, distractors, agents and distributions are checked by the shapes every place shares (<#shape>).

Conventions

• No sh:targetClass. Format 1 and format 2 of a class target the same class, so targeting would make every subject fail one of them. The shape is chosen by (rdf:type, sm:formatVersion) — absent = 1 — and the context (pod, library or draft) by pickShape in registry.ts, the same way at build time, in tests and in the browser. Every node shape carries sh:class and sh:nodeKind sh:IRI instead. The class is Solid Memo's own or, for the standard classes it writes, DCAT's or FOAF's (CLASS_NAMESPACES in packages/vocab/tooling/shapes.ts). A subject with a Solid Memo class is checked against that class's shapes only: a deck group is a dcat:Catalog too, but is never checked as CatalogV1.
• Further types are stated. A subject that is also, say, a dcat:Dataset says so with sh:property [ sh:path rdf:type ; sh:hasValue dcat:Dataset ]; the shape is still picked by its sh:class, and the writer adds every such type. A course's subjects state their schema.org types this way: a chapter is a schema:Syllabus, a step a schema:LearningResource, a distractor a schema:Answer (courses.md).
• The version is asserted. Format ≥ 2: sm:formatVersion with sh:hasValue N, exactly once. Format 1: sh:maxCount 1 ; sh:in ( 1 ), which reads "absent or 1" — the rule that a missing version means the format that predates the field.
• Not closed. Unknown triples are neither violations nor removed: readers ignore them and writers edit subjects in place.
• Property shapes are named (<#front>, never blank nodes), so the generator and the results can refer to them. sh:message is set where the engine's default text would be cryptic, always in English and Swedish ("…"@en, "…"@sv), and a test (messages.test.ts) holds every message to exactly those two. The app shows a message in the reader's language when the shape has it, else in English, marked as English: a Korean reader sees these in English. Where a shape sets none, the validator's own English stands, and the app says it in the reader's language by its constraint (validation.constraint.* in the message catalogs), more generally.
• Rules a record cannot carry — a card side has text or a picture (sh:or), the review snapshot is all five triples or none (sh:xone), a review state names its card with sm:reviewOf or is named #<cardId> or #<cardId>@back-to-front (a node-level sh:or of a sh:pattern and the property) — are enforced by the record → model mappers in code and by SHACL in validation.

Version by version

The DCAT and FOAF classes' values (an agent is a foaf:Agent, a theme a skos:Concept, a license a dcterms:LicenseDocument) are checked by the DCAT-AP profile, with the reference data; Solid Memo's own shapes only say IRI (see validation.md).

What a row says the app shows and edits is what the app did while that format was the latest; the app of today edits text as the latest formats ask.

Why each version moved is in migrations.md.

What the shapes generate

The diagram's source

flowchart LR
    accTitle: What the shapes generate
    accDescr: npm run generate turns the shapes into types and descriptors, which the migrations, the records, the mappers and the shape registry use.
    shapes["ns/shapes/*/v*.ttl"] -->|npm run generate| types["src/types.generated.ts<br/>CardV2, DeckRecord, LATEST_VERSION…"]
    shapes -->|npm run generate| desc["src/descriptors.generated.ts<br/>CARD_V2, SHAPES, ALL_SHAPES"]
    types --> migrations["domain: shapes/migrations<br/>record to the next record"]
    types --> records["domain: *Record.ts<br/>record to model and back"]
    desc --> rw["solid: records.ts<br/>Thing to record and back"]
    desc --> pick["shacl: registry.ts<br/>pickShape"]
    shapes -->|build, tests, browser| shacl["rdf-validate-shacl"]

packages/vocab/tooling/shapes.ts reads, from every node shape with an sh:name ("CardV2", "LibraryDeckV1"), the properties it lists: sh:path, sh:datatype or sh:nodeKind sh:IRI, sh:minCount, sh:maxCount, sh:in and an optional sh:name for the field. Anything else (sh:or, sh:xone, sh:pattern, ranges, messages) is validation only.

sm:formatVersion and rdf:type (the class and any sh:hasValue types) are the envelope, not fields: the generic writer stamps them from the descriptor. Generated files hold only types and as const data, are committed, and are checked for drift by CI (npm run generate:check) and by packages/vocab/tooling/generate.test.ts.

Reading and writing

Every mapper is the same three steps (see records.ts):

1. readVersioned(thing, "card") — the class is checked, the stored version read (absent = 1), and the subject read with the descriptor of that version into a { version, data } record. A version newer than this app knows is read with the latest shape it has; the stored version passes through to the model unchanged.
2. migrate("card", record) — the record walked up the migration chain to the latest version, in memory.
3. cardFromRecord(url, storedVersion, data) — the domain model, which keeps the stored version so the migration plan can count what is outdated.

Writing is the reverse: cardToRecord(content) then recordThing(url, CARD_V2, record, existing), which edits the existing subject in place (only the shape's predicates are replaced, so foreign triples survive), adds the class once and stamps the version. Every subject this app writes is therefore stamped and conforms to the latest shape — the conformance test in conformance.test.ts proves it for every version and every migration step.

Where the shapes are checked

• Tests: the fixtures in packages/vocab/fixtures/<class>/v<N>/{valid,invalid}/ pass and fail as expected against the shapes in ns/shapes/; the conformance test above. Nothing needs the network.
• The deck library: every version and the index, by npm run library:check (deck-library.md).
• pySHACL: a release published in a pod and the drafts, by npm run crosscheck (validation.md).
• Browser: the developer tool described in validation.md.

Adding a version

See migrations.md.