Formidable Form JSON Schema specification¶
definitions | ||||
|
Different contexts that helps to render a form | |||
type | object | |||
properties | ||||
|
Help text of the access | |||
type | string | |||
|
ID of the access | |||
type | string | |||
|
Label of the access | |||
type | string | |||
|
How to display the preview, default is FORM. Values are FORM, TABLE | |||
type | string | |||
enum | FORM, TABLE | |||
|
type | object | ||
properties | ||||
|
Errors on fields (key => field; value => list of messages) | |||
type | object | |||
|
Errors on anything except fields (validations…) | |||
type | array | |||
items | type | string | ||
|
allOf | #/definitions/Form | ||
properties | ||||
|
List of fields ordered in the form | |||
type | array | |||
items | #/definitions/Field | |||
|
Describe conditional display of a field, depending on the value of another field. e.g.: “display the field ‘what is you favorite Star Wars character?’ if the boolean field ‘Do you like Star Wars?’ is checked”. |
|||
type | object | |||
properties | ||||
|
Name of the action to do when the condition is true. e.g. “display the field” == display_iff |
|||
type | string | |||
enum | display_iff | |||
|
List of field slugs to show/hide depending on the conditions. | |||
type | array | |||
items | type | string | ||
minItems | 1 | |||
|
A user-provided name for the Condition | |||
type | string | |||
|
List of conditions to test. | |||
type | array | |||
items | #/definitions/ConditionTest | |||
minItems | 1 | |||
|
Condition definition. | |||
type | object | |||
properties | ||||
|
`slug` of the reference field for the comparison. | |||
type | string | |||
|
Comparison operator for the condition. | |||
type | string | |||
enum | eq | |||
|
List of the possible values that would return a “true” condition. | |||
type | array | |||
items | ||||
|
Field in a form | |||
type | object | |||
properties | ||||
|
List of accesses of the field with a level | |||
type | array | |||
items | #/definitions/FieldAccess | |||
|
Default values selected/inputed when the form is newly displayed | |||
type | array | |||
items | type | string | ||
|
Description of the field | |||
type | string | |||
|
ID of the field | |||
type | integer | |||
|
Values available | |||
type | array | |||
items | #/definitions/Item | |||
|
Label of the field | |||
type | string | |||
|
Is the field can have multiple values? | |||
type | boolean | |||
|
Placeholder of the field | |||
type | string | |||
|
Slug of the field (us as uniq identifier of the field on the form) | |||
type | string | |||
|
Type of field (see Field types table) | |||
type | string | |||
enum | title, helpText, fieldset, fieldsetTable, separation, checkbox, checkboxes, dropdown, radios, radiosButtons, text, paragraph, file, date, email, number | |||
|
List of validations of the field | |||
type | array | |||
items | #/definitions/FieldValidation | |||
|
The access is the way to use the field in the context | |||
type | object | |||
properties | ||||
|
Access reference | |||
type | string | |||
|
Level of this access for the field | |||
type | string | |||
enum | REQUIRED, EDITABLE, HIDDEN, READONLY | |||
|
This validation can only be performed on a single field | |||
type | object | |||
properties | ||||
|
Error message if the validation is not verified | |||
type | string | |||
|
Type of validation (see Validation types table) | |||
type | string | |||
enum | EQ, GT, GTE, IS_AGE_ABOVE, IS_AGE_UNDER, IS_DATE_IN_THE_FUTURE, IS_DATE_IN_THE_PAST, LT, LTE, MAXLENGTH, MINLENGTH, NEQ, REGEXP | |||
|
Value of the validation | |||
type | string | |||
|
The central piece of this project | |||
type | object | |||
properties | ||||
|
type | array | ||
items | #/definitions/Condition | |||
|
Description of the form - can be empty | |||
type | string | |||
|
ID of the form | |||
type | integer | |||
|
Title of the form | |||
type | string | |||
|
Object that contains field errors as key with a list of string in value | |||
type | object | |||
properties | ||||
|
Errors on anything except form’s fields | |||
type | array | |||
items | type | string | ||
|
properties | |||
|
Values selected/inputed when the form is in edition mode | |||
type | array | |||
items | type | string | ||
allOf | #/definitions/Field | |||
|
allOf | #/definitions/Form | ||
properties | ||||
|
List of fields ordered in the form | |||
type | array | |||
items | #/definitions/InputField | |||
|
Describe an item in a list | |||
type | object | |||
properties | ||||
|
Description of the item | |||
type | string | |||
|
Label of the item | |||
type | string | |||
|
Value which defined the item | |||
type | string |
Or, in raw JSON:
{
"basePath": "/api",
"definitions": {
"Access": {
"description": "Different contexts that helps to render a form",
"properties": {
"description": {
"description": "Help text of the access",
"type": "string"
},
"id": {
"description": "ID of the access",
"type": "string"
},
"label": {
"description": "Label of the access",
"type": "string"
},
"preview_as": {
"description": "How to display the preview, default is `FORM`. Values are `FORM`, `TABLE`",
"enum": [
"FORM",
"TABLE"
],
"type": "string"
}
},
"required": [
"id",
"label",
"description"
],
"type": "object"
},
"BuilderError": {
"properties": {
"fields": {
"description": "Errors on fields (key => field; value => list of messages)",
"type": "object"
},
"non_field_errors": {
"description": "Errors on anything except fields (validations...)",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"BuilderForm": {
"allOf": [
{
"$ref": "#/definitions/Form"
},
{
"properties": {
"fields": {
"description": "List of fields ordered in the form",
"items": {
"$ref": "#/definitions/Field"
},
"type": "array"
}
}
}
]
},
"Condition": {
"description": "Describe conditional display of a field, depending on the value of another field.\n\ne.g.: \"display the field 'what is you favorite Star Wars character?' if the boolean field 'Do you like Star Wars?' is checked\".\n",
"properties": {
"action": {
"description": "Name of the action to do when the condition is true. e.g. \"display the field\" == ``display_iff``",
"enum": [
"display_iff"
],
"type": "string"
},
"field_ids": {
"description": "List of field slugs to show/hide depending on the conditions.",
"items": {
"type": "string"
},
"minItems": 1,
"type": "array"
},
"name": {
"description": "A user-provided name for the Condition",
"type": "string"
},
"tests": {
"description": "List of conditions to test.",
"items": {
"$ref": "#/definitions/ConditionTest"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"field_ids",
"action",
"tests"
],
"type": "object"
},
"ConditionTest": {
"description": "Condition definition.",
"properties": {
"field_id": {
"description": "\\`slug\\` of the reference field for the comparison.",
"type": "string"
},
"operator": {
"description": "Comparison operator for the condition.",
"enum": [
"eq"
],
"type": "string"
},
"values": {
"description": "List of the possible values that would return a \"true\" condition.",
"items": {},
"type": "array"
}
},
"required": [
"field_id",
"operator",
"values"
],
"type": "object"
},
"Field": {
"description": "Field in a form",
"properties": {
"accesses": {
"description": "List of accesses of the field with a level",
"items": {
"$ref": "#/definitions/FieldAccess"
},
"type": "array"
},
"defaults": {
"description": "Default values selected/inputed when the form is newly displayed",
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"description": "Description of the field",
"type": "string"
},
"id": {
"description": "ID of the field",
"readOnly": true,
"type": "integer"
},
"items": {
"description": "Values available",
"items": {
"$ref": "#/definitions/Item"
},
"type": "array"
},
"label": {
"description": "Label of the field",
"type": "string"
},
"multiple": {
"description": "Is the field can have multiple values?",
"type": "boolean"
},
"placeholder": {
"description": "Placeholder of the field",
"type": "string"
},
"slug": {
"description": "Slug of the field (us as uniq identifier of the field on the form)",
"type": "string"
},
"type_id": {
"description": "Type of field (see Field types table)",
"enum": [
"title",
"helpText",
"fieldset",
"fieldsetTable",
"separation",
"checkbox",
"checkboxes",
"dropdown",
"radios",
"radiosButtons",
"text",
"paragraph",
"file",
"date",
"email",
"number"
],
"type": "string"
},
"validations": {
"description": "List of validations of the field",
"items": {
"$ref": "#/definitions/FieldValidation"
},
"type": "array"
}
},
"required": [
"id",
"slug",
"label",
"type_id",
"description",
"accesses"
],
"type": "object"
},
"FieldAccess": {
"description": "The access is the way to use the field in the context",
"properties": {
"access_id": {
"description": "Access reference",
"type": "string"
},
"level": {
"description": "Level of this access for the field",
"enum": [
"REQUIRED",
"EDITABLE",
"HIDDEN",
"READONLY"
],
"type": "string"
}
},
"required": [
"access_id",
"level"
],
"type": "object"
},
"FieldValidation": {
"description": "This validation can only be performed on a single field",
"properties": {
"message": {
"description": "Error message if the validation is not verified",
"type": "string"
},
"type": {
"description": "Type of validation (see Validation types table)",
"enum": [
"EQ",
"GT",
"GTE",
"IS_AGE_ABOVE",
"IS_AGE_UNDER",
"IS_DATE_IN_THE_FUTURE",
"IS_DATE_IN_THE_PAST",
"LT",
"LTE",
"MAXLENGTH",
"MINLENGTH",
"NEQ",
"REGEXP"
],
"type": "string"
},
"value": {
"description": "Value of the validation",
"type": "string"
}
},
"required": [
"type",
"value"
],
"type": "object"
},
"Form": {
"description": "The central piece of this project",
"properties": {
"conditions": {
"items": {
"$ref": "#/definitions/Condition"
},
"type": "array"
},
"description": {
"description": "Description of the form - can be empty",
"type": "string"
},
"id": {
"description": "ID of the form",
"readOnly": true,
"type": "integer"
},
"label": {
"description": "Title of the form",
"type": "string"
}
},
"required": [
"id",
"label",
"description"
],
"type": "object"
},
"InputError": {
"description": "Object that contains field errors as key with a list of string in value",
"properties": {
"__all__": {
"description": "Errors on anything except form's fields",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"InputField": {
"allOf": [
{
"$ref": "#/definitions/Field"
}
],
"properties": {
"values": {
"description": "Values selected/inputed when the form is in edition mode",
"items": {
"type": "string"
},
"type": "array"
}
}
},
"InputForm": {
"allOf": [
{
"$ref": "#/definitions/Form"
},
{
"properties": {
"fields": {
"description": "List of fields ordered in the form",
"items": {
"$ref": "#/definitions/InputField"
},
"type": "array"
}
}
}
]
},
"Item": {
"description": "Describe an item in a list",
"properties": {
"description": {
"description": "Description of the item",
"type": "string"
},
"label": {
"description": "Label of the item",
"type": "string"
},
"value": {
"description": "Value which defined the item",
"type": "string"
}
},
"required": [
"label",
"value"
],
"type": "object"
}
},
"host": "localhost:8000",
"info": {
"description": "django-formidable is a full django application which allows you to create,\nedit, delete and use forms.\n\n##### Field types\n\nList of known types available:\n\n| Type | Description | HTML Component |\n| ---- | ----------- | -------------- |\n| title | Title | h2 |\n| helpText | Helptext | p |\n| fieldset | Group of fields (iterable) | fieldset |\n| fieldsetTable | Group of fields display as table (iterable) | table |\n| separation | Separator line (design only) | hr |\n| checkbox | Checkbox alone | input type=checkbox |\n| checkboxes | Some checkboxes, all checkable | input type=checkbox, all have the same name |\n| dropdown | Dropdown with values | select |\n| radios | Some radios, only one is selected at once | input type=radio |\n| radiosButtons | Some radios display as toggle button | input type=radio |\n| text | Input for one line text | input type=text |\n| paragraph | Input for multiline text | textarea |\n| file | Field to select a local file to be uploaded | input type=file |\n| date | Input for a date (datepicker with it, lang know by application parameter, validation by momentjs) | input type=date |\n| email | Input for an email (validation by regexp) | input |\n| number | Input for a number | input |\n\n##### Validations types\n\nList of validations available by types:\n\n| Field | Validation type |\n| ----- | ----------- |\n| text | MINLENGTH, MAXLENGTH, REGEXP |\n| paragraph | MINLENGTH, MAXLENGTH, REGEXP |\n| date | GT, GTE, LT, LTE, EQ, NEQ, IS_AGE_ABOVE (>=), IS_AGE_UNDER (<), IS_DATE_IN_THE_PAST (< today), IS_DATE_IN_THE_FUTURE (< today) |\n| number | GT, GTE, LT, LTE, EQ, NEQ |\n",
"title": "Formidable API",
"version": "1.0.0"
},
"paths": {
"/builder/accesses/": {
"get": {
"description": "List of accesses available.",
"responses": {
"200": {
"description": "A list of accesses",
"schema": {
"items": {
"$ref": "#/definitions/Access"
},
"type": "array"
}
}
},
"summary": "Get accesses"
}
},
"/builder/forms/": {
"post": {
"description": "Create Form Description",
"parameters": [
{
"in": "body",
"name": "form",
"required": true,
"schema": {
"$ref": "#/definitions/BuilderForm"
}
}
],
"responses": {
"201": {
"description": "Newly created form",
"schema": {
"$ref": "#/definitions/BuilderForm"
}
},
"400": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/BuilderError"
}
}
},
"summary": "Create a new form"
}
},
"/builder/forms/{id}/": {
"get": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "Form",
"schema": {
"$ref": "#/definitions/BuilderForm"
}
}
},
"summary": "Retrieve a Form"
},
"put": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"type": "integer"
},
{
"in": "body",
"name": "form",
"required": true,
"schema": {
"$ref": "#/definitions/BuilderForm"
}
}
],
"responses": {
"200": {
"description": "Form",
"schema": {
"$ref": "#/definitions/BuilderForm"
}
},
"400": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/BuilderError"
}
}
},
"summary": "Update a Form"
}
},
"/forms/{id}/": {
"get": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "A form",
"schema": {
"$ref": "#/definitions/BuilderForm"
}
}
},
"summary": "Get a contextualized form"
}
},
"/forms/{id}/validate/": {
"post": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"type": "integer"
}
],
"responses": {
"204": {
"description": "Validation OK"
},
"400": {
"description": "Validation KO",
"schema": {
"$ref": "#/definitions/InputError"
}
}
},
"summary": "Validate user-data against a form schema."
}
}
},
"produces": [
"application/json"
],
"schemes": [
"http"
],
"swagger": "2.0"
}