json-schema-form / angular-schema-form

Generate forms from a JSON schema, with AngularJS!

Angular Schema Form

Generate forms from JSON schemas using AngularJS!

Why not many changes lately?

Much of the new development is being done in Assimilate, a standardised validator for JSON Schema to help ensure changing validators is never as painful as escaping tv4 is, as well as a new core library to allow for a more predictable upgrade from AngularJS to Angular.

The Blog / The Web Site / The Twitter / The Movie

medium.com/@SchemaFormIO / website / @SchemaFormIO / Movie

If you use ASF in your project/company please let us know! We'd love to feature you on the site.

There has been some recent developments in this project that you might want to read about.

Demo Time!

Try out the example page. Try editing the schema or form definition and see what comes out!

Hint: By pressing the 'Save to gist' button (top left), you can save your example into a shareable link.

Documentation

You can find all documentation here, it covers all the different field types and their options.

It also covers how to extend angular schema form with your own field types.

Before filing an issue, please read our issue support instructions or you may be ignored.

What is it?

Schema Form is a set of AngularJS directives (and a couple of services). It can do two things to make life easier:

1. Create a form directly from a JSON schema.
2. Validate form fields against that same JSON schema.

Schema Form uses convention over configuration, so it comes packaged with some sensible defaults. But you can always customize it by changing the order and types of form fields.

JSON Form

Schema Form is inspired by the nice JSON Form library and aims to be roughly compatible with it, especially its form definition. So what sets Schema Form apart from JSON Form?

1. Schema Form integrates deeply with AngularJS and uses AngularJS conventions to handle forms.
2. Schema Form uses tv4 for validation, making it compatible with version 4 of the JSON schema standard.
3. By default, Schema Form generates Bootstrap 3-friendly HTML.

Migration Guide

If you already use the library factories in an app or an add-on or plan to upgrade versions, please read the migration guide for any items that may need consideration.

Basic Usage

First, expose your schema, form, and model to the $scope.

angular.module('myModule', ['schemaForm'])
       .controller('FormController', function($scope) {
  $scope.schema = {
    type: "object",
    properties: {
      name: { type: "string", minLength: 2, title: "Name", description: "Name or alias" },
      title: {
        type: "string",
        enum: ['dr','jr','sir','mrs','mr','NaN','dj']
      }
    }
  };

  $scope.form = [
    "*",
    {
      type: "submit",
      title: "Save"
    }
  ];

  $scope.model = {};
});

Then load them into Schema Form using the sfSchema, sfForm, and sfModel directives.

<div ng-controller="FormController">
    <form sf-schema="schema" sf-form="form" sf-model="model"></form>
</div>

Installation

NPM

npm i angular-schema-form@latest

For the latest pre-release (alpha)

npm i angular-schema-form@pre-release

Bower

It's simplest to install Schema Form using Bower. If you use the bootstrap decorator use the one from the angular-schema-form-bootstrap repo

bower install angular-schema-form angular-schema-form-bootstrap
bower install angular-schema-form angular-schema-form-bootstrap

This will install the latest release and basic dependencies. See dependencies section below.

You can also load the files via cdnjs.com.

Manual

You can also just download the contents of the dist/ folder and add dependencies manually.

Dependencies

Schema form has a lot of dependencies, most of which are optional. Schema Form depends on:

1. AngularJS version 1.3.x is recommended. Version 1.2.x has some limitation. See known limitations.
2. angular-sanitize
3. tv4
4. bootstrap 3

If you install via bower you get all of the above except bootstrap since we don't want to push a certain version or flavor on you. Also make sure you got the angular version you actually want.

Additional dependencies

1. If you'd like to use drag-and-drop reordering of arrays, you'll also need ui-sortable and its jQueryUI dependencies. See the ui-sortable documentation for details about which parts of jQueryUI are needed. You can safely ignore these if you don't need reordering.
2. Schema Form provides tabbed arrays through the form type tabarray. Tab arrays default to tabs on the left side. For these to work, you'll need to include the CSS from bootstrap-vertical-tabs. However, you won't need Bootstrap Vertical Tabs for horizontal tabs (the tabType: "top" option).

The minified files include templates - no need to load additional HTML files.

Script Loading

Schema form is split into two main files, dist/schema-form.min.js and dist/bootstrap-decorator.min.js and they need be loaded in that order. AngularJS, tv4 and objectpath also needs to be loaded before Schema Form.

<script type="text/javascript" src="bower_components/angular/angular.min.js"></script>
<script type="text/javascript" src="bower_components/angular-sanitize/angular-sanitize.min.js"></script>
<script type="text/javascript" src="bower_components/tv4/tv4.js"></script>
<script type="text/javascript" src="bower_components/objectpath/lib/ObjectPath.js"></script>
<script type="text/javascript" src="bower_components/angular-schema-form/dist/schema-form.min.js"></script>
<script type="text/javascript" src="bower_components/angular-schema-form/dist/bootstrap-decorator.min.js"></script>

Module loading

Don't forget to load the schemaForm module or nothing will happen.

angular.module('myModule', ['schemaForm']);

Add-ons

There are several add-ons available, for a full list see the web page. Your can also create your own add-ons!

Contributing

Contributions are welcome! Please see Contributing.md for more info.

Building

The new Webpack compilation has made it easier to manage files and code and run build scripts, but it is still not easy enough for users unfamiliar with it... yet.

NOTE in order to build simultaneously with json-schema-form-core you must have it cloned as a sibling directory to this one OR npm install the version you wish to build with.

Webpack now generates a header to indicate version and date of build. Do not create PR with the DIST folder.

Branch Status & New Add-On

This branch will be the next version of Angular Schema Form, currently please use the examples/example.html file as the best example to get the framework working.

The example uses angular-schema-form.js and angular-schema-form-bootstrap.js for the version of the code it executes, if you want your page to behave the same you obviously need the same version!

Add-on

To see how to make an add-on work I have now included the calculate add-on file within the examples/add-on directory.

Tests

Unit tests are run with karma and written using mocha, chai and sinon

To run the tests:

1. Install all dependencies via NPM.
2. Install dev dependencies with bower.
3. Install the Karma CLI.
4. Run the tests using npm test.

$ npm install
$ bower install
$ npm test

angular-schema-form's Issues

Mismatched list tags in array template

https://github.com/Textalk/angular-schema-form/blob/21f6d3ab64435b032456dfe19e03f96b29366320/src/directives/decorators/bootstrap/array.html#L3-L12

Not sure which is desired, but my guess is <ol> since the array ordering is relevant. But I can see a case being made for either.

postProcess Examples

Hiya,

I was wondering if you could provide me some more examples with the postProcess function.
For example:
I used "*" in the form. However, now I want to hide some properties.
schemaFormProvider.postProcess(function(form){
//what do I do with form here
return form;
})

Other than reverse() what are some 1 line examples that I could do in the postProcess?

Thanks!

AMD support

Provide an amd loader option, so all the dependencies are loaded without polluting the global namespace.

Help with select type

$scope.schema = {
type: "object",
properties: {
Test: {
type: "select",
title: "Test 2",
titleMap: [
{ value: "yes", name: "Yes I do" },
{ value: "no", name: "Hell no" }
],
},
}
};

this is just not appearing in my form. help?

Default value not populating checkboxes

Repro steps:

• Visit the demo
• Enter [*] for the form and the following schema:

{
    "type": "object",
    "properties": {
        "flavors": {
            "title": "Flavors",
            "type": "array",
            "items": {
                "enum": [
                    "Chocolate",
                    "Vanilla"
                ]
            },
            "default": ["Chocolate"]
        }
    }
}

Observe that the "Chocolate" checkbox is not checked.

I believe this is because after ng-init="checkboxValues = {}", checkboxValues is never being set with the default passed in via the schema.

only validation & server side validation integration

Hi!
is it possible to :

• just validate a form without generate it?
• integrate (visualize) server-side validation errors to rendered fields?

File upload field?

How complicated would it be to create a File field support? I'd be happy for a few pointers since I'm going to need this functionality in my project.

sf-decorator name clash: both an attribute read by sf-schema and a directive

The attribute name has to change. "sf-decorator-name" maybe?

Bug: hyphens in key names break forms inside arrays

This is actually an issue with writing angular references in dot notation (see this SO question).

To see the bug in action, open up the example page and use:

Form

[
  "*"
]

Schema

{
  "type": "object",
  "title": "Names",
  "properties": {
    "buggy-names": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "title": "Name",
            "type": "string"
          }
        }
      }
    }
  }
}

Changing buggy-names to names fixes it.

Failed to execute 'createElement' on 'Document

Hello,
First, thank you for this fantastic work ... looks great !
I tried the example "Basic Usage" but i got an error :
Failed to execute 'createElement' on 'Document': The tag name provided ('') is not a valid name.
I missed something ?
Philippe

Array of simple strings?

Is this possible? It seems like something the schema should support, ie:

"schema" : {
    "type" : "object",
    "properties" : {
        "_id" : {
            "type" : "string",
            "title" : "Identifier"
        },
        "test" : {
            "type" : "array",
            "title" : "Test items",
            "maxItems" : 5,
            "minItems" : 1,
            "items" : {
                "type" : "string",
                "title" : "An item"
            }
        },
 ....

Currently this property definition is ignored (no error).

Thanks, Alfie.

Problem with titleMap and select

Hello,

form :
 [
    {
      "key": "choice",
      "type": "select",
      "titleMap": {
        "one": "One",
        "two": "More..."
      }
    }
  ]

schema :

{
    "type": "object",
    "properties": {
      "choice": {
        "type": "string"
      }
    }
}

is not working. Dropdown is empty.
but if you change "select" type to "radios" or "radiobuttons", it works fine !
I think the problem is with titleMap, if you use an "enum" in the schema then "select" works fine.

Thank you !
Philippe

Default titles from properties is broken in angular 1.2

One character long.

call function to get enum values

Hello,
I would like to call external functions in schemas to get enum values.
Something like that :

$scope.schema = {
    type: "object",
    properties: {
      name: { type: "string", minLength: 2, title: "Name", description: "Name or alias" },
      title: {
        type: "string",
        enum: "getTitlesValues(...,...)"
      }
    }
  };

getTitlesValues = function(data, ...) {
    if(data.xxx == "YYY")
         return ["a", "b", ...]
}

OK, it's easy if you build the schema with javascript
In my case, schemas are stored in DB, and the return values from the external function could change ... if it depend of data entered by the user.
Any idea ?

edit : I said schema ? OK, same question, but the function would be defined in the form.

Thank you !
Philippe

The use of Javascript Reserved Keywords as Property Names

First of all, great job on the module! I am one of those poor souls who has to make his single page app work in IE8. While doing that, I got the "Expected Identifier" errors in console. Results from google search suggested Javascript reserved keywords being used as property names as the possible cause. The first of these errors was pointing to "e.default", and sure enough, after changing it to "e['default']", the error was gone. There were a few more errors pointing to places where ".enum" was used. Thanks in advance for looking into this.

No tag found that was able to satisfy 0.6.0

I'm trying to get bower to install a specific version of angular-schema-form, but it's failing with the following error:

> bower install angular-schema-form#0.6.0
  bower not-cached    git://github.com/Textalk/angular-schema-form.git#0.6.0
  bower resolve       git://github.com/Textalk/angular-schema-form.git#0.6.0
  bower ENORESTARGET  No tag found that was able to satisfy 0.6.0

I believe that bower expects releases to be tagged (in github) with the version number, as well as having a version specified in the bower.json file?

Could you please tag the 0.6.0 release?

Support array of objects?

I'm building a little invoicing app. angular-schema-form seems almost perfect fit for it. There's a little thing I haven't managed to resolve nicely yet, though.

In my case I need to allow the user to create an arbitrary amount of job type, cost pairs (field for both). The problem is how to deal with the schema.

Maybe something like this would be nice in schema definition?

services: {
    type: 'array',
    title: 'Services',
    items: {
        type: 'object',
        properties: {
            type: {
                type: 'string',
                title: 'Type'
            },
            cost: {
              type: 'string',
              title: 'Cost'
            }
        }
    }
}

This would generate controls to create/remove objects within an array and necessary controls as per definition.

Of course if this feels too specific for your library perhaps we can figure out some alternative solution.

Maybe in my case even some type of table control (a plugin) would work instead of a bunch of fields.

Deleting last object in TabArray leaves no tab selected

To reproduce using TabArray sample:

• Add some tabs
• Select last tab
• Hit Delete

Form area for tabs is now blank.

When any tab but the last tab is deleted, the tab immediately after is selected. I think when the last tab is deleted, the previous tab should be selected.

Submit and Cancel buttons

I want to achieve this feature:

Submit and Cancel buttons

• should be on the same vertical line
• should not be in a button group
• should be able to align buttons on the left or right
• should be able to control spacing between buttons

Support Promise of schema

This seemed angu-natural but isn't actually working:

$scope.schema = $http.get( 'schema.json' );

What about supporting such a use case?
$scope.form could be set the same way.

What works with 0.7.3 is:

$http.get( 'schema.json' ).success( function( schema ) { $scope.schema = schema; } );

Adding own values to a Select

Hey everybody I am using the following Schema and Form :

$scope.schema = {
"type": "object",
"properties": {
"surname": { "type": "string" },
"firstname": { "type": "string" }
}
}
;
$scope.form = [
"firstname",
{
key: "surname",
type: "select",
titleMap: {
"yes": "Yes I do",
"no": "Hell no"
}
}
];

The result is, that the appearing selectboxes have "Yes I do" and "Hell no" , but the values of those options are 0/1.
Did I made somethin wrong ?

Possible to have titleMap for enums in schema ?

Hello,
hum not clear ?
I would have value/label pairs for enums in schemas.

PS: great work with arrays ... love it !

Validate required array field

This is possibly related to issue #27 .

If you have an array of strings, the required flag is not validated.

The following will not be $invalid when the array is empty.

{
    "type": "object",
    "required": ["editors_used"],
    "properties": {
        "editors_used": {
            "type": "array",
            "title": "What editors do you use?",
            "minItems": 1,
            "items": {
                "type": "string",
                "enum": [
                    "vim", "emacs", "sublime", "kate"
                ]
            },
            "additionalItems": false
        }
    }
}

override input templates

I (think I) need to override the individual (html) field definitions. I want to render my form horizontally (class=form-horizontal) but I understand this requires the input control to be wrapped in a div with a specific grid sizing class (e.g. col-md-8)

What options are there (besides forking :) to override the fields templates?

Is there any plans for type array?

I really love what the original json-form do with the array type, so maybe I could work on that for bringing a basic implementation for array type and If I have time tabarray also.

The "V" green icon is bad positionned if the field in the form has no title

Hello,
Little issue, not big stuff.
Thank you,
Philippe

validationMessage is only visible if a description is set

Several fields have a ng-show="form.description" on the help block that also displays validation messages, this means that validation messages are suppressed if no description is present. As reported by @ollivierj in #15.

Tabs and Routes

The current implementation of tabs is not compatible with Angularjs. If the application uses ng-view and routes, selecting a tab will not work. It will expect to follow the href in the tab to the appropriate route. That is why projects such as UI-Bootstrap were created. Many of the standard bootstrap javascript components are not compatible with angularjs out of the box.

How can I reference the index of the current array item in a condition

Consider a slightly modified "Array" example from the demo page. The only change is an additional boolean field on the array called show.

I want to show a certain section of the array only if comments[?].show evaluates true.

How can I reference the current item of the array in the condition of the section? comments[$index].show or comments[arrayIndex].show did not work for me.

Form:

[
  {
    "type": "help",
    "helpvalue": "<h4>Array Example</h4><p>Try adding a couple of forms, reorder by drag'n'drop.</p>"
  },
  {
    "key": "comments",
    "items": [
      "comments[].show",
      { "type": "section",
        "condition": "model.comments[???].show",
        "items": [
           "comments[].name",
           "comments[].email"
         ]
      },
      {
        "key": "comments[].comment",
        "type": "textarea"
      }
    ]
  },
  {
    "type": "submit",
    "title": "OK"
  }
]

Schema:

{
  "type": "object",
  "title": "Comment",
  "properties": {
    "comments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "title": "Name",
            "type": "string"
          },
          "show": {
            "title": "Show",
            "type": "boolean",
            "default": false
          },
          "email": {
            "title": "Email",
            "type": "string",
            "pattern": "^\\S+@\\S+$",
            "description": "Email will be used for evil."
          },
          "comment": {
            "title": "Comment",
            "type": "string",
            "maxLength": 20,
            "validationMessage": "Don't be greedy!"
          }
        },
        "required": [
          "name",
          "email",
          "comment"
        ]
      }
    }
  }
}

Feature Request: apply "readonly" to entire form

Hi there. I have a use case where I need to toggle "readonly" on an entire form, rather than just a few elements. Perhaps we can look for an optional sf-readonly attribute on the form level?

Perhaps this could be added with #61.

Does this support $ref?

Hiya,

I have a schema with
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "title",
"type": "object",
"item": {
"type": "object",
"properties": {
"attribute": {
"$ref": "#/definitions/schema2"
}
},
"required": [
"attribute_info"
]
}
....
something like that.

I kept the form simple with the "*" and a submit button. However the form doesn't render properly where the $ref is.

am I doing something wrong?

Tab-array - välj den nyskapade tabben

Question: can a boolean be rendered with two radio button ?

I want the model to be a boolean, but the widget a radio button, with custom labels for each choice,
is that possible ?

Awesome project btw !

Imporve main doc, load module

Plase, add to the readme to load 'schemaForm' befor using angular-schema-form.

Validation on submit

I have a question regarding the validation process.
I tried to dig through the code, but I'm not sure if I got it right. I'm also pretty new to angular.

In my examples it seems like, I can submit the form even that there are validation issues.
Is there a full validation before the form gets submitted?
I think that would be a good improvement if not.

Also, can I call a function, that goes through the schema and validates the fields and updates the valid state of the form fields?

date support

What are the current plans for supporting date (and time) entry? I've noticed there's a "feature/datepicker" branch - is this still being managed? It seems to lag a bit behind master.

I might consider working on this myself. If so, would the feature/datepicker branch be a good start, or should I start from scratch?

Question to createManualDirective

I am a bit confused about the createManualDirective function.

1. Why is it completely separated from createDirective? For example the scope function showTitle and error messaging are not available then.
2. Is it a bug, that the template of the directive is hardcoded and the templateUrl variable is not used?

Creating form dynamically with different option

Can we have an option where in we can create a form and schema directly with various option ?
ex.
http://selmanh.github.io/angularjs-form-builder/#/forms/create this plugin allows to create form

Form Decorator not inherited in sub sections

When I specify a custom decorator for my form like

<form sf-schema="schema"
      sf-form="form"
      sf-model="data"
      sf-decorator="my-horizontal-form-decorator"
      class="form-horizontal"
      >
</form>

to use other templates than the templates from the default decorator, on top level everything works fine.
But inside sections this specified decorator doesn't seem to be inherited and the default decorator is used.

Checkboxes for an array don't seem to have two-way binding

If you update the variable on the model that the checkboxes are bound to, they don't check/uncheck. Is this the way it's supposed to work?

I'm trying to load an existing object so that you can edit the current properties. The selects/inputs all work fine, but checkboxes aren't coming through as checked.

Validation fails on non-required empty field

When entering something and removing it again, a field is marked as invalid even though it is not required.

Reproduce:

Go to http://textalk.github.io/angular-schema-form/examples/bootstrap-example.html
Enter "a" in comment field.
Remove the "a".
...the comment field gets red with the note "Don't be greedy", probably since it's not a string anymore.

readonly doesn't work for arrays

Include non minified code in distribution, to help debugging

It would be nice if the distribution included ./dist/schema-form.js (non minified) in addition to schema-form.min.js.

This would help with debugging, I am having an error in the minified code and this would help me debug it.

Thanks

Nice project btw !

data validation callback?

In one of your examples, a pattern property is used in the schema object. I was wondering if there's any other way to validate your data, perhaps by using a callback function.
If any such feature is not currently present, could you please add it?

Angular input validations

Should angular-schema-form use the built-in angular validations on the input directive? (eg. ng-min-length or ng-pattern). So far as I can tell it's not setting them (except for required). I realise that tv4 is used for validation against the schema, but does this mean that the built-in angular validations are unnecessary? Or is this a useful feature that could be added?

Required doesn't work on "root" object in schema

ie this doesn't work:

{
  "type": "object",
  "properties": { "foo": { "type": "string"} },
  "required": ['foo']  
}

But this does:

{
  "type": "object",
  "properties": {
   "wrapped": {
      "type": "object",
      "properties": { "foo": { "type": "string"} },
      "required": ['foo']  
    }
}

Regression: maintain enum order for select options

A little background for reminder:

In #12, we implemented this change to the select.html template:

-          ng-options="val as name for (val,name) in form.titleMap">
+          ng-options="val as form.titleMap[val] for val in form.schema.enum">

This was later reverted after the discussion in #23 with f119fb1#diff-b7fb23ab1fda485328f4ece15a745a38R10. The new internal titleMap list should have the correct sort order so I dug a little deeper.

I believe the issue is here: f119fb1#diff-7322ca889abbb7d0f0e6de922b7e4838R59. canonicalTitleMap is iterating over schema.enumNames when it should be iterating over enum. Otherwise the order can be determined by enumNames (an object, without a guaranteed order) rather than the enum list itself.

You can reproduce the issue by visiting the Bootstrap Example page and pasting ["*"] for Form and the following for Schema:

{
  "type": "object",
  "properties": {
    "thing": {
      "type": "string",
      "title": "Thing",
      "enum": ["b", "a"],
      "enumNames": {"a": "The A", "b": "The B"}
    }
  }
}

enum has "b" listed first, but it appears second in the select options.

Unminified libs

Hi there. I tired using files in src folder but somehow they dont seem to be the same as the ones in dist. Is bootstrap-datepicker.min.js the same as bootstrap-datepicker.js in derectives/decorators/bootstrap/datepicker ?

I am trying to wrap my head around your recent update and I am trying to make sense of it all as I go. I am still new at this, please bare with me 😄

I was wondering if you could include unminified versions of the files in dist folder.

Thanks

Hidden field in form

Angular schema form seems like a pretty nice tool to use.

One thing I couldn't find is how to render hidden fields with it.

Do you currently support hidden fields (for e.g. ID field)

datepicker with dutch translation won't "validate"

pickadate's dutch translation provides a rather complex, long dutch date format:

format: 'dddd d mmmm yyyy',
formatSubmit: 'yyyy/mm/dd'

asf's datepicker won't validate (max 10 characters). It will happily accept the sv_SE format, s/m yyyy
(no idea why these translations are so different)

since the formatSubmit is in the correct ISO format, shouldn't asf's datepicker just ignore the long version?