Table Schema

1.21.0 · active · verified Wed Apr 15

A utility library for working with Table Schema in Python, enabling validation, inference, and manipulation of tabular data based on the Table Schema standard. It is actively maintained with frequent releases, currently at version 1.21.0. An important notice indicates that the broader Frictionless Framework offers a more complete data solution, extending `tableschema`'s functionality.

Warnings

breaking Version `1.0` introduced significant breaking changes, including API renames (e.g., `tableschema.push/pull_resource` to `tableschema.Table`, `tableschema.model` to `tableschema.Schema`, `tableschema.types` to `tableschema.Field`) and changes in parameter signatures for `Field.cast/test_value`.
Fix: Review the `v1.0` migration guide and update API calls and parameter usage according to the new patterns. It is highly recommended to pin version ranges (e.g., `tableschema>=1.0,<2.0`) to avoid unexpected major version updates.
gotcha The `tableschema` library, while functional, is part of the broader Frictionless Data ecosystem. The Frictionless Framework (a separate library) provides extended and improved `tableschema` functionality as a more complete data solution. While existing `tableschema` code is not breaking, users are encouraged to consider the Frictionless Framework for new projects or future enhancements.
Fix: For new projects or if advanced data management features are needed, explore migrating to or directly using the Frictionless Framework for a more comprehensive solution. Existing `tableschema` implementations should continue to work as expected.
gotcha The `validate` function (e.g., `tableschema.validate`) is designed to validate a Table Schema *descriptor* itself, not to validate *data* against a given schema. Passing data directly to `validate` will not perform data validation.
Fix: To validate data against a schema, load the data using `Table` with a specified `schema` and then iterate through the data. Validation errors will be raised during iteration if the data does not conform to the schema (especially in strict mode). Use `Table.iter()` which handles casting and validation.
gotcha The library uses semantic versioning, meaning major versions (e.g., v1.x.x to v2.x.x) can introduce breaking changes. Relying on `tableschema` without a version constraint in your `requirements.txt` can lead to unexpected breakages when new major versions are released.
Fix: Always specify a version range for `tableschema` in your `requirements.txt` or `setup.py` (e.g., `tableschema>=1.0,<2.0`) to ensure predictable dependency behavior and prevent automatic upgrades to potentially breaking major versions.

Install

pip install tableschema Install stable version

Imports

Table
```
from tableschema import Table
```
Schema
```
from tableschema import Schema
```
Field
```
from tableschema import Field
```
validate
```
from tableschema import validate
```
infer
```
from tableschema import infer
```

Quickstart

This quickstart demonstrates how to initialize a `Table` with data and a schema, iterate through its rows, and infer a schema from raw data. It creates temporary `data.csv` and `schema.json` files to provide a runnable example.

import os
from tableschema import Table, Schema

# Create dummy data and schema files for demonstration
data_csv_content = """
id,name,age
1,Alice,30
2,Bob,24
3,Charlie,35
"""

schema_json_content = """
{
  "fields": [
    {"name": "id", "type": "integer"},
    {"name": "name", "type": "string"},
    {"name": "age", "type": "integer"}
  ]
}
"""

with open('data.csv', 'w') as f:
    f.write(data_csv_content)
with open('schema.json', 'w') as f:
    f.write(schema_json_content)

# 1. Create a Table instance with data and schema
table = Table('data.csv', schema='schema.json')

# 2. Print schema descriptor
print("Schema Descriptor:", table.schema.descriptor)

# 3. Read and print data as keyed rows
print("\nData Rows (keyed):")
for keyed_row in table.iter(keyed=True):
    print(keyed_row)

# 4. Infer schema from data
headers = ['id', 'name', 'age']
rows = [[1, 'Alice', 30], [2, 'Bob', 24], [3, 'Charlie', 35]]
inferred_schema_descriptor = Schema.infer(rows, headers)
print("\nInferred Schema Descriptor:", inferred_schema_descriptor)

# Clean up dummy files
os.remove('data.csv')
os.remove('schema.json')

view raw JSON →