JSON Schema UI vocabulary

[Anthropic]

JSON Schema can be viewed as purely to define data structures and their validation, however there is a growing number of libraries seeking to generate UI for editing the data a JSON Schema defines.

These UI libraries are not interoperable at present and many contain different ways to do the same thing which can reduce the ability to move from one to the other without substantial re-work that could be avoided by a consensus of vocabulary.

There is a valid perspective that an independent format using JSON Schema rather than based on JSON Schema could be required, this does not conflict with the goals of this issue as even an independant format could benefit from users being able to define basic UI properties like enum titles within their data schema. Having a UI Schema does not mean it must define absolutely everything UI related, it may simply provide the groundwork for an independent format to provide a better value proposition to service consumers.

The goals of a JSON Schema UI vocabulary could include:

• defining how a user should expect a data schema to be presented for editing by a library/framework when some validation keywords can be infinitely complex and ambiguous in their intent
  • mapping enum values to readable titles proposed solution to document
  • what to do with *Of keywords, ie render when enough detail is provided
  • using the Hyper Schema to define related assets required for the UI such as dynamic drop down lists or lazy-loaded content
  • determine field ordering/display status
• hint / placeholder / information text so description may remain for defining the data model
• additional keyword(s) for linking a UI definition to the core schema object it is defining UI for
  • advocating for updates to relative json pointers and other pointer keywords like $data that could benefit more than just UI frameworks
• allowing a UI definition to be combined within a json-schema for single schema file definition or within a separate scope for UI switching
• expected changes to the UI based on validation conditions, for example, the editability, visibility, default value and mandatory status could be updated on the validation of a property/properties
• define widgets/templates and their properties as generically as possible
• defining a method for validation levels info/warn/error

It may well be that there is two components, a vocabulary for defining a core set of UI related properties and behaviours and a separate project for defining a unique format part of or independent of the json-schema-org that extends it into territory that does not fit as well within the structure of a vocabulary the org would want to maintain. The main goal of this beyond the above list is to find out where the line between the two may lie.

Note: Internationalisation of the UI is a separate concern and should have its own vocabulary discussion if desired, it would not form part of any UI Schema discussions directly.

@handrews

[romainpiel]

Thanks for the initiative, that's a nice start. I'm in the process of defining a Json schema for a system I am currently building (mobile focused) and it's not as simple as it could sound. It is mostly complex because various consumers might read the data in different ways. So if you define a Person:

{
    "title": "Person",
    "type": "object",
    "properties": {
        "firstName": {
            "type": "string"
        },
        "lastName": {
            "type": "string"
        },
        "age": {
            "description": "Age in years",
            "type": "integer",
            "minimum": 0
        }
    },
    "required": ["firstName", "lastName"]
}

We know for sure that an age is an integer for any "kind" of consumer.

Now say that we have profile view (I've mapped it on the previous example). This payload is consumed by an Angular client and an iOS client.

{
    "title": "Profile",
    "type": "view",
    "properties": {
        "firstName": {
            "type": "text"
        },
        "lastName": {
            "type": "text"
        },
        "age": {
            "description": "Age",
            "type": "dropdown",
            "minimum": 0
        }
    },
    "required": ["firstName", "lastName"]
}

How should I display age, what is a dropdown? A UI json schema should be versioned and I think there should be a way to describe that consistently. What if the Angular UI should show the lastName and the iOS version shouldn't? Or what if a dropdown is what we want on Angular but not on iOS.

It feels to me that it's going to be hard to have one single standard without staying too high level. A UI means different thing depending on the platform. I guess there is a common ground but it might be very concise:

• text
• input
• ...?

Another part I'm wondering about is constraints. In the scope of forms, it's quite simple. Things will usually show vertically one view under the other. For more complex UIs, we might want to show one view to the right to another one and then make a third view fill the width. Should we consider constraints? I think it might be an interesting question as it's essentially the same as asking, is this schema going to be able to describe the entire UI or what simpler entities that could be called view models?

[Anthropic]

@RomainPiel regarding the drop down part of the question, the bullet point about widgets is where this could be addressed, type would remain string (or whatever) and 'ui:widget' would become 'select' or something synonymous. The idea being all UI generators would provide the most common elements. Anything outside common would be designed for purpose and may not be as easy to migrate to another implementation without due consideration.

Constraints is one where 'classes' appeal to me, classes/tags can be used in a methodical manner to provide UI guidance for both web and for application interface. If I have a class of 'vertical-section' on a section widget for example I can ensure any version of my UI will display child properties of the section inline. However I am totally open to a more defined structure definition if there is consensus for such a direction.

[dlax]

@Anthropic

mapping enum values to readable titles

Isn't it something that got solved in draft-6 with const keyword to be used with oneOf (see https://github.com/json-schema-org/json-schema-spec/issues/57#issuecomment-247861695)?

[Anthropic]

@dlax to be clearer on intent, this is about documenting things exactly like that for UI producers to be able to consistently replicate. So documenting that exact expectation would indeed be a part of this proposal. Many other aspects may also already be solved within comments somewhere, but until they are combined into a form that all adherents can follow, the problem still exists that you cannot reliably expect consistent behaviour currently and users are not aware of how best to design their schemas for UI generation.

[Anthropic]

@dlax I added the link to the OP, I will be sure to do that when made aware of any solution proposals that could be documented. Cheers :)

[dlax]

@Anthropic Thanks for clarification! Clearly, I missed the intent but it now makes sense to me.

[coderextreme]

So what do we do when we extend into 2D SVG with d3.js or 3D X3D JSON. We already have an X3D JSON schema, but that's not for defining UI for schemas. How do we define SVG and 3D UIs for JSON schemas?

[handrews]

@Anthropic @RomainPiel @coderextreme please see the vocabulary support proposals for draft-08 for ideas on how to manage this and other vocabularies going forwards. I hope that we can lay enough foundation in draft-08 to proceed with developing the vocabularies and not have to worry so much about how they work. In particular, json-schema-org/json-schema-spec#561 is the starting point.

@coderextreme this would, in theory, make it easy to create and use (in an interoperable fashion) 3rd-party vocabularies.

So if a 2D UI vocabulary is designed (maybe standardized, maybe just well-advertised), then it would be easy to either replace it with a 3D vocabulary later, or layer a new vocabulary on top of it that adds 3D support while retaining compatibility.

[brettz9]

Very interesting proposal at https://github.com/mozilla-services/react-jsonschema-form/issues/701 which may be of interest here...

[Anthropic]

@brettz9 you will notice in that thread that Henry has already commented, I have also brought up with him an Intermediate Representation structure for when a ui-schema is merged with a json-schema for more manageable operations in frameworks. This would be outside the remit of the json-schema org, but ensuring it is at least not hindered by the spec is something that could be a desirable goal.

[philsturgeon]

Bump. Moved this to the vocabularies repo, who is still actively interested in pursuing this.

[handrews]

@philsturgeon let's wait on figuring out how we want to use this repo and manage (or not manage) work on new vocabularies before pushing people to take new action.

[philsturgeon]

@handrews I've been meaning to get the ball rolling on this one for ages, and finding people who are willing to chat about doing the work takes a little while. What the vocab looks like and where it'll live are two different things which can happen independently.