portaljs-define-schema
Define a dataset's metadata profile — infer a Frictionless Table Schema from its data, add Data Package metadata (license, sources, keywords), and write it into datasets.json so the showcase renders a typed field table. Extend or customize via the L0→L3 profile ladder.
Install / Use
npx skills add datopian/portaljsInstalls into whichever agent you are using.
Claude Commands
Claude Code slash commands
Quality Score
Category
LegalSupported Platforms
Tags
Our assessment of portaljs-define-schema
portaljs-define-schema scores 93/100 on our quality scale, 24th of 208 Legal skills we index (top 12%).
Its Claude Commands is 11 KB long, well organised into 15 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.
With 2,356 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so portaljs-define-schema is actively maintained.
- Our last check on 2026-10-26 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-30. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
portaljs-define-schema compared with similar skills
All 4 of these similar skills score higher than portaljs-define-schema; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| portaljs-define-schema (this skill)by datopian | 93 | 2.4k | 2mo ago | Claude Commands |
| claude-memby thedotmack | 100 | 117.6k | today | CLAUDE.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 9d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 92.8k | 1d ago | CLAUDE.md |
Frequently asked questions
- How do I install portaljs-define-schema?
- Run
npx skills add datopian/portaljs. The install tabs above show the steps for each supported agent. - Which AI agents does portaljs-define-schema work with?
- It is written for Claude Code, as a Claude Commands file. Other agents that read the same format can often use it too.
- Is portaljs-define-schema safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is portaljs-define-schema still maintained?
- The repository was last updated about 2 months ago, so portaljs-define-schema is actively maintained.
Skill content
View source on GitHubdescription: Define a dataset's metadata profile — infer a Frictionless Table Schema from its data, add Data Package metadata (license, sources, keywords), and write it into datasets.json so the showcase renders a typed field table. Extend or customize via the L0→L3 profile ladder. allowed-tools: Read, Write, Edit, Bash
/portaljs-define-schema
The authoring skill for the metadata-profile contract (lib/metadata). Where
/portaljs-add-dataset registers that a dataset exists, this skill
describes what its data means: it infers a Frictionless Table Schema (fields, types,
constraints) from the data, adds the Data Package descriptor fields a catalog surfaces
(title, licenses, sources, keywords), and writes them onto the dataset's entry in
datasets.json. The showcase at /@<namespace>/<slug> then renders a typed
column/description table instead of a bare preview.
The model is Frictionless-native. DCAT / DCAT-AP is a serialization layer on top
(designed-in at lib/metadata/dcat.ts, built in the later DCAT-interop phase) — this
skill authors the native model, not the export.
The skill is interactive and never dead-ends: if the brief is thin it interviews in short rounds, infers sensible defaults from the data, echoes the schema for confirmation, and lets you reply "use defaults" to accept the inferred schema as-is.
See lib/metadata/README.md
for the contract and the L0→L3 ladder.
The profile ladder — pick a level
Most datasets want L0. Reach for higher levels only when you actually need them.
| Level | What it is | When |
|-------|-----------|------|
| L0 | Use the default frictionless-tabular profile as-is; just declare the dataset's schema + metadata. | Default. Tabular CSV/TSV with the standard Frictionless types. |
| L1 | Extend L0 — same default profile, plus a few extra package fields you care about. | You need extra descriptive metadata but standard validation is fine. |
| L2 | A fully custom profile (your own schema template + validate()), registered in lib/metadata. | A dataset type with validation rules L0 doesn't express. |
| L3 | Multiple profiles in the registry, resolved per dataset by its profile field. | A portal mixing dataset types, each with its own profile. |
Steps
1. Gather input from $ARGUMENTS (interview if thin)
Extract what's present:
PORTAL_DIR— portal directory (default:.)DATASET— which dataset to describe, byslugornamespace/slugLEVEL—L0(default) ·L1·L2·L3
If DATASET is missing, read PORTAL_DIR/datasets.json and ask which one (list the
slugs), then wait:
Which dataset should I define a schema for? (reply with a slug, or "all" to do each in turn)
- country-codes (reference) — already has a schema
- population-2022 (reference) — no schema yet
- co2-emissions (reference) — no schema yet
You can also say "use defaults" and I'll infer the schema from the data and confirm it.
Don't ask about the level up front — default to L0 and only offer to go higher in step 4 if the data or the user's answers call for it.
2. Validate the portal directory
The target must be a portaljs-catalog portal with the metadata contract. Confirm
PORTAL_DIR/datasets.json, PORTAL_DIR/lib/metadata/types.ts, and
PORTAL_DIR/pages/[owner]/[slug].tsx exist. If lib/metadata/ is missing, the portal
predates the metadata-profile contract — tell the user and offer to proceed by writing the
schema onto datasets.json anyway (the fields are optional and ignored by older
showcases) rather than failing.
3. Infer the Table Schema from the data
Locate the dataset entry in datasets.json, then read its file from
PORTAL_DIR/public/data/<file>. For CSV/TSV, sample the header + first ~50 data rows:
# Replace FILE with PORTAL_DIR/public/data/<file>.
head -1 FILE # header → field names
sed -n '2,51p' FILE # sample rows → infer types
Infer each field's type from the sampled values, using the contract's vocabulary
(lib/metadata/types.ts → FieldType): integer if every value matches ^[+-]?\d+$;
number if numeric but not all integers; year if all 4-digit; boolean for
true/false/yes/no/0/1; date/datetime if Date.parse-able; geopoint for "lon, lat";
otherwise string. When a column is empty or ambiguous, default to string — never guess
wildly. (This mirrors coercesTo() in frictionless-tabular.ts, so an inferred schema
validates clean against its own data.)
Build a TableSchema:
- One
Fieldper column:name(exact header, spaces preserved), inferredtype, and a shorttitle+descriptionyou draft from the column name and the dataset's purpose. constraints: markrequired: truefor columns with no missing values in the sample;unique: truefor columns whose sampled values are all distinct; add apatternonly when the values clearly fit one (e.g. uppercase codes^[A-Z]{2}$).primaryKey: the column (or composite) that uniquely identifies a row, if obvious.
For JSON / GeoJSON datasets, the L0 tabular profile doesn't apply — explain that
schema authoring here covers tabular data, offer to capture package metadata only (step 5),
and stop short of a fields schema.
4. Confirm the schema (and offer to go beyond L0)
Echo the inferred schema as a compact table for confirmation:
Inferred schema for <dataset> — say "go" to write it, or correct any field:
field type required unique notes
----------- -------- -------- ------ -----------------------------
<name> <type> <y/n> <y/n> <title / pattern>
...
primaryKey: <col(s) or none>
This uses the default L0 'frictionless-tabular' profile.
Then, only if warranted, offer to go higher: "Want extra metadata fields (L1), or a custom profile with its own validation rules (L2/L3)?" Default stays L0 if they say "go".
5. Capture Data Package metadata
Ask for the descriptor fields the showcase surfaces (all optional — Enter/"skip" to omit):
Optional dataset metadata (Enter to skip any):
- license (e.g. ODbL-1.0, CC-BY-4.0)
- source(s) (title + URL of where the data came from)
- keywords (comma-separated)
- version (e.g. 1.0.0)
Map answers to the Dataset fields licenses[] ({name,title,path}), sources[]
({title,path}), keywords[], version (and modified with today's date if the data was
just updated).
6. Write it into datasets.json
Open PORTAL_DIR/datasets.json and update the target dataset's entry in place,
preserving all other entries and the existing slug/namespace/name/file/format
fields. Add:
{
"...": "existing fields unchanged",
"profile": "frictionless-tabular",
"schema": {
"primaryKey": "<col or [cols]>",
"fields": [
{ "name": "<col>", "type": "<type>", "title": "<title>", "description": "<desc>",
"constraints": { "required": true } }
]
},
"licenses": [ { "name": "<id>", "title": "<title>", "path": "<url>" } ],
"sources": [ { "title": "<title>", "path": "<url>" } ],
"keywords": ["..."],
"version": "<x.y.z>"
}
This matches the extended Dataset shape in lib/providers/types.ts. Drop any field with
no value (all are optional). Omit profile to let it default to frictionless-tabular, or
set it explicitly for clarity. For an L2/L3 custom profile, set profile to that profile's
id.
For L2 / L3 (custom profile): scaffold a profile module and register it so the
dataset's profile id resolves:
- Write
PORTAL_DIR/lib/metadata/<profile-id>.tsexporting aMetadataProfile(id,name,version, optional pinnedschema, and avalidate(input)— start fromfrictionlessTabularProfile's shape and add the extra rules). - Register it once at load: in
PORTAL_DIR/lib/metadata/registry.tsimport the profile and addregisterProfile(<profile>), or callregisterProfilefrom app bootstrap. - Keep L0 as the fallback —
getProfile(id)already returns the default for unknown ids.
7. Validate the schema against the data (optional but recommended)
The L0 profile can check the schema against the dataset's rows (type-coercion + the constraint subset). Offer a quick check using the contract:
cd PORTAL_DIR
npx tsx -e '
import { getProfile } from "./lib/metadata";
// load the dataset entry + parse its CSV rows, then:
// const r = getProfile(ds.profile).validate({ schema: ds.schema, rows });
// console.log(JSON.stringify(r, null, 2));
' 2>/dev/null || echo "skip if tsx is unavailable; the build check below still covers types"
If validation reports errors, surface them (wrong type, missing required, duplicate key)
and fix the schema (e.g. relax a type, drop a required) before writing. Warnings are
advisory.
8. Verify the build
cd PORTAL_DIR
npx next build > /tmp/portaljs-define-schema-build.log 2>&1
BUILD_EXIT=$?
tail -20 /tmp/portaljs-define-schema-build.log
The common failure is malformed JSON in datasets.json (a stray comma) or a type that
isn't in FieldType. Fix and rebuild before reporting success.
9. Report
✓ Schema defined: <dataset>
- Profile: <profile-id> (L<level>)
- Fields: <n> (<list of names>)
- Metadata: <license / sources / keywords / version that were set, or "none">
- Manifest: datasets.json (entry updated in place)
- Showcase: /@<namespace>/<slug> now renders a typed field table
Next: run `npm run dev` and open the showcase to see the schema table, or run
/portaljs-define-schema on the next dataset. Need machine-readable export for harvesting?
DCAT serialization is designed-in (lib/metadata/dcat.ts) and built in the DCAT-interop phase.
Notes
- One source of truth. The schema lives on the dataset's
datasets.jsonentry, read through the data provider unchanged — no page edits, no separate schema file (except an L2/L3 custom profile module inlib/metadata). - Degrades cleanly. Every metadata field is optional; a dataset with none still lists, previews, and renders — the showcase just omits the schema table.
- Frictionless-native, DCAT on top. This authors the native model.
toDCAT/fromDCATinlib/metadata/dcat.tsare the interop layer (DCAT-AP / national / domain profiles), designed-in now and built in the DCAT-interop phase — don't hand-write DCAT here. - Backends. A CKAN / OpenMetadata provider maps its native metadata onto these same fields; this skill is for the static/git-authored catalog.
Example
/portaljs-define-schema population-2022
The skill reads public/data/population-2022.csv, infers fields (e.g. country: string,
population: integer), drafts titles/descriptions, asks for a license + source, writes the
schema + metadata onto the population-2022 entry in datasets.json under the default
frictionless-tabular profile, validates it against the rows, verifies the build, and
reports the showcase URL. With no arguments it lists the datasets and asks which to describe.
Related Skills
claude-mem
117.6kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
92.8kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
