The (underlying data schema) API

[mohsen1]

Based on our discussions, it would be very beneficial to make the core component dependency-free and expose the core component via different means(AngularJS directive, React component or web component)

For that, we need to agree on the API of the core component. What should core component get and what it should return?

For starters I put these input/output lists here:

Input

• Form Schema (JSON Schema)
• List of templates (HTML Handlebars templates)

output

• Data object to write the result of the user input (aka ng-model). Question: should we have getter/setter for this?

events

• change (also keypress?)
• Form submit
• Validation error

[kentcdodds]

I would highly encourage a using a custom field config object with the ability to convert a JSON schema into this field config object. JSON schema is verbose and unnecessarily complex if you're only wanting to setup client-side forms and your server doesn't use JSON schema as well. But JSON schema support is a must I'd say as well.

I think it would be pretty cool if we could figure out a way to decouple our library from the DOM. So we wouldn't need to be opinionated about what the templates/types look like. Also, validation works so differently between the different frameworks that I think that maybe that could be pushed down into the adapters as well because I think it would be valuable for us to leverage the framework where possible. I just don't want to have to fight the framework when it comes to making these adapters...

[bvaughn]

Agreed with Kent. Custom field config will be necessary because of custom validations (which seem to be fairly common, at least among formFor users).

Decoupling validation and display also seems like a nice goal, although I feel we'd likely want to provide a couple of default templates (e.g. Bootstrap, Polymer, whatever) as folks are unlikely to want to always write these from scratch.

FWIW, I think our validation and object-watching can be totally vanilla ES6. I might be missing something obvious, but I don't think we need any framework(s) to be involved.

[davidlgj]

I agree wholeheartedly with @kentcdodds on that we should use our own format for field configuration and not marry ourselves to JSON Schema, its just to limiting in its validation.

And +1 for vanilla ES6

[kentcdodds]

Totally agree @bvaughn that we should create default templates to encourage adoption. This is the approach I've taken with formly and it's worked really well. I always encourage people to create their own templates if they want to get serious about stuff (though, as formly has recently become much more flexible this is less necessary)

Whatever we do, we should make it very very easy to get started and very very easy to extend what exists to customize it. I think the API simplicity should be paramount so this is a terrific issue to discuss.

Also, I seriously recommend that we look into my apiCheck.js library. It's still fairly young, but it's vanilla-js (ES6 authored of course) and it helps people figure out the API without having to review the docs or post an issue.

[mohsen1]

If we're going to have our own format, how about extending JSON Schema itself? There are a couple of benefits to that:

• JSON Schema has a hyper schema that validates JSON Schema spec files. If we extend that hyper schema, we can get free JSON Schema validation for the objects people pass to this component.
• JSON Schema will work with no adapters.

[kentcdodds]

I'm not certain what this would entail, but I'm mostly concerned about the API. One of the things I work really hard to accomplish with formly is an api that is so simple that you only have to look at it once and then never again. This is helped a great deal because of apiCheck, but I think a simple api with an adapter is more valuable than a complex api without one. Even if it means more work for us.

[bvaughn]

Sounds to me like @mohsen1 is a good candidate for owning the JSON schema portion of forms-js. Seems like you're the one who feels most passionate about it (and who has the most experience with it). I'm comfortable with you making the schema-related decisions.

I think we should define what our validation input looks like first. Make sure it's robust, sexy, etc. - then we can tackle a utility that consumes JSON schema and generates this validation format.

[mohsen1]

Just to be clear, I hate JSON Schema too! It's weird and has almost no documentations!

But
JSON Schema is a well defined standard. JSON Schema at IETF. At first look most things look weird, but there is always a good reason why the did it that way. For example @kentcdodds brought up required in our call. Sure, it makes tons of sense to put the required as a boolean property in the property definition itself. It's cleaner and everything is together. But it won't work when you have two properties that one of them (oneOf) is required. So they had to put the required filed outside and make it an array.

I promise we will have to redo all the work people did in JSON Schema working group over the years if we decide to make our own schema.

[bvaughn]

To me, that sounds like another argument for a configuration object that allows users to provide either truthy/falsy values or custom callbacks that return truthy/falsy values or custom callbacks that return Promises. At that point, it's relatively easy to implement complex logic without the mental overhead of parsing/understanding a schema.

[kentcdodds]

Also, we have the luxury of JavaScript, whereas they had the limitations of JSON. I know that there will be those who use JSON schema and they'll want to use this library, which is why we'll make an adapter for it. But I believe that the main use case (based on users of angular-formly) will be those who just want to configure their fields with JavaScript.

[mohsen1]

We need a list of properties with type, title, description and other information about each property. That list has to be recursive and allow arrays and so on. Everything we need is already in JSON Schema. We can extend JSON Schema to allow a lot more than that. I don't think it's a wise decision to not use JSON Schema for that list of properties.

[mchapman]

Strongly recommend you have a look at something like mongoose.js schemas and the idea of extending them (following the principle, but probably not the detail, I adopted in my library). I have been sending the schema from the server, but if there is something like a cross between pouchdb and mongoose then that would be a good place to start - it would give the most frictionless starter apps / demos.

[bvaughn]

We need more than just static (or pre-defined-conditional) validation though. Many of formFor's users need support for async, JIT validations. That can't be achieved with something like JSON schema.

[kentcdodds]

👍 for that @bvaughn. JSON schema just isn't powerful enough. We need to enable people to use JavaScript. And if we're going to do that, then let's just leverage the power of a real programming language altogether and make the api simpler while we're at it.

[mchapman]

I agree, but think that Mohsens's diagram handles that well. Use JSON for the simple cases, and base it on something that is already well understood. This can include simple validation (min, max, patterns etc as in mongoose schemas). The advantage of doing this is two-fold - less education for those that already use that form of JSON schema and something tested in real life for others. Trivial forms can then be generated without the "Customizer Object" (or probably with a null one).