Open Console — Form Abstraction Syntax, version 0

There may be existing Open Source projects which implement parts of these requirements. When they are of good quality, they MAY be used fully or partially: those libraries will run in the Open Console infrastructure, so do not bother third parties.

Uppercased words like "MAY", "MUST", and "SHALL" are defined in RFC2119. Words with a leading capital have a definition within this specification.

Requirements

Many of the requirements below are really hard; the Open Console has to be prepared for a lot. The reasons behind these requirements are not detailed, but don't hesitate to ask.

A. Project environment

1. The software MUST be distributed with an Open Source license;
2. The software MAY be released as a separate (re-usable) project, when that is useful;
3. The software SHOULD be written in Python or Perl5, so make it easier to maintain;
4. Produced html MUST use aria attributes and other Inclusive Design techniques.
5. The software MAY use modern libraries, as long as they have a fully Open license.
6. The specification SHALL not require anyone to buy a license or register somewhere to be able to use the provided.
7. The only supported character-set is UTF-8.
8. From the start, everything must be prepared to be maintainable and evolving on the long run.

B. Forms

The purpose of this specification is creating Forms.

1. One organization MAY specify one or more Forms.
2. One Form relates to exactly one service. There MAY be multiple Forms for one service, for different types of use.
3. There will be a different Form edition for each supported language: translation needs to be done outside Open Console.
4. A single Form consist of Sections (at least one)
5. Sections MAY be shown in separate overlays (tabs) or sequentially.
6. A Section contains Cells, which contain input Fields, FieldSets, or HTML.
7. Within a Section, the Cells get organized in a way like the common fluid grid syntax.
8. Each Section MAY have a short intro (shown by default), a longer description (shown on request), and refer to external help (click away).
9. Very little decoration will be supported: for instance a small logo of the organization which maintains the form specification. The CSS will not differ between Forms by different organizations.
10. A Section MAY have limited support to be invisible or disabled based on the value of Fields in the Form.
11. Sections can be in separate files.

C. The Data

The filled-in Form is represented by a nested data-structure with the same structure as the Form definition. The handle for the data is referred to as "Root".

1. Values of Sections and FieldSets are grouped in key-value pairs.
2. Chosen names for Sections, Fields, Types, and FieldSet names use namespace prefixes and use non-blank printable ASCII characters only.
3. The Root contains namespace declarations: prefix to URL mappings in XML style.
4. The Root contains version information: when it has been produced, version of the Open Console installation, version of the used Form description, and so on.

D. Field Sets

A Section can contain FieldSets.

1. A FieldSet (like in HTML) can contain Text, Fields, and nested FieldSets
2. The FieldSet MUST have a label.
3. The FieldSet may have a short intro, description, or external help.
4. A FieldSet MAY repeat, between a given minimum and maximum, by default appear only once.
5. The FieldSet has a grid-based layout on its own.
6. When a FieldSet can appear more than once, only one SHOULD be displayed. Ordering MUST be supported. Search MAY be available.
7. Fields within FieldSets are flagged for short-list display, to select sets by hand.
8. When the User has no write Rights to any of the Fields in the FieldSet, the Summary should be shown at most.

E. Input fields

1. Input Field Types are supported to a level supported by libraries like jQuery: sliders, location pickers, color pickers, data-range selectors, etc.
2. Types can be based on simple types.
3. The Form specification can only hint on visualization based on the chosen Types.
4. Related checkboxes and radio-buttons SHOULD be treated as one Type, together with "select", they form one base Type which shape is chosen based on the number of alternatives and maximum number of picks.
5. Separate textarea Types for plain text and html text. The latter should invoke a HTML editor while changing. Maybe other text fields like "markdown" can be supported in the future.
6. A Field will always have a label, which MUST be shown in a convenient way.
7. A Field may have a short note, which MUST be used when available (input field title)
8. A Field may have a long help, which is a link to an external webpage within the namespace of the form provider. It MUST be shown when that help is available.
9. When the User has no read Right on a Section, FieldSet, or Field, then nothing should be shown.

F. Input field changes

1. The Section is locked for changes by other users: they can only open the form read-only and get a warning. Section locks will expire after TBD, after which changes cannot be saved anymore.
2. Saved changes will include the version of the Section which was used to compose them.
3. Simple validation on Fields SHALL be available.
4. A Section submit will not be allowed when any field does not validate.
5. When a Field has a default, it should be shown special and not be saved (because defaults may change). When the default is taken explicitly, it will need to be saved and not changed when the form default changes.
6. Fields can be flagged as "required", which means: non-empty.
7. It MUST be shown when a required field is not filled-in.
8. A Field MAY have limited support to be invisible or disabled based on the value of other Fields in the Form.

G. Form change management

It will be common that the forms will change. The configuration which was entered by users will not change immediately. Therefore, the forms MUST implement version management.

1. Each input Field MAY have an attribute since with a version number, indicating the revision of the Section which introduced the Field.
2. Each Section MAY contain a list of Field names which have been removed. This MAY be accompanied by an explanation which is shown.
3. Loading an old configuration MAY support simple automatic conversion of the form-data towards the new revision of that form. It may be dangerous to support smart behavior.
4. A Field may contain a "deprecated" warning, which should be shown. That warning may ask the user to, for instance, reconfigure it into a more complex alternative.
5. The Form, Section, and Field must be marker when it is new since the last time the user saved the Section (Field appeared in a Section version higher than the version kept in the saved Section data. The color of the marker MAY be green when there is a non-breaking change, and red when it really needs a visit.

For ideas, see Cambria and Confluence Schema Registry Compatibility Types.

H. History

1. All Sections will maintain historical records, showing who (identity) has changed what (fields) and when.
2. The Form MUST be able to list the revisions of the Sections over time.
3. Each Section MUST be able to display the history of that Section, showing the changed Fields.
4. Each (historical) revision must be able produce a Summary, which only contains Fields with a non-default value in a compact way.

I. Entitlements

The user of the Form has access Rights, which are derived from his/her organizations and personal settings. These Rights are (namespaced) constants.

1. Users have a collection of Rights, which MAY BE assigned via Forms filled-in by other Users in unrelated sessions.
2. Rights are (namespaced) entitlements with (namespaced) values.
3. The Rights are not standardized, which makes it syntactically a bit harder to express "Write right". See example below.
4. Field, FieldSet, and Section attributes which express Rights or Validation MAY use boolean Formulas.

An example: prefix appl is mapped to namespace https://example.com/Appl (the application Appl is produced by company Example). In the Form, you can manage servers. You may design that the (Form) User can have entitlements:

  appl:rights/server/add      or  appl:server/right-add
  appl:rights/server/delete   or  appl:server/right-delete

The actual choice for constant names is totally up to the namespace owner. Now, the Form description could contain something like:

  <FieldSet name="appl:server"
     write="appl:rights/server/add || appl:rights/superuser"
     read="appl:rights/server/read"
     maximum="10"
  >

J. License

The user will be able to see which Identities have a License to see the configured data. Probably, this is shown in a separate tab.

1. The user SHALL be able to refuse its data for explicitly selected License holders;
2. The user SHALL be able to set the default for emerging licensees;
3. The user SHALL be able to be notified when licensees emerge or disappear;