[Proposal] JSON UI Schema: define UI behaviours for all current elements

[Anthropic]

Issue

I always feel uneasy about *Of being assumed to be acting to define model properties not found in properties and I see other potential future options 'select'/'if' looking the same way. I feel it inhibits the ability to accurately generate a UI without needing to process validation or model keywords as if they are a ui-schema definition.

I have seen implementations provide a plus sign and then display part of the form that is in the oneOf list and I've seen all sorts of other combinations where implementations have tried to define what option to display in a drop down to choose a form fragment to display. I've seen discussion around special types of keys for referencing the *Of elements from a UI schema.

I don't believe we should create a blueprint and leave out important structural details and ask the builder to decide what to do.

Proposal

*Of

I'd like to see all properties defined in *Of, or any other keyword that can bypass properties, be required in properties and relatively referenced instead if the user intends to have a form generator display the fields at all. In addition I would like to see a clear definition of how any such item is to be processed to display so that implementations can provide a level of consistency, this is not specifically about the look, but instead the elemental level, at least, of what is provided (a select could be tabs or radio buttons for example).

Essentially something along the lines of: if the fields are in properties and there is a title value within all the oneOf's then make them selectable sub schema, otherwise, don't and use them only for validation instead.

Obviously to be refined, but I wanted to give an idea about the direction of what I am suggesting.

Keys

To be clear, I am not suggesting you MUST have everything in properties, if the schema is purely for **validation"", you do not need to, however if you want the fields rendered at all, then they should be.

For Model and UI purposes I believe it makes more sense for them to be required in properties as it makes it easier to reference them as keys internally by any implementation. I believe it is also required for clear UI schema definitions.

Definition

I would like to see any new proposals require a definition and discussion on how it should be rendered in the UI, both with, and importantly without, UI Schema. As part of UI schema I think it should define an option to just render the schema in the way json-schema-form has "*" and "..." key options that should render the fields based exclusively on their schema definition. As such the UI schema specification will need to define how all elements should be rendered both with and without additional information provided..

Feedback

I would like to hear perspectives on this for consideration. I know @awwright has expressed a desire to always know how the schema should render and @Relequestual @epoberezkin @handrews may have input on this too, but if anyone knows people related to implementations please tag them in.

relative of: #67

[epoberezkin]

@Anthropic to summarise:
Problem - it is impossible in general case to generate UI from a given JSON schema
Solution - to restrict JSON schema (or to define required restrictions) in such a way that it is always possible to generate UI from it

Is it what you are saying?

[Anthropic]

@epoberezkin close, not restricted in that anything is required, no change to validation ideally. Just definition that tells users in the spec if you don't have this attribute then what you add won't generate in a form as there's not enough information, so clarification for each element within the spec to explain the UI required elements and what that would produce in a non prescriptive way where possible.

Is that clearer at all?

[epoberezkin]

@Anthropic so then the problem you want solved is the ambiguity in how UI should be generated from JSON schema, and the proposed solution is to define additional specification and/or keywords to make UI generation deterministic. Is that right?

[Anthropic]

Yes, that's the essence of it, the other parts are all related to that so that's the most important element.

[handrews]

Lots of good stuff here, @Anthropic! Overall, I think that JSON UI Schema should include a section clarifying how it interacts with any validation keywords that could be ambiguous or problematic- see PR #251 for hyper-schema where I exclude any hyper-schema keywords under a "not" (at any level of depth, no matter the validation outcome) or from non-validating or otherwise irrelevant subschemas of "oneOf", "anyOf", or "dependencies". I also clarify how to use hyper-schema keywords with "contains", which requires a bit more specification than merely using "contains" for validation.

I see other potential future options 'select'/'if' looking the same way

I think "if" in particular could be leveraged to express UI field interactions- display the fields from the "if" and depending on the contents entered, either display the "then" or "else" fields. This could handle quite a few interactions without necessarily needing to define new keywords for UI.

---

I need to think through your proposals a bit more before responding further. In general, the validation spec should make sense without (and be unconstrained by) hyper-schema, UI schema, etc. UI schema, hyper-schema, etc. should specify their own constraints and exclusions on validation as needed.

[epoberezkin]

In general, the validation spec should make sense without (and be unconstrained by) hyper-schema, UI schema, etc. UI schema, hyper-schema, etc. should specify their own constraints and exclusions on validation as needed.

@handrews I agree

[epoberezkin]

@Anthropic I think there is a bigger problem with using JSON schema for UI generation, and it consists of two parts:

1. it is impossible in general case to generate "form UI" from any given JSON schema
2. it is impossible in general case to describe any given "form UI" using JSON schema (that is also used to validate the data in the form).

@awwright would probably say that there are two sets - the set of JSON schemas and the set of "form UIs". Only a subset of JSON schemas can be converted to "form UI" (with or without additional definition file). Only subset of "form UIs" can be expressed using JSON schema.

The problem you are describing (ambiguity) is a part of problem 1 stated above.

I can elaborate or illustrate with some examples, I was raising these problems in #67.

[epoberezkin]

@Anthropic @handrews A bigger question for me is that I do not understand the motivation to standardise the format of JSON file used for "form UI" definition. Standardisation is a substantial effort on its own, as we all can see from JSON schema and hyper-schema, that goes far beyond just understanding what the standard should or could look like. So unless we clearly understand the motivation behind such standardisation, the problems we want to solve and the criteria we need to meet, there will never be enough effort from community to create and publish such standard. The fact that we have a lot of conversation about UI schema and no real progress I see as a confirmation that the motivation is unclear and the goals are not set.

Don't get me wrong here please. I totally like the idea of using JSON format as a schema to generate "form UI", and there are many ways to do it (in combination with JSON schema as @Anthropic is doing or separately like some other libraries do, when JSON schema is only used for validation, but not for defining UI - that's the approach that @handrews seem to prefer and I like it more as well). I am only questioning the need for a standard here as opposed to multiple library-specific file formats (that can use JSON schema to define such formats).

In general, such standards are usually needed to provide interoperability between different systems, particularly when they use different languages. When we are talking about data transfer/storage we need a standard to define the schema for such data, and JSON schema addresses this need. What kind of interoperability problem we would solve by standardising "form UI" definition schema?

The common ground that already exists for UI applications is web standards (HTML/CSS/JavaScript), and these standards are adopted in desktop, mobile and embedded platforms, so we don't really have multi-language problem here. Neither we have multi-system problem - different platforms usually need differently looking UIs for the same app. And if we want to generate UI for non-web platforms (e.g. desktop, native mobile apps), we usually have to follow very different UI conventions and these platforms already have their own very advanced ways to define UIs.

What I think is long due is a standard for UI to supersede HTML/CSS, as using them to define application UI (not just "form UI") seems like the most unnatural part of web application development to me. But I don't think it should be JSON based. And it is completely out of scope of this discussion.

I would really like to understand the motivation why do we need a JSON-based standard for "form UI" and not just libraries that solve that problem.

[handrews]

@epoberezkin There are many JavaScript frameworks and/or JS+HTML+CSS component systems. A JSON-based form description system allows implementations in multiple frameworks or component systems to produce the same UI. This is of tremendous benefit when a codebase inevitably drops an older framework for a newer one (in JS development, this seems to be necessary every two to four years depending on how much you want to deal with bleeding edge vs outdated/unsupported systems).

JSON Schema Form is already dealing with this in that it started as an Angular project, has a semi-independent React incarnation, and is trying to construct a framework-neutral core. But even with a core that multiple of today's frameworks can use, a large enough paradigm shift in UI development will require a new implementation.

Additionally, I see UI Schema as describing interactions independent of HTML/CSS vs mobile native vs (unlikely as it may be to occur) desktop native UIs. Not all concepts will translate equally well, but the ability to work from a common specification to provide the best implementation of the form in the given type of UI is a big win.

In short, I see a lot of reasons for a JSON UI schema. The effort involved in the standardization is irrelevant to whether it is needed- JSON UI schema does not block any of the JSON Schema standards already underway. This is why I assert that validation must not be aware of, much less dependent upon, UI schema.

The fact that we have "no real progress" means that we just started and most of us are trying to get Draft 06 of the main specifications published. I've personally been avoiding starting large new discussions, so it's not like there's been effort to get conversations started that have failed- we just haven't had time to focus on it yet. However, there is a great deal of enthusiasm for the project among my co-workers and we will hopefully be able to participate more in the near future.

[epoberezkin]

@handrews I agree that there is a need to define UI / interactions in framework/library agnostic way. I still see two problems though:

• while we call it UI definition, we essentially constrain it to "form UI" definition, so the wider need to describe UI is not addressed (layout, constraints, etc.). At the very least we should refer to it as a "form UI schema" rather than "UI schema" to have it correctly scoped.
• I am not convinced that such standard should be JSON based, and not XML based or even a separate DSL completely. UI definition has two dimensions (even if you constrain UI to forms) - tree structure and node attributes, and JSON, unlike XML, only supports tree structure. While you can cram both tree and attributes into JSON, the result is usually too verbose. And to properly define UI you would most likely need expressions as well... There are examples of successful non-JSON based DSLs lately (e.g. react JST, GraphQL) and while I think JSON is very good for data schema, I am not equally convinced about JSON being good for library agnostic UI definition standard.

[handrews]

@epoberezkin if you don't support a JSON UI solution, just don't participate in it. Feel free to start an XML-based project elsewhere (I'm not touching XML for this, personally). If you want to help shape the direction of a JSON-based system, that's a welcome discussion (although perhaps you should file your own issue rather than dragging @Anthropic's off in different directions). But if you just don't think it's a good idea in general, ignore it- no one will force you to implement it any more than you will be forced to implement hyper-schema, which you don't seem to find useful either.

[epoberezkin]

@handrews I am expressing concerns I have and I am interested to know how you think they should be addressed or why you think they should not be addressed. What I want is to:

• clearly define the problem we want to solve (any UI? form UI? Code generation? Only HTML/CSS generation?)
• understand the goals and requirements (which behaviours to support? Which UI structures to support?)
• understand the scope and limitations (Limited to JavaScript/web land? Completely language agnostic?)

I am not saying that JSON-based form UI definition is not needed, I am just looking for "shared justifications" of it being JSON-based, rather than using it as a default choice. Considering alternatives is the only way we can answer the questions above and justify our design choices.

Exactly because I am interested I am raising all these questions as we seem to have skipped them all and jumped to implementation details straight away.

hyper-schema, which you don't seem to find useful either.

Where this is coming from? :) Never said it's not useful.

[awwright]

@epoberezkin Would an existing implementation not need to be deterministic? Maybe it would be inconsistent between implementations, but I don't really see a problem if the output is always valid.

[epoberezkin]

Sorry, I don't understand the question, you lost me here completely... Which implementation?