PortalJS — Add DCAT
Overview
Turn an existing PortalJS (portaljs-catalog) portal into a harvestable data catalog.
PortalJS is Frictionless-native — a dataset is a Data Package (see
portaljs-define-schema) — and DCAT is the serialization + harvest layer on top
(lib/metadata/dcat.ts + lib/metadata/dcat-profiles.ts). This skill selects one or
more DCAT application profiles, maps every dataset's metadata to them, and writes
static feed files at build time — JSON-LD, Turtle, and RDF/XML — so external catalogs
(data.europa.eu, data.gov, national portals) can harvest the datasets automatically,
on any static host, with no runtime.
Prerequisites
- A scaffolded PortalJS portal with
datasets.json, package.json, and
lib/metadata/ (the metadata-profile contract) present.
lib/metadata/dcat.ts (the DCAT-3 core) already in place — profiles augment it.- Node 18+ and npm available in the portal directory.
- For DCAT-AP / DCAT-US: a publishing organization (name + homepage) and a contact
(name + email) — both profiles require
dct:publisher and dcat:contactPoint.
- Optional but recommended: network access to run SHACL conformance checks against the
official EU ITB validator or
pyshacl.
Instructions
The canonical, full step-by-step workflow is
.claude/commands/portaljs-add-dcat.md —
the single source of truth. Read and follow it when executing. Summary:
- Gather input from
$ARGUMENTS (interview if thin): portal directory (default .),
profiles (default ["dcat-3"]), site URL, publisher, contact, license, themes,
languages, access level.
- Validate the portal directory: confirm
datasets.json, package.json, and
lib/metadata/ exist; stop with an ERROR: if the metadata contract is missing.
- Ensure the DCAT profile layer is present —
dcat-profiles.ts, dcat-rdf.ts,
dcat-validate.ts — copying canonical versions from examples/portaljs-catalog if
the portal predates this skill.
- Ensure
scripts/generate-dcat.ts is wired to predev/prebuild and emits
per-profile x serialization feeds from dcat.config.json.
- Write
dcat.config.json with the gathered profiles, publisher, contact, license,
themes, and access level.
- Add feed autodiscovery: a
<link rel="alternate" type="application/ld+json"> to
pages/_document.tsx pointing at /catalog.jsonld.
- Generate the feeds and check conformance: run
npm run generate:dcat and surface
any missing mandatory fields.
- Verify the RDF: confirm the JSON-LD parses, and cross-check that JSON-LD, Turtle,
and RDF/XML agree; run SHACL validation (ITB for DCAT-AP,
pyshacl for DCAT-US)
when network/tooling allow.
- Verify the build with
npx next build; fix errors before reporting success.
- Report the profiles emitted, feed paths, conformance status, and next steps
(register with the harvester, run
portaljs-deploy).
Output
- Created/modified:
dcat.config.json (committed config).
- Generated (build artifacts, gitignored):
public/catalog.jsonld /.ttl/.rdf
(canonical feed), public/catalog.<profile>.{jsonld,ttl,rdf} per configured profile,
public/catalog-feeds.json (feed index).
- Modified:
pages/_document.tsx (autodiscovery <link>), package.json
(generate:dcat script wired to predev/prebuild).
- Verified: feeds are valid JSON-LD/Turtle/RDF-XML, conformance status reported,
npx next build passes.
Error Handling
| Symptom |
Cause |
Fix |
NO_METADATA_CONTRACT |
lib/metadata/ not found |
Portal predates the metadata-profile contract; scaffold with portaljs-new-portal or add lib/metadata first. |
NO_DCAT_CORE |
lib/metadata/dcat.ts not found |
The DCAT-3 core is missing; update the portal template before adding profiles. |
BAD_CONFIG |
dcat.config.json is not valid JSON |
Fix the syntax and re-run npm run generate:dcat. |
UNKNOWN_PROFILE |
Profile id not in the registry |
Use one of dcat-2, dcat-3, dcat-ap, dcat-us, geodcat-ap, croissant, dcat-ap-se, dcat-ap-ch, dcat-ap-de, or register a national profile first. |
| Feed flagged non-conformant |
publisher/contactPoint missing for DCAT-AP or DCAT-US |
Ask the user for the publishing organization and contact, add to dcat.config.json, regenerate. |
| DCAT-US SHACL rejects the publisher |
Publisher has no IRI (blank node) |
Set publisher.uri (or homepage) in dcat.config.json. |
next build fails after config change |
Malformed JSON in dcat.config.json or datasets.json |
Print the build log, fix the JSON, rebuild before reporting success. |
Examples
Example 1 — Default DCAT-3 feed, no national harvesting
/portaljs-add-dcat
Emits the canonical public/catalog.jsonld/.ttl/.rdf under the default dcat-3
profile, adds autodiscovery to _document.tsx, and wires generate:dcat into
predev/prebuild. No publisher/contact required.
Example 2 — EU harvesting via DCAT-AP
/portaljs-add-dcat profiles=dcat-ap site=https://data.example.org
Prompts for publisher (name + homepage) and contact (name + email) since DCAT-AP
requires both, writes them into dcat.config.json, and emits
public/catalog.dcat-ap.{jsonld,ttl,rdf} plus the canonical feed with absolute links.
Example 3 — US federal harvesting via DCAT-US
/portaljs-add-dcat profiles=dcat-us site=https://data.example.gov
Requires an IRI-identified publisher (publisher.uri) for SHACL conformance; emits
catalog.dcat-us.{jsonld,ttl,rdf} and validates against the DCAT-US 3.0 SHACL shapes
with pyshacl when available.
Example 4 — Multiple profiles plus a national extension
/portaljs-add-dcat profiles=dcat-ap,dcat-ap-de site=https://daten.example.de
Emits both catalog.dcat-ap.* and catalog.dcat-ap-de.* feeds from one config; the
first profile listed also becomes the canonical, un-suffixed catalog.jsonld/.ttl/.rdf.
Resources
Source: jeremylongshore/claude-code-plugins-plus-skills → plugins/community/portaljs/skills/portaljs-add-dcat/SKILL.md
1---
2name: portaljs-add-dcat
3description: "Make a PortalJS portal harvestable by national/EU/US open-data portals — emit standards-compliant DCAT catalog feeds (DCAT 2/3, DCAT-AP, DCAT-US, national profiles) in JSON-LD, Turtle, and RDF/XML at build, with autodiscovery and per-profile conformance checking. Use when a portal needs to be harvested by data.europa.eu, data.gov, or a national open-data catalog."
4allowed-tools: "Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(node:*), WebFetch"
5category: general-purpose
6source_repo: jeremylongshore/claude-code-plugins-plus-skills
7source_path: "plugins/community/portaljs/skills/portaljs-add-dcat/SKILL.md"
8source_url: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/community/portaljs/skills/portaljs-add-dcat/SKILL.md
9---
10
11
12# PortalJS — Add DCAT
13
14## Overview
15
16Turn an existing PortalJS (`portaljs-catalog`) portal into a harvestable data catalog.
17PortalJS is Frictionless-native — a dataset is a Data Package (see
18`portaljs-define-schema`) — and DCAT is the serialization + harvest layer on top
19(`lib/metadata/dcat.ts` + `lib/metadata/dcat-profiles.ts`). This skill selects one or
20more DCAT application profiles, maps every dataset's metadata to them, and writes
21static feed files at build time — JSON-LD, Turtle, and RDF/XML — so external catalogs
22(data.europa.eu, data.gov, national portals) can harvest the datasets automatically,
23on any static host, with no runtime.
24
25## Prerequisites
26
27- A scaffolded PortalJS portal with `datasets.json`, `package.json`, and
28 `lib/metadata/` (the metadata-profile contract) present.
29- `lib/metadata/dcat.ts` (the DCAT-3 core) already in place — profiles augment it.
30- Node 18+ and npm available in the portal directory.
31- For DCAT-AP / DCAT-US: a publishing organization (name + homepage) and a contact
32 (name + email) — both profiles require `dct:publisher` and `dcat:contactPoint`.
33- Optional but recommended: network access to run SHACL conformance checks against the
34 official EU ITB validator or `pyshacl`.
35
36## Instructions
37
38The canonical, full step-by-step workflow is
39[`.claude/commands/portaljs-add-dcat.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-add-dcat.md) —
40the single source of truth. Read and follow it when executing. Summary:
41
421. Gather input from `$ARGUMENTS` (interview if thin): portal directory (default `.`),
43 profiles (default `["dcat-3"]`), site URL, publisher, contact, license, themes,
44 languages, access level.
452. Validate the portal directory: confirm `datasets.json`, `package.json`, and
46 `lib/metadata/` exist; stop with an `ERROR:` if the metadata contract is missing.
473. Ensure the DCAT profile layer is present — `dcat-profiles.ts`, `dcat-rdf.ts`,
48 `dcat-validate.ts` — copying canonical versions from `examples/portaljs-catalog` if
49 the portal predates this skill.
504. Ensure `scripts/generate-dcat.ts` is wired to `predev`/`prebuild` and emits
51 per-profile x serialization feeds from `dcat.config.json`.
525. Write `dcat.config.json` with the gathered profiles, publisher, contact, license,
53 themes, and access level.
546. Add feed autodiscovery: a `<link rel="alternate" type="application/ld+json">` to
55 `pages/_document.tsx` pointing at `/catalog.jsonld`.
567. Generate the feeds and check conformance: run `npm run generate:dcat` and surface
57 any missing mandatory fields.
588. Verify the RDF: confirm the JSON-LD parses, and cross-check that JSON-LD, Turtle,
59 and RDF/XML agree; run SHACL validation (ITB for DCAT-AP, `pyshacl` for DCAT-US)
60 when network/tooling allow.
619. Verify the build with `npx next build`; fix errors before reporting success.
6210. Report the profiles emitted, feed paths, conformance status, and next steps
63 (register with the harvester, run `portaljs-deploy`).
64
65## Output
66
67- **Created/modified:** `dcat.config.json` (committed config).
68- **Generated (build artifacts, gitignored):** `public/catalog.jsonld` /`.ttl`/`.rdf`
69 (canonical feed), `public/catalog.<profile>.{jsonld,ttl,rdf}` per configured profile,
70 `public/catalog-feeds.json` (feed index).
71- **Modified:** `pages/_document.tsx` (autodiscovery `<link>`), `package.json`
72 (`generate:dcat` script wired to `predev`/`prebuild`).
73- **Verified:** feeds are valid JSON-LD/Turtle/RDF-XML, conformance status reported,
74 `npx next build` passes.
75
76## Error Handling
77
78| Symptom | Cause | Fix |
79| --- | --- | --- |
80| `NO_METADATA_CONTRACT` | `lib/metadata/` not found | Portal predates the metadata-profile contract; scaffold with `portaljs-new-portal` or add `lib/metadata` first. |
81| `NO_DCAT_CORE` | `lib/metadata/dcat.ts` not found | The DCAT-3 core is missing; update the portal template before adding profiles. |
82| `BAD_CONFIG` | `dcat.config.json` is not valid JSON | Fix the syntax and re-run `npm run generate:dcat`. |
83| `UNKNOWN_PROFILE` | Profile id not in the registry | Use one of `dcat-2`, `dcat-3`, `dcat-ap`, `dcat-us`, `geodcat-ap`, `croissant`, `dcat-ap-se`, `dcat-ap-ch`, `dcat-ap-de`, or register a national profile first. |
84| Feed flagged non-conformant | `publisher`/`contactPoint` missing for DCAT-AP or DCAT-US | Ask the user for the publishing organization and contact, add to `dcat.config.json`, regenerate. |
85| DCAT-US SHACL rejects the publisher | Publisher has no IRI (blank node) | Set `publisher.uri` (or `homepage`) in `dcat.config.json`. |
86| `next build` fails after config change | Malformed JSON in `dcat.config.json` or `datasets.json` | Print the build log, fix the JSON, rebuild before reporting success. |
87
88## Examples
89
90### Example 1 — Default DCAT-3 feed, no national harvesting
91
92```
93/portaljs-add-dcat
94```
95Emits the canonical `public/catalog.jsonld`/`.ttl`/`.rdf` under the default `dcat-3`
96profile, adds autodiscovery to `_document.tsx`, and wires `generate:dcat` into
97`predev`/`prebuild`. No publisher/contact required.
98
99### Example 2 — EU harvesting via DCAT-AP
100
101```
102/portaljs-add-dcat profiles=dcat-ap site=https://data.example.org
103```
104Prompts for publisher (name + homepage) and contact (name + email) since DCAT-AP
105requires both, writes them into `dcat.config.json`, and emits
106`public/catalog.dcat-ap.{jsonld,ttl,rdf}` plus the canonical feed with absolute links.
107
108### Example 3 — US federal harvesting via DCAT-US
109
110```
111/portaljs-add-dcat profiles=dcat-us site=https://data.example.gov
112```
113Requires an IRI-identified publisher (`publisher.uri`) for SHACL conformance; emits
114`catalog.dcat-us.{jsonld,ttl,rdf}` and validates against the DCAT-US 3.0 SHACL shapes
115with `pyshacl` when available.
116
117### Example 4 — Multiple profiles plus a national extension
118
119```
120/portaljs-add-dcat profiles=dcat-ap,dcat-ap-de site=https://daten.example.de
121```
122Emits both `catalog.dcat-ap.*` and `catalog.dcat-ap-de.*` feeds from one config; the
123first profile listed also becomes the canonical, un-suffixed `catalog.jsonld`/`.ttl`/`.rdf`.
124
125## Resources
126
127- Full workflow: [`.claude/commands/portaljs-add-dcat.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-add-dcat.md)
128- Profile registry, serialization formats, and validator details: [`references/reference.md`](references/reference.md)
129- Related skills: `portaljs-define-schema`, `portaljs-new-portal`, `portaljs-deploy`, `portaljs-migrate`
130- DCAT specification: <https://www.w3.org/TR/vocab-dcat-3/>
131
132---
133
134**Source:** [`jeremylongshore/claude-code-plugins-plus-skills`](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) → `plugins/community/portaljs/skills/portaljs-add-dcat/SKILL.md`
jeremylongshore