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.
Instrucciones de origen · Vista previa de solo lectura
name
portaljs-add-dcat
description
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.
Claude Code with PortalJS portals (Next.js 14, React 18, Node 18+). Runs from any project via the plugin, a personal ~/.claude/commands install, or a portaljs clone.
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/ and emits
per-profile x serialization feeds from .
prebuild
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).
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.
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.
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
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.
