Schemas

Madame doesn’t use any python ORM to describe data, it uses JSON schemas to describe each collections. The idea was to separate schemas from code to enable modifications during runtime. Schemas are considered as part of data, except the fact that they are not saved in the database.

Madame uses Validictory to validate data with the schemas provided.

There are two ways to add schemas:

  • Decribe them in a file
  • Add them with a POST method on the root url or your API during runtime.

The schema file

Creating a schema file allows you to set schemas available when your start the application.

These schemas can be disabled with a DELETE method during runtime if you set the configuration value ROOT_DELETE to True in the configuration file. See Configuration Handling section for more details.

To tell Madame about your schema file, add this line in your configuration file :

SCHEMA_FILE = <PATH>

Replace <PATH> with the path of your schema file.

The schema wrapper

Schemas are encapsulated in a wrapper that contains additional informations about your collections.

Here is the minimal content that needs to be in your schema file :

{
  <COLLECTION_URL> : {
      "title" : <COLLECTION_TITLE>,
      "description" : <COLLECTION_DESCRIPTION>,
      "schema" : {} # the validictory schema
  },

  <COLLECTION_URL> : ...
}
<COLLECTION_URL>

sets the url of your collection

example : for “members” -> http://localhost:5000/members/

<COLLECTION_TITLE> used in the response to describe the given collection
<COLLECTION_DESCRIPTION> used in the response to describe the given collection

To get more informations about how to write schema, see the Validictory documentation, it is very simple and doesn’t need to be documented here.

Adding schemas with POST

If the configuration value ROOT_POST is enabled, you can add schemas with a POST method. Here is an example with Requests :

>>> import request, json

>>> schema = { ... }
>>> headers = {'content-type': 'application/json'}
>>> r = requests.post('http://localhost:5000/',
... data=json.dumps(schema), headers=headers)
>>> print r.status_code
201

Schema example

In the schema file :

{
  # Pet collection
  # url : /pets/
  "pets" : {
      "title" : "Pets",
      "description" : "My pets",
      "schema" : {
          "type" : "object",
          "properties" : {
              "name" : {
                  "type"  : "string",
                  "minLength" : 1,
                  "maxLength" : 15,
                  "required"  : true
              },
              "age" : {
                  "type"  : "number"
              }
          }
      }
  },

  # Book collection
  # url : /books/
  "books" : {
      "title" : "Books"
      "description" : "My book list",
      "schema" : {
          "type" : "object",
          "properties" : {
              "title"     : {"type" : "string", "required" : true},
              "author"    : {"type" : "string", "required" : true}
          }
      }
  }
}

With the POST method :

>>> import request, json

>>> schema = {
... "type" : "object",
... "properties" : {
...     "title"     : {"type" : "string", "required" : true},
...     "author"    : {"type" : "string", "required" : true}
... }}
>>> headers = {'content-type': 'application/json'}
>>> r = requests.post('http://localhost:5000/',
... data=json.dumps(schema), headers=headers)
>>> print r.status_code
201

Madame is an easy-to-use RESTful API for Python and MongoDB. You are currently looking at the documentation of the development version.

Donate

If you love Madame, consider supporting the author on Gittip:

Feedback

Feedback is greatly appreciated. If you have any questions, comments, random praise, or anonymous threats, shoot me an email.

Useful Links

Table Of Contents

Related Topics

This Page

Fork me on GitHub