Overview
--------
[](https://travis-ci.org/pglass/py-openapi-schema-to-json-schema)
[](https://pypi.org/project/py-openapi-schema-to-json-schema/)
[](https://pypi.org/project/py-openapi-schema-to-json-schema/)
**This is a straight Python port of the MIT-licensed
[mikunn/openapi-schema-to-json-schema](https://github.com/mikunn/openapi-schema-to-json-schema)
([v2.1.0](https://github.com/mikunn/openapi-schema-to-json-schema/tree/v2.1.0))**.
This port is similarly MIT-licensed.
It converts from [OpenAPI 3.0](
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md) to
[JSON Schema Draft 4](http://json-schema.org/specification-links.html#draft-4).
## Why?
OpenAPI 3 Schemas and JSON Schemas are mostly similar. However, JSON Schema
validators are unaware of the differences between the two formats. This means
that validating request/response JSON using a standard JSON Schema validator
with OpenAPI 3 Schemas will result in incorrect validations in certain common
cases.
One way to solve this problem is to translate the OpenAPI 3 schema to JSON
Schema, which is the purpose of this library.
See [here](https://github.com/mikunn/openapi-schema-to-json-schema/tree/v2.1.0#why)
for more rationale, as well as [Phil Sturgeon's blog post](
https://philsturgeon.uk/api/2018/03/30/openapi-and-json-schema-divergence/)
about the problem.
## Features
* converts OpenAPI 3.0 Schema Object to JSON Schema Draft 4
* deletes `nullable` and adds `"null"` to `type` array if `nullable` is `true` and `type` is present
* adds `{"type": "null"}` to `oneOf` or `anyOf` array if `nullable` is `true` and `type` is _not_ present
* supports deep structures with nested `allOf`s etc.
* removes [OpenAPI specific
properties](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-20)
such as `discriminator`, `deprecated` etc. unless specified otherwise
* optionally supports `patternProperties` with `x-patternProperties` in the
Schema Object
**NOTE**: `$ref`s are not dereferenced. You will need another library to
read the spec and follow `$ref` fields.
## Installation
```bash
$ pip install py-openapi-schema-to-json-schema
```
## Usage
```python
import json
from openapi_schema_to_json_schema import to_json_schema
openapi_schema = {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": True,
}
},
"x-patternProperties": {
"^[a-z]+$": {
"type": "number",
}
}
}
options = {"supportPatternProperties": True}
converted = to_json_schema(openapi_schema, options)
print(json.dumps(converted, indent=2))
```
This outputs the following JSON schema. This shows the conversion of
`nullable: True` to `type: ["string", "null"]`, and the enablement of
unsupported JSON Schema features using OpenAPI extension fields
(`x-patternProperties` -> `patternProperties`).
```json
{
"patternProperties": {
"^[a-z]+$": {
"type": "number"
}
},
"properties": {
"name": {
"type": [
"string",
"null"
]
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object"
}
```
### Options
The `to_json_schema` function accepts an `options` dictionary as the second
argument.
```python
# Defaults
options = {
'cloneSchema': True,
'dateToDateTime': False,
'supportPatternProperties': False,
'keepNotSupported': [],
'patternPropertiesHandler':
openapi_schema_to_json_schema.patternPropertiesHandler,
'removeReadOnly': False,
'removeWriteOnly': True,
}
```
#### `cloneSchema` (bool)
If set to `False`, converts the provided schema in place. If `True`, clones the
schema using `copy.deepcopy`. Defaults to `True`.
#### `dateToDateTime` (bool)
This is `False` by default and leaves `date` format as is. If set to `True`,
sets `format: 'date'` to `format: 'date-time'`.
For example
```python
import json
from openapi_schema_to_json_schema import to_json_schema
schema = {
'type': 'string',
'format': 'date',
}
converted = to_json_schema(schema, {'dateToDateTime': True})
print(json.dumps(converted, indent=2))
```
prints
```json
{
"format": "date-time",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "string"
}
```
#### `keepNotSupported` (list)
By default, the following fields are removed from the result schema:
`nullable`, `discriminator`, `readOnly`, `writeOnly`, `xml`, `externalDocs`,
`example` and `deprecated` as they are not supported by JSON Schema Draft 4.
Provide a list of the ones you want to keep (as strings) and they won't be
removed.
#### `removeReadOnly` (bool)
If set to `True`, will remove properties set as `readOnly`. If the property is
set as `required`, it will be removed from the `required` list as well. The
property will be removed even if `readOnly` is set to be kept with
`keepNotSupported`.
#### `removeWriteOnly` (bool)
Similar to `removeReadOnly`, but for `writeOnly` properties.
#### `supportPatternProperties` (bool)
If set to `True` and `x-patternProperties` property is present, change
`x-patternProperties` to `patternProperties` and call
`patternPropertiesHandler`. If `patternPropertiesHandler` is not defined, call
the default handler. See `patternPropertiesHandler` for more information.
#### `patternPropertiesHandler` (function)
Provide a function to handle pattern properties and set
`supportPatternProperties` to take effect. The function takes the schema where
`x-patternProperties` is defined on the root level. At this point
`x-patternProperties` is changed to `patternProperties`. It must return the
modified schema.
If the handler is not provided, the default handler is used. If
`additionalProperties` is set and is an object, the default handler sets it to
false if the `additionalProperties` object has deep equality with a pattern
object inside `patternProperties`. This is because we might want to define
`additionalProperties` in OpenAPI spec file, but want to validate against a
pattern. The pattern would turn out to be useless if `additionalProperties` of
the same structure were allowed. Create you own handler to override this
functionality.
See `tests/to_jsonschema/test_pattern_properties.py` for examples of this.
Credits
-------
- [mikunn](https://github.com/mikunn) for the [original
openapi-schema-to-json-schema](https://github.com/mikunn/openapi-schema-to-json-schema)
- [Phil Sturgeon](https://github.com/philsturgeon) for his great
[blog post](https://philsturgeon.uk/api/2018/03/30/openapi-and-json-schema-divergence/)
about the issue (and his [reverse implementation](https://github.com/wework/json-schema-to-openapi-schema))
Raw data
{
"_id": null,
"home_page": "https://github.com/pglass/py-openapi-schema-to-json-schema",
"name": "py-openapi-schema-to-json-schema",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "openapi json schema convert translate",
"author": "Paul Glass",
"author_email": "pnglass@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/51/c5/5d6a9b08df175a886b4085eb51e0351854a96e4896a367b2373ad19d881b/py-openapi-schema-to-json-schema-0.0.3.tar.gz",
"platform": "",
"description": "Overview\n--------\n\n[](https://travis-ci.org/pglass/py-openapi-schema-to-json-schema)\n[](https://pypi.org/project/py-openapi-schema-to-json-schema/)\n[](https://pypi.org/project/py-openapi-schema-to-json-schema/)\n\n\n**This is a straight Python port of the MIT-licensed\n[mikunn/openapi-schema-to-json-schema](https://github.com/mikunn/openapi-schema-to-json-schema)\n([v2.1.0](https://github.com/mikunn/openapi-schema-to-json-schema/tree/v2.1.0))**.\nThis port is similarly MIT-licensed.\n\nIt converts from [OpenAPI 3.0](\nhttps://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md) to\n[JSON Schema Draft 4](http://json-schema.org/specification-links.html#draft-4).\n\n## Why?\n\nOpenAPI 3 Schemas and JSON Schemas are mostly similar. However, JSON Schema\nvalidators are unaware of the differences between the two formats. This means\nthat validating request/response JSON using a standard JSON Schema validator\nwith OpenAPI 3 Schemas will result in incorrect validations in certain common\ncases.\n\nOne way to solve this problem is to translate the OpenAPI 3 schema to JSON\nSchema, which is the purpose of this library.\n\nSee [here](https://github.com/mikunn/openapi-schema-to-json-schema/tree/v2.1.0#why)\nfor more rationale, as well as [Phil Sturgeon's blog post](\nhttps://philsturgeon.uk/api/2018/03/30/openapi-and-json-schema-divergence/)\nabout the problem.\n\n## Features\n\n* converts OpenAPI 3.0 Schema Object to JSON Schema Draft 4\n* deletes `nullable` and adds `\"null\"` to `type` array if `nullable` is `true` and `type` is present\n* adds `{\"type\": \"null\"}` to `oneOf` or `anyOf` array if `nullable` is `true` and `type` is _not_ present\n* supports deep structures with nested `allOf`s etc.\n* removes [OpenAPI specific\n properties](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-20)\nsuch as `discriminator`, `deprecated` etc. unless specified otherwise\n* optionally supports `patternProperties` with `x-patternProperties` in the\n Schema Object\n\n**NOTE**: `$ref`s are not dereferenced. You will need another library to\nread the spec and follow `$ref` fields.\n\n\n## Installation\n\n```bash\n$ pip install py-openapi-schema-to-json-schema\n```\n\n\n## Usage\n\n```python\nimport json\nfrom openapi_schema_to_json_schema import to_json_schema\n\nopenapi_schema = {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"nullable\": True,\n }\n },\n \"x-patternProperties\": {\n \"^[a-z]+$\": {\n \"type\": \"number\",\n }\n }\n}\n\noptions = {\"supportPatternProperties\": True}\nconverted = to_json_schema(openapi_schema, options)\n\nprint(json.dumps(converted, indent=2))\n```\n\nThis outputs the following JSON schema. This shows the conversion of\n`nullable: True` to `type: [\"string\", \"null\"]`, and the enablement of\nunsupported JSON Schema features using OpenAPI extension fields\n(`x-patternProperties` -> `patternProperties`).\n\n```json\n{\n \"patternProperties\": {\n \"^[a-z]+$\": {\n \"type\": \"number\"\n }\n },\n \"properties\": {\n \"name\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n \"type\": \"object\"\n}\n```\n\n### Options\n\nThe `to_json_schema` function accepts an `options` dictionary as the second\nargument.\n\n```python\n# Defaults\noptions = {\n 'cloneSchema': True,\n 'dateToDateTime': False,\n 'supportPatternProperties': False,\n 'keepNotSupported': [],\n 'patternPropertiesHandler':\n openapi_schema_to_json_schema.patternPropertiesHandler,\n 'removeReadOnly': False,\n 'removeWriteOnly': True,\n}\n```\n\n#### `cloneSchema` (bool)\n\nIf set to `False`, converts the provided schema in place. If `True`, clones the\nschema using `copy.deepcopy`. Defaults to `True`.\n\n#### `dateToDateTime` (bool)\n\nThis is `False` by default and leaves `date` format as is. If set to `True`,\nsets `format: 'date'` to `format: 'date-time'`.\n\nFor example\n\n```python\nimport json\nfrom openapi_schema_to_json_schema import to_json_schema\n\nschema = {\n 'type': 'string',\n 'format': 'date',\n}\n\nconverted = to_json_schema(schema, {'dateToDateTime': True})\n\nprint(json.dumps(converted, indent=2))\n```\n\nprints\n\n```json\n{\n \"format\": \"date-time\",\n \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n \"type\": \"string\"\n}\n```\n\n#### `keepNotSupported` (list)\n\nBy default, the following fields are removed from the result schema:\n`nullable`, `discriminator`, `readOnly`, `writeOnly`, `xml`, `externalDocs`,\n`example` and `deprecated` as they are not supported by JSON Schema Draft 4.\nProvide a list of the ones you want to keep (as strings) and they won't be\nremoved.\n\n#### `removeReadOnly` (bool)\n\nIf set to `True`, will remove properties set as `readOnly`. If the property is\nset as `required`, it will be removed from the `required` list as well. The\nproperty will be removed even if `readOnly` is set to be kept with\n`keepNotSupported`.\n\n#### `removeWriteOnly` (bool)\n\nSimilar to `removeReadOnly`, but for `writeOnly` properties.\n\n#### `supportPatternProperties` (bool)\n\nIf set to `True` and `x-patternProperties` property is present, change\n`x-patternProperties` to `patternProperties` and call\n`patternPropertiesHandler`. If `patternPropertiesHandler` is not defined, call\nthe default handler. See `patternPropertiesHandler` for more information.\n\n#### `patternPropertiesHandler` (function)\n\nProvide a function to handle pattern properties and set\n`supportPatternProperties` to take effect. The function takes the schema where\n`x-patternProperties` is defined on the root level. At this point\n`x-patternProperties` is changed to `patternProperties`. It must return the\nmodified schema.\n\nIf the handler is not provided, the default handler is used. If\n`additionalProperties` is set and is an object, the default handler sets it to\nfalse if the `additionalProperties` object has deep equality with a pattern\nobject inside `patternProperties`. This is because we might want to define\n`additionalProperties` in OpenAPI spec file, but want to validate against a\npattern. The pattern would turn out to be useless if `additionalProperties` of\nthe same structure were allowed. Create you own handler to override this\nfunctionality.\n\nSee `tests/to_jsonschema/test_pattern_properties.py` for examples of this.\n\n\nCredits\n-------\n\n- [mikunn](https://github.com/mikunn) for the [original\nopenapi-schema-to-json-schema](https://github.com/mikunn/openapi-schema-to-json-schema)\n- [Phil Sturgeon](https://github.com/philsturgeon) for his great \n[blog post](https://philsturgeon.uk/api/2018/03/30/openapi-and-json-schema-divergence/)\nabout the issue (and his [reverse implementation](https://github.com/wework/json-schema-to-openapi-schema))\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert OpenAPI Schemas to JSON Schemas",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/pglass/py-openapi-schema-to-json-schema"
},
"split_keywords": [
"openapi",
"json",
"schema",
"convert",
"translate"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1c1aa43f73b8762512ab3358aac96c6c6d1d9ec4dbb3bbb99d82c2e90e5f3d16",
"md5": "781fdb33e90caf6680c57454ea1be4ce",
"sha256": "456802186309257a9667fd50eca7c6ff6eaf9930ab09dcc87c54537e01066f09"
},
"downloads": -1,
"filename": "py_openapi_schema_to_json_schema-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "781fdb33e90caf6680c57454ea1be4ce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6954,
"upload_time": "2020-07-25T05:34:50",
"upload_time_iso_8601": "2020-07-25T05:34:50.932835Z",
"url": "https://files.pythonhosted.org/packages/1c/1a/a43f73b8762512ab3358aac96c6c6d1d9ec4dbb3bbb99d82c2e90e5f3d16/py_openapi_schema_to_json_schema-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "51c55d6a9b08df175a886b4085eb51e0351854a96e4896a367b2373ad19d881b",
"md5": "5fbcbf4a38fbee6206cede45cf855157",
"sha256": "d557afb6bcc45d62a1383ada0ad57515421552efa3b2e07b2264e5b9e1e9634e"
},
"downloads": -1,
"filename": "py-openapi-schema-to-json-schema-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "5fbcbf4a38fbee6206cede45cf855157",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5964,
"upload_time": "2020-07-25T05:34:52",
"upload_time_iso_8601": "2020-07-25T05:34:52.287557Z",
"url": "https://files.pythonhosted.org/packages/51/c5/5d6a9b08df175a886b4085eb51e0351854a96e4896a367b2373ad19d881b/py-openapi-schema-to-json-schema-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-07-25 05:34:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pglass",
"github_project": "py-openapi-schema-to-json-schema",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "py-openapi-schema-to-json-schema"
}
JSON
