Add context7.json + expand README and per-export docs by jeswr · Pull Request #29 · solid/object

jeswr · 2026-04-23T02:03:14Z

Adds documentation and discovery metadata so consumers of @solid/object can find the API without reading source.

What's added

context7.json — catalogue file the context7 MCP reads to serve docs lookups. Without it, every consumer of @solid/object (reactive-fetch, downstream Solid apps, etc.) has to read the source to figure out the API surface.
README expansion — install instructions, quick-start example, package layout, contribution notes.
Per-export API reference under docs/api/ covering: webid (Agent, WebIdDataset), solid (Resource etc.), acp (the access-control wrappers), wac, vocabulary, and conversion. Each documents what the wrapper represents, the spec it follows, public properties + methods, and a usage example.

What's NOT changed

No runtime behaviour. Pure docs / metadata addition. The oidcIssuers getter on Agent is in a separate small PR (#28); the planned WebIDProfile rename work is left untouched.

Self-review

Reviewed locally with roborev review --local before opening. Two follow-up commits address its findings (accuracy gaps in the docs, plus nits around HasValue, mimeType, phoneType, and example correctness).

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

Lets the Context7 MCP server (https://context7.com) index this repository so coding agents that depend on @solid/object can look the API up directly rather than reading the source. Includes the project title, a one-line description, the folders worth parsing (docs, src), the noise to skip (dist, node_modules, test, .github), and a short rules block summarising the wrapper / dataset construction convention and the sub-path import layout. Refs solid#14. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The previous README was three lines; this rewrite gives consumers enough to get going without opening the source: - npm install instructions and runtime expectations. - Two quick-start examples (read a WebID profile, enumerate ACL authorisations) plus a one-liner for the WAC -> ACP converter. - A table of the four entry points with links into the per-export docs added under docs/api/. - Specification index with links to the Solid Protocol, Solid OIDC, WAC, ACP, LDP, vCard, FOAF, PIM, POSIX and Dublin Core sources the wrappers map onto. - Contributing notes (clone, install, npm test) and a pointer to the context7.json catalogue. Refs solid#14. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

One Markdown file per public sub-path plus a vocabulary file and a docs/README.md index. Each file documents: - What each wrapper class wraps (TermWrapper vs DatasetWrapper from @rdfjs/wrapper, what RDF subject or graph it stands for). - The spec the concept comes from (Solid Protocol, Solid OIDC, WAC, ACP, LDP, vCard, FOAF, PIM, POSIX, Dublin Core), with section anchors where they exist. - Every property: its TypeScript type, the predicate it reads or writes, and whether it's read-only or read/write. - Worked examples using n3 as the RDF/JS implementation. For the WAC -> ACP and ACP -> WAC translators the docs enumerate the exact features that trigger each TranslationError subclass so consumers can decide where to fall back. Refs solid#14. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- conversion.md: wacToAcp does not iterate acl:agentClass — only acl:agent and expanded acl:agentGroup members. Documented the limitation so readers do not expect public/authenticated translation for canonical WAC graphs that express those subjects via acl:agentClass. Reworded the bullet that previously implied agent-class translation. - webid.md: clarified that Agent.name's URL fallback strips any trailing #fragment as well as path segments. - solid.md: noted that Resource.mimeType returns the full IANA-vocabulary class IRI rather than the bare media-type string. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- README: rewrote the wacToAcp quick-start so the AclResource construction is no longer an inline-comment placeholder; the example now parses a small Turtle fixture into a Store first, mirroring the earlier WAC example. - docs/api/webid.md: dropped the `HasValue` type name (the class is not exported from the package) in favour of an inline shape description for `hasEmail` / `hasTelephone` return values. Reworded the WebIdDataset.mainSubject caveat so it no longer links a source-level TODO; describes the limitation directly instead. - docs/api/solid.md: added a "Known issues" note flagging that Telephone.phoneType uses the `vcard:TelephoneType` IRI as a predicate where the vCard ontology defines that IRI as a class — reflects upstream code as-is and warns consumers. - context7.json: stopped excluding the test/ folder so the worked examples in test/unit/ get indexed alongside the docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

This PR adds discovery metadata and expanded documentation so consumers of @solid/object can understand and navigate the public API surface without reading the source.

Changes:

Add context7.json for Context7 MCP documentation indexing.
Expand the root README.md with install, quick-start examples, package layout, and contribution notes.
Add per-export API reference docs under docs/api/ and an index at docs/README.md.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
docs/api/webid.md	New WebID wrapper docs for `WebIdDataset` and `Agent`.
docs/api/wac.md	New WAC wrapper docs for `AclResource`, `Authorization`, `Group`.
docs/api/vocabulary.md	New docs for exported vocabulary constant objects.
docs/api/solid.md	New docs for `Resource`/`Container` and vCard `Email`/`Telephone` wrappers.
docs/api/conversion.md	New docs for WAC↔ACP translation helpers and error types.
docs/api/acp.md	New docs for ACP wrappers (`AcrDataset`, `AccessControlResource`, etc.).
docs/README.md	Adds a docs landing page and shared conventions for wrappers.
context7.json	Adds Context7 catalog metadata and usage rules for indexing.
README.md	Major expansion of project-level documentation and navigation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-23T02:09:46Z

+- Properties typed `Set<T>` are live: adding to or removing from the
+  returned set mutates the underlying dataset.


The convention "Properties typed Set<T> are live" isn’t universally true in the current API: e.g. Agent.storageUrls returns a newly constructed Set union and mutations won’t write back to the dataset. Please qualify this as "SetFrom-backed" sets are live, and call out computed/synthetic sets as snapshots.

Suggested change

- Properties typed `Set<T>` are live: adding to or removing from the

returned set mutates the underlying dataset.

- Properties typed `Set<T>` are live only when they are `SetFrom`-backed:

adding to or removing from those returned sets mutates the underlying

dataset. Computed or synthetic sets are snapshots, so mutating them does

not write back to the dataset.

Copilot · 2026-04-23T02:09:47Z

+`@solid/object` re-exports a frozen object per RDF namespace it touches. The
+values are the full IRI strings; pair them with any `DataFactory.namedNode`
+when constructing terms by hand.


This doc says each vocabulary export is a "frozen object", but the implementation exports plain const objects (typed as const) and does not Object.freeze them. Please either update the wording to "as const object" / "constant object" or actually freeze the objects in code if immutability at runtime is intended.

Suggested change

`@solid/object` re-exports a frozen object per RDF namespace it touches. The

values are the full IRI strings; pair them with any `DataFactory.namedNode`

when constructing terms by hand.

`@solid/object` re-exports an `as const` object per RDF namespace it touches.

The values are the full IRI strings; pair them with any

`DataFactory.namedNode` when constructing terms by hand.

Copilot · 2026-04-23T02:09:47Z

+All properties are read-only getters. Sets are mutable via `@rdfjs/wrapper`'s
+`SetFrom` machinery — adding to or deleting from the returned `Set` mutates
+the underlying dataset.


The statement that "Sets are mutable via @rdfjs/wrapper's SetFrom machinery" is not true for every Set-returning getter here: Agent.storageUrls is implemented as new Set([...this.pimStorage, ...this.solidStorage]), so mutating the returned set will NOT update the underlying dataset. Please qualify this note (e.g., only SetFrom-backed properties are live, and computed unions like storageUrls are snapshots).

Copilot · 2026-04-23T02:09:47Z

+| `photoUrl` | `string \| null` | [`vcard:hasPhoto`](https://www.w3.org/TR/vcard-rdf/) | vCard |
+| `pimStorage` | `Set<string>` | [`pim:storage`](http://www.w3.org/ns/pim/space#storage) — the agent's storage roots. | [PIM/space](http://www.w3.org/ns/pim/space) |
+| `solidStorage` | `Set<string>` | [`solid:storage`](http://www.w3.org/ns/solid/terms#storage) — Solid Protocol storage. | [Solid Protocol §4.1](https://solidproject.org/TR/protocol#storage) |
+| `storageUrls` | `Set<string>` | The union of `pimStorage` and `solidStorage`. | — |


storageUrls is documented like other live Set<string> properties, but the current implementation returns a new Set union (not a SetFrom-backed set). Please document it as a computed snapshot (read-only; mutating it does not write triples) or adjust the implementation to return a live set-like view.

Copilot · 2026-04-23T02:09:48Z

+| `phone` | `string \| null` | Convenience: `hasTelephone?.value`. | vCard |
+| `hasTelephone` | term wrapper \| `undefined` | [`vcard:hasTelephone`](https://www.w3.org/TR/vcard-rdf/#hasTelephone). Same opaque shape as `hasEmail`. | vCard |
+| `website` | `string \| null` | Computed: `vcardHasUrl` -> `foafHomepage`. | vCard / FOAF |
+| `vcardHasUrl` | `string \| undefined` | [`vcard:hasURL`](https://www.w3.org/TR/vcard-rdf/) | vCard |


The predicate is labeled/link-texted as vcard:hasURL, but the library’s vocabulary constant and wrapper use VCARD.hasUrl (IRI ends with #hasUrl). For consistency with the actual API/constants, please change this row to vcard:hasUrl (and update any link text accordingly).

Suggested change

| `vcardHasUrl` | `string \| undefined` | [`vcard:hasURL`](https://www.w3.org/TR/vcard-rdf/) | vCard |

| `vcardHasUrl` | `string \| undefined` | [`vcard:hasUrl`](https://www.w3.org/TR/vcard-rdf/) | vCard |

Copilot · 2026-04-23T02:09:48Z

+| `website` | `string \| null` | Computed: `vcardHasUrl` -> `foafHomepage`. | vCard / FOAF |
+| `vcardHasUrl` | `string \| undefined` | [`vcard:hasURL`](https://www.w3.org/TR/vcard-rdf/) | vCard |
+| `foafHomepage` | `string \| undefined` | [`foaf:homepage`](http://xmlns.com/foaf/spec/#term_homepage) | FOAF |


Copilot · 2026-04-23T02:09:48Z

+| `title` | `string \| undefined` | [`dc:title`](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/title) | |
+| `label` | `string \| undefined` | [`rdfs:label`](https://www.w3.org/TR/rdf-schema/#ch_label) | |
+| `name` | `string` | Computed: `title` -> `label` -> last URL path segment (URL-decoded where possible). | Always defined. |
+| `modified` | `Date \| undefined` | [`dc:modified`](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/modified) | |


jeswr and others added 5 commits April 23, 2026 02:25

Copilot AI review requested due to automatic review settings April 23, 2026 02:03

jeswr requested review from langsamu and matthieubosquet as code owners April 23, 2026 02:03

Copilot started reviewing on behalf of jeswr April 23, 2026 02:03 View session

Copilot AI reviewed Apr 23, 2026

View reviewed changes

jeswr marked this pull request as draft April 23, 2026 11:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add context7.json + expand README and per-export docs#29

Add context7.json + expand README and per-export docs#29
jeswr wants to merge 5 commits intosolid:mainfrom
jeswr:feat/context7-and-docs

jeswr commented Apr 23, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Copilot AI Apr 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		- Properties typed `Set<T>` are live: adding to or removing from the
		returned set mutates the underlying dataset.

-- Properties typed `Set<T>` are live: adding to or removing from the
-  returned set mutates the underlying dataset.
+- Properties typed `Set<T>` are live only when they are `SetFrom`-backed:
+  adding to or removing from those returned sets mutates the underlying
+  dataset. Computed or synthetic sets are snapshots, so mutating them does
+  not write back to the dataset.

	\| `vcardHasUrl` \| `string \\| undefined` \| [`vcard:hasURL`](https://www.w3.org/TR/vcard-rdf/) \| vCard \|
	\| `vcardHasUrl` \| `string \\| undefined` \| [`vcard:hasUrl`](https://www.w3.org/TR/vcard-rdf/) \| vCard \|

Conversation

jeswr commented Apr 23, 2026

What's added

What's NOT changed

Self-review

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants