Spreadsheet tabular metadata
Read a workbook into a folio-tabular-csvw/v1 record, one CSVW table per rectangular block of cells. Blocks are split on empty rows, then on empty columns, so several tables on one sheet are found, each anchored at its real top-left cell (fac:anchor: sheet, A1 cell, row, column). Dates are read through the number formats in styles.xml, not misread as integer serials. A malformed part is refused rather than half-read. Reads the ZIP with node:zlib and SpreadsheetML with fast-xml-parser. Governed by the tabular-metadata skill.
Skills it satisfies
A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.
tabular-metadata
Extract tabular metadata from a CSV or spreadsheet as CSVW — tables, rows, headers, columns, datatypes and location on sheet — recording every field as determined or explicitly undetermined. Read before touching a tabular ingest arm, adding a format, or deciding what a sheet is in the graph.
Source: folio-assistant-core/skills/library/ingestion/tabular-metadata.md.
Also satisfied by: tabular-csv.
The skill declares no I/O contract (schemas/skills/tabular-metadata/{input,output}.schema.json).
Inputs and outputs
Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | file | WorkbookPath | yes | Path to the .xlsx workbook. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A repository path to a spreadsheet workbook. |
| in | doc-id | DocId | The record’s doc_id. Default: the file name without its extension. | string · pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$ · A library document id, e.g. WPR-RDO-2020-003-eng | |
| in | out | RepoPath | Where to write tabular.csvw.json. Default: stdout. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| out | record | Text | A folio-tabular-csvw/v1 document, one table per block. Exit 2 when the file is not a SpreadsheetML workbook. | string · A short single-line human string. Not admissible as a command-line argument. |
Processes and tasks
No process step names a skill this Tool satisfies.
How it is deployed and reached
- Command line. From the repository root:
bun run folio-assistant-core/scripts/tabular-xlsx.ts. - GitHub Actions. No workflow in this checkout runs its command.
As an API: its operation in the OpenAPI document and the MCP tool list of its layer.
| install | none |
| runtime | bun |
| network | no |
What it is made of
| role | file | |
|---|---|---|
| definition | folio-assistant-core/tools/tabular-xlsx/tabular-xlsx.ts | |
| script | folio-assistant-core/scripts/tabular-xlsx.ts |
Linked data
The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/tabular-xlsx.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.
{
"@context": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.context.jsonld",
"@id": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/tabular-xlsx.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.jsonld",
"name": "tabular-xlsx",
"title": "Spreadsheet tabular metadata",
"description": "Read a workbook into a `folio-tabular-csvw/v1` record, one CSVW table per rectangular block of cells. Blocks are split on empty rows, then on empty columns, so several tables on one sheet are found, each anchored at its real top-left cell (`fac:anchor`: sheet, A1 cell, row, column). Dates are read through the number formats in `styles.xml`, not misread as integer serials. A malformed part is refused rather than half-read. Reads the ZIP with `node:zlib` and SpreadsheetML with `fast-xml-parser`. Governed by the `tabular-metadata` skill.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run folio-assistant-core/scripts/tabular-xlsx.ts"
},
"io": {
"inputs": [
{
"name": "file",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/WorkbookPath",
"description": "Path to the `.xlsx` workbook.",
"required": true,
"arg": {
"positional": 0
}
},
{
"name": "doc-id",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/DocId",
"description": "The record's `doc_id`. Default: the file name without its extension.",
"required": false,
"arg": {
"flag": "--doc-id"
}
},
{
"name": "out",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Where to write `tabular.csvw.json`. Default: stdout.",
"required": false,
"arg": {
"flag": "--out"
}
}
],
"outputs": [
{
"name": "record",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
"description": "A `folio-tabular-csvw/v1` document, one table per block. Exit 2 when the file is not a SpreadsheetML workbook."
}
]
},
"satisfies": [
"tabular-metadata"
],
"requirements": {
"runtime": [
"bun"
],
"network": false
}
}