Skip to content

Check your data in a few minutes

You will validate an order amount, inspect a rejected value and reuse the same contract across a small batch. Everything runs locally. You need Python 3.11+; you do not need a database, server, API key or sample download.

The examples on this page are verified with the published pycharter==0.0.67. See capability status for the broader product journey.

1. Install

Use a virtual environment for your project, then install:

python -m pip install pycharter

For the exact documented release, use python -m pip install "pycharter==0.0.67". Installation covers virtual environments and optional extras.

2. Describe acceptable data

Run the following Python blocks in the same script or interpreter session. This example requires an order ID and a nonnegative amount:

from pycharter import Validator

contract = {
    "json_schema": {
        "version": "1.0.0",
        "type": "object",
        "properties": {
            "order_id": {"type": "string", "minLength": 1},
            "amount": {"type": "number", "minimum": 0},
        },
        "required": ["order_id", "amount"],
        "additionalProperties": False,
    }
}
validator = Validator.from_dict(contract)

A contract is your explicit definition of acceptable data. You can add named coercion rules, business checks and metadata as your requirements grow.

3. Accept a record and inspect a failure

accepted = validator.validate({"order_id": "A-100", "amount": "19.95"})
print(accepted.is_valid)       # True
print(accepted.data.amount)    # 19.95

rejected = validator.validate({"order_id": "A-101", "amount": -5})
print(rejected.is_valid)       # False
print(rejected.errors)         # Identifies 'amount' and the minimum requirement

Compatible numeric strings are coerced before validation by default. To require strict types, construct Validator.from_dict(contract, strict_types=True). Check is_valid before consuming data. Failure messages explain which requirement was not met; keep sensitive inputs out of shared logs.

Correct the record without weakening the contract:

corrected = validator.validate({"order_id": "A-101", "amount": 5})
print(corrected.is_valid)      # True

4. Apply the same rules to a batch

records = [
    {"order_id": "A-100", "amount": 19.95},
    {"order_id": "A-101", "amount": -5},
    {"order_id": "A-102", "amount": 0},
]
results = [validator.validate(record) for record in records]
print(sum(result.is_valid for result in results))  # 2
print(sum(not result.is_valid for result in results))  # 1

You now have two accepted records and one rejection. This is a validation result; it has not written data to a destination. Use the DataFrame recipe for table-oriented work.

5. Keep the contract and continue from the terminal

This block writes two small files in your current directory. Run it in your example project so existing files with these names are not overwritten.

import json
from pathlib import Path

Path("orders-contract.json").write_text(json.dumps(contract, indent=2) + "\n")
Path("orders.jsonl").write_text(
    "".join(json.dumps(record) + "\n" for record in records)
)

The CLI validates the same records against the same saved contract:

pycharter validate orders-contract.json orders.jsonl

Expect a validation failure: one of the three records deliberately violates the contract. Correct the negative amount and rerun. From Python, reload the same definition with Validator.from_file("orders-contract.json").

Choose the next useful step