alchemyjsonschema

features

alchemyjsonschema is the library for converting sqlalchemys’s model to jsonschema.

using alchemyjsonschema as command
using alchemyjsonschema as library

as library

having three output styles.

NoForeignKeyWalker – ignore relationships
ForeignKeyWalker – expecting the information about relationship is foreign key
StructuralWalker – fullset output(expecting the information about relationship is full JSON data)

examples

dumping json with above three output styles.

target models are here. Group and User.

# -*- coding:utf-8 -*-
import sqlalchemy as sa
import sqlalchemy.orm as orm
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()


class Group(Base):
    """model for test"""
    __tablename__ = "Group"

    pk = sa.Column(sa.Integer, primary_key=True, doc="primary key")
    name = sa.Column(sa.String(255), default="", nullable=False)


class User(Base):
    __tablename__ = "User"

    pk = sa.Column(sa.Integer, primary_key=True, doc="primary key")
    name = sa.Column(sa.String(255), default="", nullable=True)
    group_id = sa.Column(sa.Integer, sa.ForeignKey(Group.pk), nullable=False)
    group = orm.relationship(Group, uselist=False, backref="users")

NoForeignKeyWalker

import pprint as pp
from alchemyjsonschema import SchemaFactory
from alchemyjsonschema import NoForeignKeyWalker

factory = SchemaFactory(NoForeignKeyWalker)
pp.pprint(factory(User))

"""
{'properties': {'name': {'maxLength': 255, 'type': 'string'},
                'pk': {'description': 'primary key', 'type': 'integer'}},
 'required': ['pk'],
 'title': 'User',
 'type': 'object'}
"""

ForeignKeyWalker

import pprint as pp
from alchemyjsonschema import SchemaFactory
from alchemyjsonschema import ForeignKeyWalker

factory = SchemaFactory(ForeignKeyWalker)
pp.pprint(factory(User))

"""
{'properties': {'group_id': {'type': 'integer'},
                'name': {'maxLength': 255, 'type': 'string'},
                'pk': {'description': 'primary key', 'type': 'integer'}},
 'required': ['pk', 'group_id'],
 'title': 'User',
 'type': 'object'}
"""

StructuralWalker

import pprint as pp
from alchemyjsonschema import SchemaFactory
from alchemyjsonschema import StructuralWalker

factory = SchemaFactory(StructuralWalker)
pp.pprint(factory(User))

"""
{'definitions': {'Group': {'properties': {'pk': {'description': 'primary key',
                                                 'type': 'integer'},
                                          'name': {'maxLength': 255,
                                                   'type': 'string'}},
                           'type': 'object'}},
 'properties': {'pk': {'description': 'primary key', 'type': 'integer'},
                'name': {'maxLength': 255, 'type': 'string'},
                'group': {'$ref': '#/definitions/Group'}},
 'required': ['pk'],
 'title': 'User',
 'type': 'object'}
"""

pp.pprint(factory(Group))

"""
{'definitions': {'User': {'properties': {'pk': {'description': 'primary key',
                                                'type': 'integer'},
                                         'name': {'maxLength': 255,
                                                  'type': 'string'}},
                          'type': 'object'}},
 'description': 'model for test',
 'properties': {'pk': {'description': 'primary key', 'type': 'integer'},
                'name': {'maxLength': 255, 'type': 'string'},
                'users': {'items': {'$ref': '#/definitions/User'},
                          'type': 'array'}},
 'required': ['pk', 'name'],
 'title': 'Group',
 'type': 'object'}
"""

as command

using alchemyjsonschema as command (the command name is also alchemyjsonschema).

help

$ alchemyjsonschema --help
usage: alchemyjsonschema [-h] [--walker {noforeignkey,foreignkey,structural}]
                         [--decision {default,fullset}] [--depth DEPTH]
                         [--out OUT]
                         target

positional arguments:
  target                the module or class to extract schemas from

optional arguments:
  -h, --help            show this help message and exit
  --walker {noforeignkey,foreignkey,structural}
  --decision {default,fullset}
  --depth DEPTH
  --out OUT             output to file

If above two model definitions (User,Group) are existed in alchemyjsonschema.tests.models .

Target is the class position or module position. for example,

class position – alchemyjsonschema.tests.models:User
module position – alchemyjsonschema.tests.models

example

Using StructuralWalker via command line (–walker structural). Of course, NoForeignKeyWalker is noforeignkey, and ForeignKeyWalker is foreignkey.

$ alchemyjsonschema --walker structural alchemyjsonschema.tests.models:Group

{
  "definitions": {
    "Group": {
      "properties": {
        "color": {
          "enum": [
            "red",
            "green",
            "yellow",
            "blue"
          ],
          "maxLength": 6,
          "type": "string"
        },
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "name": {
          "maxLength": 255,
          "type": "string"
        },
        "pk": {
          "description": "primary key",
          "type": "integer"
        },
        "users": {
          "items": {
            "$ref": "#/definitions/User"
          },
          "type": "array"
        }
      },
      "required": [
        "pk"
      ],
      "title": "Group",
      "type": "object"
    },
    "User": {
      "properties": {
        "created_at": {
          "format": "date-time",
          "type": "string"
        },
        "name": {
          "maxLength": 255,
          "type": "string"
        },
        "pk": {
          "description": "primary key",
          "type": "integer"
        }
      },
      "required": [
        "pk"
      ],
      "type": "object"
    }
  }
}

Output is not same when using Walker-class, directly. This is handy output for something like a swagger(OpenAPI 2.0)’s tool.

appendix: what is –decision ?

what is –decision? (TODO: gentle description)

$ alchemyjsonschema --walker structural alchemyjsonschema.tests.models:User | jq . -S > /tmp/default.json
$ alchemyjsonschema --decision useforeignkey --walker structural alchemyjsonschema.tests.models:User | jq . -S > /tmp/useforeignkey.json
$ diff -u /tmp/default.json /tmp/useforeignkey.json

--- /tmp/default.json 2017-01-02 22:49:44.000000000 +0900
+++ /tmp/useforeignkey.json   2017-01-02 22:53:13.000000000 +0900
@@ -1,43 +1,14 @@
 {
   "definitions": {
-    "Group": {
-      "properties": {
-        "color": {
-          "enum": [
-            "red",
-            "green",
-            "yellow",
-            "blue"
-          ],
-          "maxLength": 6,
-          "type": "string"
-        },
-        "created_at": {
-          "format": "date-time",
-          "type": "string"
-        },
-        "name": {
-          "maxLength": 255,
-          "type": "string"
-        },
-        "pk": {
-          "description": "primary key",
-          "type": "integer"
-        }
-      },
-      "required": [
-        "pk"
-      ],
-      "type": "object"
-    },
     "User": {
       "properties": {
         "created_at": {
           "format": "date-time",
           "type": "string"
         },
-        "group": {
-          "$ref": "#/definitions/Group"
+        "group_id": {
+          "relation": "group",
+          "type": "integer"
         },
         "name": {
           "maxLength": 255,

Metadata

Release files for alchemyjsonschema 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for alchemyjsonschema 0.8.0
File	Size	Uploaded
alchemyjsonschema-0.8.0.tar.gz	16.6 kB	Aug 5, 2023	Details

Built distribution (wheel)

Table of built distributions (wheels) for alchemyjsonschema 0.8.0
File	Interpreter	ABI	Platform	Reset
alchemyjsonschema-0.8.0-py2.py3-none-any.whl 17.3 kB Aug 5, 2023	Python 3, Python 2	none	any	Details

Total release size: 33.9 kB

Release files / alchemyjsonschema-0.8.0.tar.gz

Download URL	alchemyjsonschema-0.8.0.tar.gz
Size	16.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`df95f068ed2b69e90b65c9711e6b6ec773037e9f14ec00707f18e7ae5040e360`
BLAKE2b-256 checksum How to use checksums	`ca5007e62ba3583eea27ed9a6b47ef9885be748d282bc125de0fefb7a0c60469`
Upload date	Aug 5, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.10.6`

Release files / alchemyjsonschema-0.8.0-py2.py3-none-any.whl

Download URL	alchemyjsonschema-0.8.0-py2.py3-none-any.whl
Size	17.3 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`56a44a60f93631345b2e8030245c81e7ba7842db7d7e8d2c106210c3b599a0cb`
BLAKE2b-256 checksum How to use checksums	`43c2421bccfceb18e0fc2bfd0a3bf4f1361a5c2ca37b52998221d5ead6253bcb`
Upload date	Aug 5, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.10.6`