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.
We are looking for someone (or a group of people) to implement this component of Open Console. It requires experience to be able to achieve this. Do not start with it without dedication to implement 100% of the needs, and (of course) before you have contacted us.
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
- The software MUST be distributed with an Open Source license;
- The software MAY be released as a separate (re-usable) project, when that is useful;
- The software SHOULD be written in Python or Perl5, so make it easier to maintain;
- Produced html MUST use
ariaattributes and other Inclusive Design techniques.
- The software MAY use modern libraries, as long as they have a fully Open license.
- The specification SHALL not require anyone to buy a license or register somewhere to be able to use the provided.
- The only supported character-set is UTF-8.
- From the start, everything must be prepared to be maintainable and evolving on the long run.
The purpose of this specification is creating Forms.
- One organization MAY specify one or more Forms.
- One Form relates to exactly one service. There MAY be multiple Forms for one service, for different types of use.
- There will be a different Form edition for each supported language: translation needs to be done outside Open Console.
- A single Form consist of Sections (at least one)
- Sections MAY be shown in separate overlays (tabs) or sequentially.
- A Section contains Cells, which contain input Fields, FieldSets, or HTML.
- Within a Section, the Cells get organized in a way like the common
- Each Section MAY have a short intro (shown by default), a longer description (shown on request), and refer to external help (click away).
- 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.
- A Section MAY have limited support to be invisible or disabled based on the value of Fields in the Form.
- 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".
- Values of Sections and FieldSets are grouped in key-value pairs.
- Chosen names for Sections, Fields, Types, and FieldSet names use namespace prefixes and use non-blank printable ASCII characters only.
- The Root contains namespace declarations: prefix to URL mappings in XML style.
- 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.
- A FieldSet (like in HTML) can contain Text, Fields, and nested FieldSets
- The FieldSet MUST have a label.
- The FieldSet may have a short intro, description, or external help.
- A FieldSet MAY repeat, between a given minimum and maximum, by default appear only once.
- The FieldSet has a grid-based layout on its own.
- When a FieldSet can appear more than once, only one SHOULD be displayed. Ordering MUST be supported. Search MAY be available.
- Fields within FieldSets are flagged for short-list display, to select sets by hand.
- 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
- Input Field Types are supported to a level supported by libraries like jQuery: sliders, location pickers, color pickers, data-range selectors, etc.
- Types can be based on simple types.
- The Form specification can only hint on visualization based on the chosen Types.
- 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.
- 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.
- A Field will always have a label, which MUST be shown in a convenient way.
- A Field may have a short note, which MUST be used when available (input
- 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.
- When the User has no read Right on a Section, FieldSet, or Field, then nothing should be shown.
F. Input field changes
- 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.
- Saved changes will include the version of the Section which was used to compose them.
- Simple validation on Fields SHALL be available.
- A Section submit will not be allowed when any field does not validate.
- 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.
- Fields can be flagged as "required", which means: non-empty.
- It MUST be shown when a required field is not filled-in.
- 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.
- Each input Field MAY have an attribute
sincewith a version number, indicating the revision of the Section which introduced the Field.
- Each Section MAY contain a list of Field names which have been removed. This MAY be accompanied by an explanation which is shown.
- 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.
- 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.
- 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.
- All Sections will maintain historical records, showing who (identity) has changed what (fields) and when.
- The Form MUST be able to list the revisions of the Sections over time.
- Each Section MUST be able to display the history of that Section, showing the changed Fields.
- Each (historical) revision must be able produce a Summary, which only contains Fields with a non-default value in a compact way.
The user of the Form has access Rights, which are derived from his/her organizations and personal settings. These Rights are (namespaced) constants.
- Users have a collection of Rights, which MAY BE assigned via Forms filled-in by other Users in unrelated sessions.
- Rights are (namespaced) entitlements with (namespaced) values.
- The Rights are not standardized, which makes it syntactically a bit harder to express "Write right". See example below.
- Field, FieldSet, and Section attributes which express Rights or Validation MAY use boolean Formulas.
An example: prefix
appl is mapped to
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
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" >
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.
- The user SHALL be able to refuse its data for explicitly selected License holders;
- The user SHALL be able to set the default for emerging licensees;
- The user SHALL be able to be notified when licensees emerge or disappear;
The environment where these forms are used, differ from any set-up we have studied. The organizing implementation has to combine separate responsibilities. For each requirement must be decided where it get implemented, often a combination of actors.
- The user has a single website which gives access to forms produced by multiple organizations. The forms differ in content, but are consistent in appearance.
- The organizations offer one or more forms, probably in many languages. The form specification offers all features you expect from forms, but the execution is not in the hands of the author.
- The data which is filled-in can be downloaded by the form author, but remains property of the user, hence stored protected. The data may be in an old version of the form: no planned upgrade moments.
- Third parties may influence the behavior of the form with settings and defaults for fields.
The implementation of the connectors is outside the scope of the requirements.
Namespaces, form version management, and data version management
will be handled by Meshy Space.
That library also provides lists of standardizations to be used, some
basic abstract Types, and ideas about expressions. For instance, what
dc:author should express.
Preferably, existing standards are found for each part. In such case, a list of processing restrictions and needed extensions should be produced.
- Global Form syntax specification (XHTML or XForms like?)
- Layouting syntax specification (Fluid grid like?)
- Form Field validation syntax;
- Validation and Rights (boolean) Formula syntax (P3P like?)
- Data transformation to upgrade to next Form syntax (XSLT, XForms Mutations)
- Form field widget library with validation (JS);
- Form description to interactive HTML converter, runtime;
- Integrated documentation.
The specification SHOULD not be extremely complex (as, for instance, XML-Schemas), but mainly readable. Preferably in accessible form, via web-pages or wiki, not as a single paper document.