[Proposal] JSON UI Schema

[Anthropic]

EDIT: This is now being tracked at json-schema-org/json-schema-vocabularies#2 as its own project.

Please join us there for further discussion!

---

I propose a separate schema extension for the view definition in the same way hypermedia was separated into its own schema.

JSON Schema Form has a form definition that is array based for ordering, with the majority of its attributes taken from json-schema. It also has titleMap array to define labels for enum fields and can define field types (including custom field types) to use for displaying the field.

As it describes nothing more than a type name it is generator agnostic and not destined to be specific to our Angular implementation. In fact we are already working on making a plain JavaScript version and there is already a React implementation.

The main purpose of raising this here is to highlight a need, in our view, to avoid allowing view based attributes to diminish the data definition purity of the json-schema specification.

Choices and Enum Names would both bring changes to json-schema that would confuse any existing view based frameworks like ours and others while bringing little value and breaking model view separation of concerns. A full json-ui-schema would provide the missing view properties while keeping view and model separate, as they should be in our view.

In addition to a ui-schema, the same way the main json-schema has an extension for hyper media, we would also like consideration for a json-rules-schema for controller/field logic (if/when etc..) and json-flow-schema for workflow/wizard/state management keywords.

I am interested in feedback primarily on the json-ui-schema proposal. But all feedback is welcomed.

Proposal:
JSON Schema UI vocabulary
Child issues:
#252 2017-02-16

[erosb]

I welcome this proposal. It is a much better idea than trying to hack UI-specific keywords into JSON Schema.

[handrews]

I'm definitely in favor of a UI-oriented schema extension. I have no idea whether it is reasonable to include it directly in this core project or whether it should be an independent effort. Either way, it would be very helpful to be able to respond to UI-oriented proposals with "please make this proposal in the UI extension".

We would need to come up with some way of determining what annotation properties, if any, would stay in the existing three parts of JSON Schema. In my opinion, anything that is useful for documentation (like description) or instance processing (like default) should stay in the validation document.

On the other hand, enumeration names should probably go in a UI extension because description is sufficient for human-oriented documentation. The individual enum names are only needed for matching them to values in the UI.

[handrews]

@Anthropic if you would like discussion on the json-rules-schema idea, could you please file it as a separate issue? I think it is too different from json-ui-schema to discuss in the same issue without the whole thing becoming confusingly muddled.

[Anthropic]

@handrews the other extensions I consider as something to discuss after we determine how to approach json-ui-schema. I already created an org of that name just in case.

Regarding properties, I see description as being used more for what you would write in a MySQL field description rather than as a field hint like some use it now. I would like a separate hint field for that.

With json-schema-form we currently allow most json-schema fields to be overwritten in the ui-schema as it is very often the case that an online form will only display part of a data definition. As such we do not validate for fields not added to the ui-schema or removed by logic rules. Obviously a field may still be hidden. You can see our current behaviour at http://github.com/json-schema-form/angular-schema-form documentation.

If interested, I can created a repo in the org I registered and add all json-schema admin interested as admin to that also? Then create a rough draft spec based on our usage as a starting point. Also worth considering to keeping it within this org too, probably easier if it is, just means giving me admin rights on a json-ui-schema repo here to get started.

[Anthropic]

@awwright I finally made the issue for what I discussed with you previously

[awwright]

@Anthropic I've been following this, but you and everyone else seems to have already said pretty much everything I had to say, haha.

I'm very interested in building UI's from a JSON Schema, so I'd like to advance whatever would help accomplish this.

What you describe follows my experience with building user interfaces from JSON Schema pretty well, especially that even for a single JSON document, you'll want to be able to create multiple different forms to edit it in different ways. For example, editing your own comment on a blog, vs. moderating comments on a blog.

There probably should be some way to specify a "default" style, though. If I'm browsing a JSON API annotated with JSON Schema, my user-agent should still be able to show a sensible rendering of an editable JSON document.

[Anthropic]

@awwright well the way that angular-schema-form handles it, we allow users to define an x-schema-form extension object type property on the schema for users who for whatever reason cannot work with two files. But by making it a single property it still clearly maintains an identifiable separation of concerns. We do only recommend it for very small forms though.

If we rename and allow perhaps a ui-schema property to do that, it would still make it part of the ui-schema definition extending the main json-schema spec. Also a schema could always be tied to its ui-schema by a top level ref... or even an array of oneOf ui-schema ref...

[awwright]

JSON Schema Core defines a framework to allow an arbitrary JSON document to be described in any way. I imagine a UI vocabulary would just be another vocabulary following the JSON Schema paradigms, and application/schema+json media type.

Suppose we had entirely different vocabularies for validation and UI. If you want to describe a single document with both vocabularies, you could set two rel=profile links on the instance (one per vocabulary). Or just use one, and do something like:

{
    $schema: "http://json-schema.org/draft-04/schema#",
    type: "object",
    /* ... */
    allOf: [ {
        $schema: "http://json-schema.org/example/json-ui",
        fields: /* ... */,
        /* ... */
    } ]
}

[Anthropic]

@awwright our ui-schema includes all the same values in the main schema with type defining templates to use (so a enum type in the schema can be type select in the ui-schema).

The main differences to core schema in our implementation being:

• for the sake of always maintaining order the definitions are within an array
• it includes a key value pointing to the schema def (the array item can either be the key value or an object with key defined, it isn't currently a jref as at the time it was unclear how to work with arrays at the time)
• there is a titleMap for enum labels (name, value, group and any additional properties)
• some basic conditional logic processing, currently quite "Angular" but looking to change that.

There's more to it, you can see the docs here at the ASF repo

So a vocabs could work, are you thinking json-LD style? I like your example. I'm assuming that fields would be like the array in our definition, but also able to take a $ref?

Obviously I don't expect everything we do to be adopted, far from it, I know some things I don't even want to keep (like functions on the object) so I am very open to making changes! But I was thinking there's enough in our definition to get discussions started depending on where you feel is best for that to take place.

[nicklasb]

Hi @/all,
When @Anthropic, me and some more people discussed the json-rules idea, I created the json-rules org and repo here: https://github.com/json-rules/json-rules

We used gitter, but I guess we've come far enought to discuss publicly, I have started a thread here: json-rules/json-rules#1

[awwright]

@Anthropic I believe it's similar to JSON-LD; the vocabulary in use is selected by "$schema".

When I've been looking for a UI solution, there's two requirements (iirc) that I can think of, that vary slightly from what angular-schema-form is covering:

One is to assist browsing of JSON APIs that would otherwise be unstyled. So if I open up my (JSON-aware) user agent, punch in a URL of a JSON document, I can see it, I can choose to edit it it, and I can persist those changes (with a PUT request). A UI schema would be used to do things like declare data relationships ("this field points to an existing user ID") and processing ("readonly: this field is set exclusively by the server -- don't define it, or whatever it is now, don't change it, changes will be lost")

The other is that I already have an HTML form, and I want to generate a JSON document from it, and provide localized (translated) and field-specific highlights for errors.

Or maybe some hybrid. Maybe I have an HTML website, a JSON instance (e.g. representing a comment on a blog post), and I want to present it to users, editable, with some values read-only or not used at all (for example, their username, IP address, and date of submission).

It seems like angular-schema-form only handles this hybrid case right now.

We need to figure out which of these cases overlap and which are really different technologies.

The big thing is that anything going over the wire gets described by JSON Schema Validation or JSON Hyper-Schema:

• Sometimes abstract resources (a blog post) will have multiple JSON representations. A blog post might have a representation aimed for the public, and a representation for moderators that includes a revision history and IP addresses.
• Instances can describe how they relate to other instances: read only (set only by the server), relationship to another resource that must exist, etc.
• form fields might choose to render themselves differently depending on the validation restrictions (e.g. automatically use <input type="number"/> for type:"number" properties).
• If the value we want to send would be invalid, we can try to trace the invalid value back to a particular form-field and display an error there.

(Some of these features might not be well-defined yet, but they would be good fits for JSON Hyper-Schema.)

So even without a dedicated UI vocabulary, there's still a lot of information for a form generation toolkit to work off of.

What other features do we need, can we come up with a list?

[Anthropic]

@awwright do you want to pick a spot in the wiki for planning to get a start on a requirement/use case list? It could get rather difficult to track if we start posting requirements and use cases in numerous posts on this issue.

I totally agree that any data transmission should be defined by those two schema, that's why when I implemented remote enum option retrieval I used the hyper-media link with a rel of 'options'.

At the same time there is obviously, based on other issues raised, a consideration to re-evaluate the hypermedia schema which could go hand-in-hand with any requirements garnered from a considered requirements list for a ui-schema.

[mmc41]

Good initiative. I am also interested in this. I am however, a bit unsure about how json schema extensibility works (what is possible / what is not) when using a schema extension for defining the view. F.x. Can existing json schema elements be extended in this way or do we have to create new, more powerful alternatives ?