Bravado Core

6.1.1 · active · verified Wed Apr 15

bravado-core is a Python library that implements the Swagger 2.0 (OpenAPI Specification v2.0). It provides core functionalities for both client-side and server-side support, including Swagger Schema ingestion and validation, marshalling and unmarshalling of requests and responses, and modeling Swagger definitions as Python classes or dictionaries. The current version is 6.1.1, and it maintains an active, though not rapid, release cadence with new versions typically addressing bugs or minor features rather than frequent major changes.

Warnings

breaking In version 5.17.0, the equality (==) feature on `Spec` objects was removed. Direct comparison using `==` will no longer work as expected and might lead to errors or unexpected behavior.
Fix: Use the `is_equal` methods provided by `bravado-core` for comparing `Spec` objects if equality checking is required.
breaking Version 5.0.0 introduced significant breaking changes, including a refactoring of model discovery. The signature of `bravado_core.spec_flattening.flattened_spec` was updated, and several public methods (e.g., `tag_models`, `bless_models`, `collect_models` from `bravado_core.model`, and `post_process_spec` from `bravado_core.spec`) were removed or changed their interface.
Fix: Review the changelog and migration guides for `bravado-core` 5.0.0. Update calls to `flattened_spec` with the new signature and replace usage of removed model-related public methods with their new equivalents or recommended patterns.
gotcha Older versions of `bravado-core` (specifically those constrained by `jsonschema<4.0.0`) are not compatible with `jsonschema>=4.0.0`. Using a newer `jsonschema` might cause `bravado-core` to break, especially in offline environments where dependency resolution might be less strict.
Fix: Ensure that your `jsonschema` dependency is pinned to a version compatible with your `bravado-core` installation, typically `jsonschema>=2.5.1,<4.0.0` as specified by `bravado-core`'s `install_requires`. If using a system that requires `jsonschema>=4.0.0`, consider upgrading `bravado-core` to a version that officially supports it, if available, or finding a workaround.
gotcha When loading a spec using `Spec.from_dict()`, the `spec.definitions` dictionary (which contains the Python models) might appear empty if the `origin_url` parameter is not provided or is incorrect, especially when loading local files. `bravado-core` relies on `origin_url` to correctly resolve internal references and build models.
Fix: Always provide a correct `origin_url` when using `Spec.from_dict()` for local files. For example, use `Path.cwd().as_uri()` or a suitable file URI for the `origin_url` parameter.
gotcha If your Swagger/OpenAPI spec defines custom formats (e.g., 'uuid', 'email', 'guid') and these are not registered with `bravado-core` via `SwaggerFormat`, you will see warnings like 'X format is not registered with bravado-core!' This can lead to validation issues or incorrect data handling for these formats.
Fix: Define custom formats using `bravado_core.formatter.SwaggerFormat` and pass them in the `config` dictionary when creating the `Spec` object (e.g., `config={'formats': [my_custom_format]}`).
deprecated Support for Python 3.5 was dropped in `bravado-core` version 5.17.0. While earlier versions might still work, they are no longer officially supported.
Fix: Upgrade to Python 3.7 or newer. The current recommended Python version is >=3.7.

Install

pip install bravado-core Install stable release

Imports

Spec
```
from bravado_core.spec import Spec
```
The central object for loading and interacting with a Swagger/OpenAPI specification.
SwaggerFormat
```
from bravado_core.formatter import SwaggerFormat
```
Used to define and register custom data formats for validation and marshalling.
SwaggerValidationError
```
from bravado_core.exception import SwaggerValidationError
```
Exception raised by bravado-core during validation failures.

Quickstart

This quickstart demonstrates how to load a Swagger/OpenAPI specification using `Spec.from_dict`, access defined models as Python types, and validate data against those models. It highlights basic model instantiation and the core validation feature of `bravado-core`.

import json
from bravado_core.spec import Spec
from bravado_core.validate import validate_object

# Example Swagger 2.0 spec (usually loaded from a file or URL)
swagger_dict = {
    "swagger": "2.0",
    "info": {"title": "Test API", "version": "1.0.0"},
    "paths": {},
    "definitions": {
        "Pet": {
            "type": "object",
            "required": ["name"],
            "properties": {
                "name": {"type": "string"},
                "age": {"type": "integer", "format": "int32", "minimum": 0}
            }
        }
    }
}

# Load the spec
spec = Spec.from_dict(swagger_dict)
print("Swagger spec loaded successfully.")

# Access a defined model
Pet = spec.definitions['Pet']
my_pet = Pet(name='Rex', age=5)
print(f"Created Pet object: Name={my_pet.name}, Age={my_pet.age}")

# Validate an object against a schema
valid_pet_data = {'name': 'Whiskers', 'age': 2}
try:
    validate_object(swagger_spec=spec, json_value=valid_pet_data, swagger_type=spec.definitions['Pet'].swagger_spec)
    print(f"Valid pet data: {valid_pet_data} is valid.")
except Exception as e:
    print(f"Validation failed for valid data: {e}")

invalid_pet_data = {'name': 'Buddy', 'age': -1}
try:
    validate_object(swagger_spec=spec, json_value=invalid_pet_data, swagger_type=spec.definitions['Pet'].swagger_spec)
    print("This line should not be reached for invalid data.")
except Exception as e:
    print(f"Validation error for invalid pet data: {invalid_pet_data} -> {e}")

view raw JSON →