# JSON Schema Generator for MongoEngine Documents
## 📖 About the project
### What is this and why?
This package provides a mixin class that extends a MongoEngine document's functionality by adding a `.json_schema()` method and allows generating a JSON schema directly from the document. Generated schema then can be used in API documentation or form validation and automatic form generation on a web application frontend, etc.
Generated schema should be compatible with [JSON schema specification](https://json-schema.org/specification.html) version Draft-7 and newer.
Tested on
- Python 3.10
- MongoEngine 0.27.0
but should work on Python >= `3.7` and MongoEngine >= `0.20.0` without any problems.
## 🛠 Installation
```sh
pip install mongoengine-jsonschema
```
## 💻 Getting started
Add `JsonSchemaMixin` to your document class as parent. Resolution order matters, so always place MongoEngine document first.
```python
import mongoengine as me
from mongoengine_jsonschema import JsonSchemaMixin
class Person(me.Document, JsonSchemaMixin):
name = me.StringField(required=True, min_length=1, max_length=32)
age = me.IntField(min_value=0)
```
Then you can generate JSON schema by calling `.json_schema()` method.
```python
Person.json_schema()
```
which returns the schema as a Python dictionary
```python
{
'$id': '/schemas/Person',
'title': 'Person',
'type': 'object',
'properties': {
'age': {
'type': 'integer',
'title': 'Age',
'minimum': 0
},
'name': {
'type': 'string',
'title': 'Name',
'minLength': 1,
'maxLength': 32
}
},
'required': ['name'],
'additionalProperties': False
}
```
### Example
Check out [example.md](https://github.com/symphonicityy/mongoengine-jsonschema/blob/main/example.md) for a more extensive example.
### Features
- Inheritance is supported. Make sure you add mixin to parent class.
- `additionalProperties` is set to `False` for `DynamicDocument` and `DynamicEmbeddedDocument` classes.
- `required` keyword can be removed by setting `strict` argument to `False` (`.json_schema(strict=False)`). This is useful for partial validation when updating documents using HTTP PATCH method.
- Constraints for special `StringField` types such as `EmailField`, `URLField`, `UUIDField`, `DateTimeField` etc. are applied to schema using `format` and/or `pattern` keywords.
- Fields derived from `GeoJsonBaseField` can be validated for both array and object types as supported by MongoEngine.
- Field arguments/constraints `required`, `min_length`, `max_length`, `min_value`, `max_value`, `default`, `choices`, `regex` and `url_regex` (for `URLField`) are supported and reflected to schema.
- Excluding a field from schema is possible with setting field argument `exclude_from_schema` to `True`. Example:
```python
name = me.StringField(exclude_from_schema=True)
```
- Auto-generates human-friendly (first-letter capitalized, separate words) `title` from both document (PascalCase) and field names (snake_case). Keeps uppercase acronyms as is, e.g. `page_URL` -> `Page URL`.
- For `ListField` types, `required=True` means it cannot be empty, therefore, schema defines this constraint with `minItems` keyword.
- Custom schemas can be defined directly in model class with `_JSONSCHEMA` class attribute. Setting a `_JSONSCHEMA` attribute will bypass JSON schema generation.
### Limitations
- `FileField`, `ImageField` fields are not supported
- `PolygonField` and `MultiPolygonField` must start and end at the same point, but this is not enforced by generated schema
- `schemes` argument is ignored for `URLField`
- `domain_whitelist`, `allow_utf8_user`, `allow_ip_domain` arguments are ignored for `EmailField`
- The following fields are defined in schema as strings and may require field specific conversion before assigning to a document's attribute:
- `ObjectIdField`
- `BinaryField`
- `DateTimeField`
- `ComplexDateTimeField`
- `DateField`
- `ReferenceField`
- `LazyReferenceField`
- `CachedReferenceField`
- `GenericReferenceField`
- `GenericLazyReferenceField`
## 👥 Contact <a name="contact"/>
- Email: [myusuferoglu@gmail.com](<mailto:myusuferoglu@gmail.com>)
- GitHub: [symphonicityy](https://github.com/symphonicityy)
- Project Link: (https://github.com/symphonicityy/mongoengine-jsonschema)
## 🤝 Contributing <a name="contributing"/>
Contributions, issues, and feature requests are welcome!
Raw data
{
"_id": null,
"home_page": "https://github.com/symphonicityy/mongoengine-jsonschema",
"name": "mongoengine-jsonschema",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Yusuf Eroglu",
"author_email": "myusuferoglu@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cd/b7/76cd5a4a5cbecaceb2f58c5bebf6159b7ada53ec7f2144d644fc7e99ba26/mongoengine-jsonschema-0.1.3.tar.gz",
"platform": "any",
"description": "# JSON Schema Generator for MongoEngine Documents\n\n## \ud83d\udcd6 About the project\n\n### What is this and why?\nThis package provides a mixin class that extends a MongoEngine document's functionality by adding a `.json_schema()` method and allows generating a JSON schema directly from the document. Generated schema then can be used in API documentation or form validation and automatic form generation on a web application frontend, etc.\n\nGenerated schema should be compatible with [JSON schema specification](https://json-schema.org/specification.html) version Draft-7 and newer.\n\nTested on\n- Python 3.10\n- MongoEngine 0.27.0\n\nbut should work on Python >= `3.7` and MongoEngine >= `0.20.0` without any problems.\n\n## \ud83d\udee0 Installation\n\n```sh\npip install mongoengine-jsonschema\n```\n\n## \ud83d\udcbb Getting started\nAdd `JsonSchemaMixin` to your document class as parent. Resolution order matters, so always place MongoEngine document first.\n```python\nimport mongoengine as me\nfrom mongoengine_jsonschema import JsonSchemaMixin\n\nclass Person(me.Document, JsonSchemaMixin):\n name = me.StringField(required=True, min_length=1, max_length=32)\n age = me.IntField(min_value=0)\n\n```\nThen you can generate JSON schema by calling `.json_schema()` method.\n```python\nPerson.json_schema()\n```\nwhich returns the schema as a Python dictionary\n```python\n{\n '$id': '/schemas/Person',\n 'title': 'Person',\n 'type': 'object',\n 'properties': {\n 'age': {\n 'type': 'integer',\n 'title': 'Age',\n 'minimum': 0\n },\n 'name': {\n 'type': 'string',\n 'title': 'Name',\n 'minLength': 1,\n 'maxLength': 32\n }\n },\n 'required': ['name'],\n 'additionalProperties': False\n}\n```\n\n### Example\nCheck out [example.md](https://github.com/symphonicityy/mongoengine-jsonschema/blob/main/example.md) for a more extensive example.\n\n### Features\n- Inheritance is supported. Make sure you add mixin to parent class.\n- `additionalProperties` is set to `False` for `DynamicDocument` and `DynamicEmbeddedDocument` classes.\n- `required` keyword can be removed by setting `strict` argument to `False` (`.json_schema(strict=False)`). This is useful for partial validation when updating documents using HTTP PATCH method.\n- Constraints for special `StringField` types such as `EmailField`, `URLField`, `UUIDField`, `DateTimeField` etc. are applied to schema using `format` and/or `pattern` keywords.\n- Fields derived from `GeoJsonBaseField` can be validated for both array and object types as supported by MongoEngine.\n- Field arguments/constraints `required`, `min_length`, `max_length`, `min_value`, `max_value`, `default`, `choices`, `regex` and `url_regex` (for `URLField`) are supported and reflected to schema.\n- Excluding a field from schema is possible with setting field argument `exclude_from_schema` to `True`. Example: \n ```python \n name = me.StringField(exclude_from_schema=True)\n ```\n- Auto-generates human-friendly (first-letter capitalized, separate words) `title` from both document (PascalCase) and field names (snake_case). Keeps uppercase acronyms as is, e.g. `page_URL` -> `Page URL`.\n- For `ListField` types, `required=True` means it cannot be empty, therefore, schema defines this constraint with `minItems` keyword.\n- Custom schemas can be defined directly in model class with `_JSONSCHEMA` class attribute. Setting a `_JSONSCHEMA` attribute will bypass JSON schema generation.\n\n### Limitations\n- `FileField`, `ImageField` fields are not supported\n- `PolygonField` and `MultiPolygonField` must start and end at the same point, but this is not enforced by generated schema\n- `schemes` argument is ignored for `URLField`\n- `domain_whitelist`, `allow_utf8_user`, `allow_ip_domain` arguments are ignored for `EmailField`\n- The following fields are defined in schema as strings and may require field specific conversion before assigning to a document's attribute:\n - `ObjectIdField`\n - `BinaryField`\n - `DateTimeField`\n - `ComplexDateTimeField`\n - `DateField`\n - `ReferenceField`\n - `LazyReferenceField`\n - `CachedReferenceField`\n - `GenericReferenceField`\n - `GenericLazyReferenceField`\n\n\n## \ud83d\udc65 Contact <a name=\"contact\"/>\n- Email: [myusuferoglu@gmail.com](<mailto:myusuferoglu@gmail.com>)\n- GitHub: [symphonicityy](https://github.com/symphonicityy)\n- Project Link: (https://github.com/symphonicityy/mongoengine-jsonschema)\n\n## \ud83e\udd1d Contributing <a name=\"contributing\"/>\nContributions, issues, and feature requests are welcome!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MongoEngine JSON Schema Generator",
"version": "0.1.3",
"project_urls": {
"Code": "https://github.com/symphonicityy/mongoengine-jsonschema",
"Documentation": "https://github.com/symphonicityy/mongoengine-jsonschema/blob/main/README.md",
"Homepage": "https://github.com/symphonicityy/mongoengine-jsonschema"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6f2e21016824ac3ddaf8292706ac5ec7cb15d190cb93191536890e3c41a4b78c",
"md5": "3c4cd315c0d9ad35e135bdba65bdee3c",
"sha256": "1661e92854aedb902b35c4ed1cd509b766c12f960b63f8996b26ea4704fd364c"
},
"downloads": -1,
"filename": "mongoengine_jsonschema-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c4cd315c0d9ad35e135bdba65bdee3c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7671,
"upload_time": "2023-08-01T11:01:07",
"upload_time_iso_8601": "2023-08-01T11:01:07.285545Z",
"url": "https://files.pythonhosted.org/packages/6f/2e/21016824ac3ddaf8292706ac5ec7cb15d190cb93191536890e3c41a4b78c/mongoengine_jsonschema-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cdb776cd5a4a5cbecaceb2f58c5bebf6159b7ada53ec7f2144d644fc7e99ba26",
"md5": "abe2c0f28d3d5af4eef14bebea557fdb",
"sha256": "b1709517df8b57ae8acb7aa963331e007a94c76167e6eb305a64a29b479dbc0d"
},
"downloads": -1,
"filename": "mongoengine-jsonschema-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "abe2c0f28d3d5af4eef14bebea557fdb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13045,
"upload_time": "2023-08-01T11:01:08",
"upload_time_iso_8601": "2023-08-01T11:01:08.930802Z",
"url": "https://files.pythonhosted.org/packages/cd/b7/76cd5a4a5cbecaceb2f58c5bebf6159b7ada53ec7f2144d644fc7e99ba26/mongoengine-jsonschema-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-01 11:01:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "symphonicityy",
"github_project": "mongoengine-jsonschema",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "mongoengine",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "mongomock",
"specs": []
},
{
"name": "jsonschema",
"specs": []
},
{
"name": "blinker",
"specs": []
}
],
"lcname": "mongoengine-jsonschema"
}
JSON
