Skip to content
This repository has been archived by the owner on Sep 28, 2022. It is now read-only.

Commit

Permalink
reflecting changes made to json schemas in the documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@jstoiko
jstoiko committed Aug 18, 2015
1 parent 8e04505 commit 2cb1f2c
Show file tree
Hide file tree
Showing 3 changed files with 61 additions and 51 deletions.
3 changes: 3 additions & 0 deletions docs/source/changelog.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,11 @@ Changelog

* :release:`0.4.0 <2015-08-x>`
* :support:`-` Ramses now parses RAML using spotify/ramlfications
* :support:`-` Added support for json-schema draft-04
* :feature:`-` Renamed authentication setting `ramses.auth` to `auth`
* :feature:`-` Added 'field' name and 'request' object to processors' arguments
* :feature:`-` Prefixed all Ramses-specific schema properties by an underscore
* :feature:`-` Renamed schema's 'args' property to '_db_settings'
* :bug:`- major` Fixed processors not applied on fields of type 'list' and type 'dict'
* :bug:`- major` Fixed a limitation preventing collection names to use nouns that do not have plural forms

Expand Down
86 changes: 47 additions & 39 deletions docs/source/fields.rst
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Field Types
===========
Fields
======

This is a list of all available types:

Expand Down Expand Up @@ -30,13 +30,16 @@ This is a list of all available types:
Required Fields
---------------

You can set a field as required by setting the ``required`` property.
You can set a field as required by setting the ``required`` property under ``_db_settings``.

.. code-block:: json
"field": {
"required": true,
"password": {
(...)
"_db_settings": {
(...)
"required": true
}
}
Expand All @@ -49,34 +52,35 @@ You can use an ``id_field`` in lieu of primary key.
"id": {
(...)
"type": "id_field",
"args": {
"_db_settings": {
(...)
"primary_key": true
}
}
You can alternatively elect a field to be the primary key of your model by setting its ``primary_key`` property under ``args``. For example, if you decide to use ``username`` as the primary key of your `User` model. This will enable resources to refer to that field in their url, e.g. ``/api/users/john``
You can alternatively elect a field to be the primary key of your model by setting its ``primary_key`` property under ``_db_settings``. For example, if you decide to use ``username`` as the primary key of your `User` model. This will enable resources to refer to that field in their url, e.g. ``/api/users/john``

.. code-block:: json
"username": {
(...)
"type": "string",
"args": {
"_db_settings": {
(...)
"primary_key": true
}
}
Constraints
-----------

You can set a minimum and/or maximum length of your field by setting the ``min_length`` / ``max_length`` properties under ``args``. You can also add a unique constraint on a field by setting the ``unique`` property.
You can set a minimum and/or maximum length of your field by setting the ``min_length`` / ``max_length`` properties under ``_db_settings``. You can also add a unique constraint on a field by setting the ``unique`` property.

.. code-block:: json
"field": {
(...)
"args": {
"_db_settings": {
(...)
"unique": true,
"min_length": 5,
"max_length": 50
Expand All @@ -88,13 +92,14 @@ You can set a minimum and/or maximum length of your field by setting the ``min_l
Field Processors
----------------

Field processors are custom functions that are called upon validation of a field. You can write those functions inside your ``__init__.py``. You can reference processors in the ``before_validation`` and ``after_validation`` properties under ``args``. The `before_` and `after_` prefixes refer to when those processors are executed, either before or after database validation. You can define more than one processor in each of those arguments in a comma-separated list. If multiple processors are listed, they are executed in the order in which they are listed.
Field processors are custom functions that are called upon validation of a field. You can write those functions inside your ``__init__.py``. You can reference processors in the ``before_validation`` and ``after_validation`` properties under ``_db_settings``. The `before_` and `after_` prefixes refer to when those processors are executed, either before or after database validation. You can define more than one processor in each of those arguments in a comma-separated list. If multiple processors are listed, they are executed in the order in which they are listed.

.. code-block:: json
"password": {
(...)
"args": {
"_db_settings": {
(...)
"before_validation": ["validate_password_format", "crypt"],
"after_validation": ["email_password_changed"]
}
Expand All @@ -106,8 +111,8 @@ For 'relationship' fields, you can also add processors to your backref field by
"parents": {
(...)
"type": "relationship",
"args": {
"_db_settings": {
"type": "relationship",
"document": "Parent",
"backref_name": "child",
"backref_before_validation": ["verify_filiation"],
Expand All @@ -121,16 +126,16 @@ To learn more about writing custom processors, see the :ref:`Writing Processors
Relationship Fields
-------------------

You can define the name of your relation model by setting the ``document`` property under ``args`` in a relationship field. You can also set the ``backref_name`` which will automatically add a field of that name to the relation model.
You can define the name of your relation model by setting the ``document`` property under ``_db_settings`` in a relationship field. You can also set the ``backref_name`` which will automatically add a field of that name to the relation model.

The example below will create a one-to-one relationship.

.. code-block:: json
"capital": {
(...)
"type": "relationship",
"args": {
"_db_settings": {
"type": "relationship",
"document": "City",
"backref_name": "country",
"uselist": false
Expand All @@ -143,8 +148,8 @@ The example below will create a one-to-many relationship.
"cities": {
(...)
"type": "relationship",
"args": {
"_db_settings": {
"type": "relationship",
"document": "City",
"backref_name": "country"
}
Expand All @@ -156,16 +161,16 @@ The example below will create both relationships above.
"capital": {
(...)
"type": "relationship",
"args": {
"_db_settings": {
"type": "relationship",
"document": "City",
"uselist": false
}
},
"cities": {
(...)
"type": "relationship",
"args": {
"_db_settings": {
"type": "relationship",
"document": "City",
"backref_name": "country"
}
Expand All @@ -177,13 +182,14 @@ Note that when using SQLA, you must add a ``foreign_keys`` property to your rela
Default Value
-------------

You can set a default value for you field by setting the ``default`` property under ``args``.
You can set a default value for you field by setting the ``default`` property under ``_db_settings``.

.. code-block:: json
"field": {
(...)
"args": {
"_db_settings": {
(...)
"default": "default value"
}
},
Expand All @@ -194,7 +200,8 @@ The ``default`` value can also be set to a Python callable, e.g.
"datetime_field": {
(...)
"args": {
"_db_settings": {
(...)
"default": "{{datetime.datetime.utcnow}}"
}
},
Expand All @@ -203,13 +210,14 @@ The ``default`` value can also be set to a Python callable, e.g.
Update Default Value
--------------------

You can set an update default value for your field by setting the ``onupdate`` property under ``args``. This is particularly useful to update 'datetime' fields on every updates, e.g.
You can set an update default value for your field by setting the ``onupdate`` property under ``_db_settings``. This is particularly useful to update 'datetime' fields on every updates, e.g.

.. code-block:: json
"datetime_field": {
(...)
"args": {
"_db_settings": {
(...)
"onupdate": "{{datetime.datetime.utcnow}}"
}
},
Expand All @@ -218,32 +226,32 @@ You can set an update default value for your field by setting the ``onupdate`` p
List Fields
-----------

You can list the accepted values of any ``list`` or ``choice`` fields by setting the ``choices`` property under ``args``.
You can list the accepted values of any ``list`` or ``choice`` fields by setting the ``choices`` property under ``_db_settings``.

.. code-block:: json
"field": {
(...)
"type": "choice",
"args": {
"_db_settings": {
"type": "choice",
"choices": ["choice1", "choice2", "choice3"],
"default": "choice1"
}
}
You can also provide the list/choice items' ``type``.
You can also provide the list/choice items' ``item_type``.

.. code-block:: json
"field": {
(...)
"type": "list",
"args": {
"_db_settings": {
"type": "list",
"item_type": "string"
}
}
Other ``args``
--------------
Other ``_db_settings``
----------------------

Note that you can pass any engine-specific arguments to your fields by defining such arguments in ``args``.
Note that you can pass any engine-specific arguments to your fields by defining such arguments in ``_db_settings``.
23 changes: 11 additions & 12 deletions docs/source/schemas.rst
View file
Original file line number Diff line number Diff line change
@@ -1,32 +1,33 @@
Defining Schemas
================

JSON Schema Draft 3
-------------------
JSON Schema
-----------

Ramses supports JSON Schema Draft 3. You can read the full specifications `here <http://tools.ietf.org/html/draft-zyp-json-schema-03>`_.
Ramses supports JSON Schema Draft 3 and Draft 4. You can read the official `JSON Schema documentation here <http://json-schema.org/documentation.html>`_.

.. code-block:: json
{
"type": "object",
"title": "Item schema",
"$schema": "http://json-schema.org/draft-03/schema",
"required": true,
"$schema": "http://json-schema.org/draft-04/schema",
(...)
}
All Ramses-specific properties are prefixed with an underscore.

Showing Fields
--------------

If you've enabled authentication, you can list which fields to return to authenticated users in ``auth_fields`` and to non-authenticated users in ``public_fields``.
If you've enabled authentication, you can list which fields to return to authenticated users in ``_auth_fields`` and to non-authenticated users in ``_public_fields``.

.. code-block:: json
{
(...)
"auth_fields": ["id", "name", "description"],
"public_fields": ["name"],
"_auth_fields": ["id", "name", "description"],
"_public_fields": ["name"],
(...)
}
Expand All @@ -46,14 +47,12 @@ If you use ``Relationship`` fields in your schemas, you can list those fields in
Custom "user" Model
-------------------

When authentication is enabled, a "user" model will be created automatically with 4 fields: "username", "email", "groups" and "password". You can extend that model by defining your own "user" schema and set ``auth_model`` to ``true`` on that schema.
When authentication is enabled, a default "user" model will be created automatically with 4 fields: "username", "email", "groups" and "password". You can extend this default model by defining your own "user" schema and by setting ``_auth_model`` to ``true`` on that schema. You can add any additional fields in addition to those 4 default fields.

.. code-block:: json
{
(...)
"auth_model": true,
"_auth_model": true,
(...)
}
You can define any additional fields you'd like but you'll need to preserve the 4 required fields above.

0 comments on commit 2cb1f2c

Please sign in to comment.