feat: w3c utils add custom context

[bovandersteene]

No description provided.

[Copilot]

Pull request overview

This PR extends the @ghentcdh/w3c-utils library to better support application-specific JSON-LD usage in W3C Annotations by adding a context builder utility and expanding the annotation schema to accept custom contexts and custom body shapes, alongside documentation and workspace/agent tooling updates.

Changes:

• Bump zod from 4.1.12 to 4.3.6 (root + w3c utils lib + lockfile).
• Add a ContextBuilder utility to generate JSON-LD @context, JSON Schema (draft-07), and annotation bodies from Zod schemas (with Vitest coverage).
• Extend W3C annotation schema/builders/helpers to support custom @context, array-based TextualBody.type, and custom body objects; add/expand tests and docs.

Reviewed changes

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

Show a summary per file

File	Description
pnpm-lock.yaml	Updates lockfile to reflect zod@4.3.6.
package.json	Bumps zod and changes the release script path.
libs/w3c/utils/src/lib/context/index.ts	Adds context module barrel export.
libs/w3c/utils/src/lib/context/context.helpers.ts	Adds helper to wrap parsed data as an annotation body.
libs/w3c/utils/src/lib/context/context.helpers.json.ts	Adds Zod→JSON Schema builder for JSON Forms compatibility.
libs/w3c/utils/src/lib/context/context.builder.ts	Introduces ContextBuilder / contextBuilder factory.
libs/w3c/utils/src/lib/context/context-helpers.jsonld.ts	Adds JSON-LD @context generator via Zod introspection.
libs/w3c/utils/src/lib/context/tests/context.helpers.json.spec.ts	Tests JSON Schema generation behavior.
libs/w3c/utils/src/lib/context/tests/context.builder.spec.ts	Tests ContextBuilder behaviors (context/schema/parse/body).
libs/w3c/utils/src/lib/context/tests/context-helpers.jsonld.spec.ts	Tests JSON-LD context generation.
libs/w3c/utils/src/lib/annotation/index.ts	Adds annotation module barrel export.
libs/w3c/utils/src/lib/annotation/annotation.schema.ts	Adds @context support, broadened type, passthrough resources, and custom bodies.
libs/w3c/utils/src/lib/annotation/annotation.builder.ts	Adds clone(), addContext(), and getBodiesByType() enhancements.
libs/w3c/utils/src/lib/annotation/annotation-helpers.ts	Adds custom-body guard + accessor and updates generic body access.
libs/w3c/utils/src/lib/annotation/tests/annotation.builder.spec.ts	Adds tests for clone, extended TextualBody type arrays, custom bodies, and new read helpers.
libs/w3c/utils/src/index.ts	Switches root exports to module barrels (annotation, context).
libs/w3c/utils/package.json	Bumps zod dependency for the w3c utils package.
docs/components/adapters/w3c/w3c-context-builder.md	Adds documentation for the new context builder API and workflows.
CLAUDE.md	Formatting tweaks + adds Nx agent guidance block.
AGENTS.md	Adds Nx agent guidance (new file).
.gitignore	Adds .nx/polygraph ignore and normalizes formatting.
.github/skills/nx-workspace/SKILL.md	Adds Nx workspace exploration skill documentation (new file).
.github/skills/nx-workspace/references/AFFECTED.md	Adds affected-projects reference (new file).
.github/skills/nx-run-tasks/SKILL.md	Adds Nx run-tasks skill documentation (new file).
.github/skills/nx-plugins/SKILL.md	Adds Nx plugins skill documentation (new file).
.github/skills/nx-import/SKILL.md	Adds Nx import skill documentation (new file).
.github/skills/nx-import/references/VITE.md	Adds Vite-specific Nx import reference (new file).
.github/skills/nx-import/references/TURBOREPO.md	Adds Turborepo Nx import reference (new file).
.github/skills/nx-import/references/NEXT.md	Adds Next.js Nx import reference (new file).
.github/skills/nx-import/references/JEST.md	Adds Jest Nx import reference (new file).
.github/skills/nx-import/references/GRADLE.md	Adds Gradle Nx import reference (new file).
.github/skills/nx-import/references/ESLINT.md	Adds ESLint Nx import reference (new file).
.github/skills/nx-generate/SKILL.md	Adds Nx generator skill documentation (new file).
.github/skills/monitor-ci/SKILL.md	Adds CI monitoring skill documentation (new file).
.github/skills/monitor-ci/scripts/ci-state-update.mjs	Adds CI monitor deterministic state script (new file).
.github/skills/monitor-ci/scripts/ci-poll-decide.mjs	Adds CI monitor deterministic polling decision script (new file).
.github/skills/monitor-ci/references/fix-flows.md	Adds CI monitor fix-flow reference (new file).
.github/agents/ci-monitor-subagent.agent.md	Adds CI monitor helper agent definition (new file).
.github/skills/link-workspace-packages/SKILL.md	Adds workspace package linking skill documentation (new file).
.github/prompts/monitor-ci.prompt.md	Adds prompt wrapper for the monitor-ci skill (new file).
.claude/settings.json	Enables Nx Claude plugins marketplace config (new file).

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (2)

libs/w3c/utils/src/lib/annotation/annotation.builder.ts:160

• addContext assumes @context is string | string[], but the schema now allows arrays mixing strings and context objects. With the current implementation, existing object entries get typed as string, and the arr.length === 1 branch casts whatever the lone entry is to the anno.jsonld literal. Consider updating addContext to work with the full W3CJsonLdContext shape (e.g. treat arrays as (string | Record<string, unknown>)[], only dedupe string entries, and avoid narrowing/casting arr[0] to the anno.jsonld literal unless it actually matches).
  libs/w3c/utils/src/lib/annotation/annotation.schema.ts:193
• W3CJsonLdContext claims to allow "context objects", but it currently restricts them to record<string, string>. JSON-LD context objects commonly contain non-string values (expanded term definitions like { "@id": ..., "@type": ... }). Either broaden the type (e.g. z.record(z.unknown())) or tighten the docstring so the runtime validation matches what is documented.

---

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

[Copilot]

Pull request overview

Copilot reviewed 39 out of 41 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (1)

libs/w3c/utils/src/lib/annotation/annotation.builder.ts:161

• addContext() collapses the @context back to a single string when the result has one entry. If that single entry is not exactly http://www.w3.org/ns/anno.jsonld, it will produce an invalid annotation per W3CAnnotation schema (which only allows that one literal string or an array of strings). Consider only collapsing when the single value is the canonical anno context, otherwise keep it as an array.

---

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