Skip to content

python

Directory actions

More options

Directory actions

More options

Latest commit

History

History

python

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
demo
demo
src/json_structure
src/json_structure
tests
tests
.gitignore
.gitignore
README.md
README.md
pyproject.toml
pyproject.toml

README.md

JSON Structure Python SDK

PyPI versionPythonLicense: MIT

Python validators for JSON Structure schemas and instances.

JSON Structure is a type-oriented schema language for JSON, designed for defining data structures that can be validated and mapped to programming language types.

Installation

pip install json-structure

Quick Start

Validate a Schema

fromjson_structureimportSchemaValidatorschema= {
"$schema": "https://json-structure.org/meta/core/v0/#",
"$id": "https://example.com/person",
"name": "Person",
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "int32"},
"email": {"type": "string"}
},
"required": ["name"]
}
validator=SchemaValidator()
errors=validator.validate(schema)
iferrors:
print("Schema is invalid:")
forerrorinerrors:
print(f" - {error}")
else:
print("Schema is valid!")

Validate an Instance

fromjson_structureimportInstanceValidatorschema= {
"$schema": "https://json-structure.org/meta/core/v0/#",
"$id": "https://example.com/person",
"name": "Person",
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "int32"}
},
"required": ["name"]
}
instance= {
"name": "Alice",
"age": 30
}
validator=InstanceValidator(schema)
errors=validator.validate_instance(instance)
iferrors:
print("Instance is invalid:")
forerrorinerrors:
print(f" - {error}")
else:
print("Instance is valid!")

Features

Supported Types

All 34 types from JSON Structure Core v0 are supported:

Primitive Types:

  • string, number, integer, boolean, null
  • int8, uint8, int16, uint16, int32, uint32
  • int64, uint64, int128, uint128 (string-encoded)
  • float8, float, double, decimal
  • date, datetime, time, duration
  • uuid, uri, binary, jsonpointer

Compound Types:

  • object, array, set, map, tuple, choice, any

Extensions

  • Conditional Composition: allOf, anyOf, oneOf, not, if/then/else
  • Validation Addins: minimum, maximum, minLength, maxLength, pattern, etc.
  • Import Extension: $import, $importdefs for schema composition

Command Line Tools

# Validate a schema file
json-structure-check schema.json
# Validate an instance against a schema
json-structure-validate instance.json schema.json

API Reference

SchemaValidator

fromjson_structureimportSchemaValidatorvalidator=SchemaValidator(
allow_dollar=False, # Allow '$' in property namesallow_import=False, # Enable $import/$importdefsimport_map=None, # Dict mapping URIs to local filesextended=False, # Enable extended validation featuresexternal_schemas=None# List of schema dicts to sideload (matched by $id)
)
errors=validator.validate(schema_dict, source_text=None)

InstanceValidator

fromjson_structureimportInstanceValidatorvalidator=InstanceValidator(
root_schema, # The JSON Structure schema dictallow_import=False, # Enable $import/$importdefsimport_map=None, # Dict mapping URIs to local filesextended=False, # Enable extended validation featuresexternal_schemas=None# List of schema dicts to sideload (matched by $id)
)
errors=validator.validate_instance(instance)

Sideloading External Schemas

When using $import to reference external schemas, you can provide those schemas directly instead of fetching them from URIs:

fromjson_structureimportInstanceValidator# External schema that would normally be fetched from https://example.com/address.jsonaddress_schema= {
"$schema": "https://json-structure.org/meta/core/v0/#",
"$id": "https://example.com/address.json",
"name": "Address",
"type": "object",
"properties": {
"street": {"type": "string"},
"city": {"type": "string"}
}
}
# Main schema that imports the address schemamain_schema= {
"$schema": "https://json-structure.org/meta/core/v0/#",
"$id": "https://example.com/person",
"name": "Person",
"type": "object",
"properties": {
"name": {"type": "string"},
"address": {"type": {"$ref": "#/definitions/Imported/Address"}}
},
"definitions": {
"Imported": {
"$import": "https://example.com/address.json"
}
}
}
# Sideload the address schema - matched by $idvalidator=InstanceValidator(
main_schema,
allow_import=True,
external_schemas=[address_schema]
)
instance= {
"name": "Alice",
"address": {"street": "123 Main St", "city": "Seattle"}
}
errors=validator.validate_instance(instance)

You can supply multiple schemas to satisfy multiple imports. The schemas are matched by their $id field against the import URIs.

Development

# Clone the repository
git clone https://github.com/json-structure/sdk.git
cd sdk/python
# Install development dependencies
pip install -e ".[dev]"# Run tests
pytest
# Run tests with coverage
pytest --cov=json_structure --cov-report=term-missing

License

MIT License - see LICENSE for details.

Links