November 2014
Twan Goosen
Outline
Component Registry Front-end Specification
Notes:
- the term 'component' refers to both components and profiles unless mentioned otherwise.
- some functionality mentioned in this page is marked 'CMDI 1.2'. This means that the described feature is introduced in CMDI 1.2, and should be implemented in the version of the Component Registry (both front-end and back-end) that supports CMDI 1.2
- examples given are based on CMDI 1.1
Global requirements
Authentication
Authentication in production is based on Shibboleth; for local testing, basic authentication on basis of the Tomcat UserDatabaseRealm is used.
- User authentication state is provided by the backend
- This includes admin status of the logged in user
- A login button or link is shown while the user is not logged in; after login, the user's name is shown
- Logout is not supported by the backend
- Once logged in, a link to the 'settings' page in the backend is provided (this allows the user to configure some account details)
Browser
- Listing
- Fields: Name, Group, Domain, Creator, Description, Registration Date, Comments
- Sortable by any field
- Search/filtering
- Also by component ID
Spaces
A user can switch between various 'registry spaces' depending on their login status and group membership
- Public space
- Private workspace
- Group workspaces (one for each group the user is a member of)
- The list of accessible groups can be retrieved via a dedicated call of the REST service
- CMDI 1.2: Review space
- This is not supported by the back-end at this stage
Component details
- Component Specification XML retrieved from back-end
- Hierarchical view
- With expandable component structure
- Verbatim XML
- Truncated if too long
- Comments
- Logged in users can see all existing comments on any component they can see.
- Logged in users can create comments on any component they can see.
- Users can remove the comments that they created themselves
- Admins can remove any comment
Actions
The following actions are available in the browser:
- Primary generic actions (visible as links or buttons)
- Create new (only enabled in the private workspace)
- Edit (applies to a single selected item; only available in the private or group workspace)
- This will open the editor with the selected item; when saving, the original will be overwritten
- Edit as new (applies to a single selected item; only available in the public workspace)
- This will open the editor with the selected item but only the 'save as new' option enabled
- Import (only available in the private workspace)
- Move to group (only available in the private or group workspace)
- Linked to a group selector; when chosen, moves the selected item(s) to the selected group
- Secondary item specific actions (only visible when an item is selected to provide context, e.g. a context menu)
- Delete item (only available in private or group workspaces, or in the public space for admins)
- Show info (always available)
- Provides reusable links to the selected item (XML, XSD and UI)
- Download XML
- Download XSD
RSS
Links to the following RSS feeds (generated by the back-end) are present:
- Any components space
- Comments on any specific component
Editor
The editor gets the XML of an existing component specification from the back-end (in the case of editing an existing component) and produces a form on basis of this.
Apart from a set of global component properties (see below), the user can create a hierarchy of components, each with an arbitrary number of attributes and elements (the latter in turn can contain attributes). At each point, the tree must be expandable by inserting a component, element or attribute (where applicable); likewise, previously created items should always be removable. Easy navigation within the tree should ideally be facilitated by means of options to expand/collapse subtrees and/or a compact overview of the tree on the side.
The exact same editing functionality is available for both components and profiles. The nature of an item (component or profile) can be toggled at any point until publication.
Global properties
Each component has a set of mandatory global properties than can be edited:
- Component nature (profile or component)
- Name
- Constrained to allowed options for XML element names (e.g. cannot contain spaces)
- Description
Optional properties:
- Group name (unrelated to the group space functionality!)
- Domain name
- Drop down from a fixed list of domains
- Concept link
- URI field with the option to search for registered data categories links in ISOcat (see below)
All values are stored in the 'item description' in the backend; some values (name, description) are duplicated in the header of the actual component specification XML, see for example:
<Header> <ID>clarin.eu:cr1:p_1361876010602</ID> <Name>DiscAn_TextCorpus</Name> <Description>A CMDI component for text (i.e. written) corpus resources, as used in the Discourse Annotation Project.</Description> </Header>
In the component hierarchy, attributes are defined first, followed by elements, then components.
Attributes
Components and elements can have any number of attributes defined
Attributes have the following properties:
- Name (mandatory; must be a valid XML attribute name)
- Type (mandatory; see below for details on selection)
- Concept link (optional; see below for details on search)
For XML examples, see Elements and Components.
Elements
Components can have any number of child elements defined
Elements have the following properties:
- Name (mandatory; must be a valid XML attribute name)
- Type (mandatory; see below for details on selection)
- DisplayPriority (mandatory - each component must have at least one child element with a value > 0)
- MinOccurrences (mandatory, should be an integer >= 0)
- MaxOccurrences (mandatory, should be an integer >= MinOccurrences or 'unbounded')
- Concept link (optional; see below for details on search)
- Documentation (optional)
- Multilingual (optional boolean)
Elements can have any number of attributes as children
XML example of an optional (0:1) 'string' type element with one attribute
<CMD_Element name="myElement" ValueScheme="string" CardinalityMin="0" CardinalityMax="1" DisplayPriority="1" Multilingual="false"> <AttributeList> <Attribute> <Name>elementAttribute</Name> <Type>string</Type> </Attribute> </AttributeList> </CMD_Element>
Components
Components can have any number of child components defined. These can either be references to other components with an ID of their own, or inline components that constitute a level of hierarchy but cannot be reused outside the context in which they are defined.
Linked components will be expanded by the back end when the client request the full XML or XSD representation of a profile.
Linking in existing components
Existing components from the public, private or group spaces can be chosen for inclusion as a reference. The following properties can be specified on the reference:
- MinOccurrences (mandatory, should be an integer >= 0)
- MaxOccurrences (mandatory, should be an integer >= MinOccurrences or 'unbounded')
XML example of a reference to the GeneralInfo component
<CMD_Component name="GeneralInfo" ComponentId="clarin.eu:cr1:c_1290431694495" CardinalityMin="0" CardinalityMax="1" />
Inline components
Inline components have the following properties:
- Name (mandatory, should be a valid XML element name)
- MinOccurrences (mandatory, should be an integer >= 0)
- MaxOccurrences (mandatory, should be an integer >= MinOccurrences or 'unbounded')
- Concept link (optional; see below for details on search)
Inline components can have any number of attributes and elements as children.
XML example of a 1:N component with an element and an attribute as children:
<CMD_Component name="DiscAn_TextCorpus" CardinalityMin="1" CardinalityMax="unbounded"> <AttributeList> <Attribute> <Name>componentAttribute</Name> <ConceptLink>http://www.isocat.org/datcat/DC-3870</ConceptLink> <Type>string</Type> </Attribute> </AttributeList> <CMD_Element name="childElement" ValueScheme="string" CardinalityMin="1" CardinalityMax="1" DisplayPriority="1" Multilingual="false"> ...
Type selection
Elements and attributes have a 'type' property. There are three types of type, which can be chosen from by the user in all cases:
- 'Type': a single data type corresponding to the basic XML types (e.g. boolean, string, decimal, time)
- The available options should be requested from the REST service
- 'Controlled vocabulary': a closed controlled vocabulary with a set of option that can be defined by the user
- Each item in the vocabulary has a value and optionally a display value and concept link (with ISOcat search, see below)
- 'Pattern': a regular expression pattern - the UI should give a short explanation and/or a link to documentation about regular expressions (as supported in XML)
CMDI 1.2: the user should have the option to link the field to an external vocabulary OR import an external vocabulary as a closed vocabulary
ISOcat data category search
Concept link fields have an option to search in ISOcat. The search facility should provide the following functionality:
- A text box for entering a search term that should match name, definition or identifier
- A table of search results showing the properties of each matching data category
- A method of selecting a search result or to cancel
- Selecting an result should fill in the data catagory URI in the current field
- Search results should be limited to:
- 'container' categories if the concept link is for a component
- 'complex' categories if the concept link is for an element or attribute
- 'simple' categories if the concept link is for a vocabulary item
Actions
Global actions that close the editor:
- Save
- Saves the current item; only available if the editor was openend on an existing item in the private or group workspace
- Save as new in private workspace
- Saves the current editor state into a new item; if the editor was opened on an existing item, it will not be affected
- Publish in public space
- Saves the current editor state and changes the item state from private (or group) to published, moving it out of the non-public space
- Should fail (with a friendly error message) if one of the directly referenced components is not public yet
- Cancel
- Discards any changes in the current editor state, does not update, publish or copy the item in any way
Client side validation
The following rules have been extracted from the Flex UI code:
- Attribute and Field names
- RegEx:
^[A-Za-z0-9_\-]+$ - siblings (of any kind) cannot have the same name
- RegEx:
- Concept links
- RegEx:
^([^:/?#]+):(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?$
- RegEx:
- Cardinalities:
case minimum maximum check 1 UNK UNK OK 2 UNK number maximum ne 0 3 UNK unbounded OK 4 number UNK minimum le 1 5 number number minimum le maximum 6 number unbounded OK 7 unbounded UNK NOK 8 unbounded number NOK 9 unbounded unbounded OK UNK can be either a missing attribute or an empty value, both can be detected with normalize-space(@...)='' default CardinalityMin is 1 (based on the XSD minOccurs default value) default CardinalityMax is 1 (based on the XSD maxOccurs default value)
Mandatory fields:
- name (on every level)
- component description
- display priority
- should be filled in with a positive integer and among siblings at least one value should be > 0
- value scheme (either pattern, vocab or simple type)
Also see the general component schema, in particular the schematron annotations (sch:pattern elements).
Importer
The importer should provide the option of uploading an existing component specification XML file from disk, which then gets sent to the back end as a new private workspace submission.
API documentation
There exists interactive API documentation of the production version of the Component Registry (based on annotations in the actual service implementation). Notice that the root of the REST service to which the mentioned paths are relative is https://catalog.clarin.eu/ds/ComponentRegistry/rest.
Further technical documentation of the Component Registry REST service can be found here (for the version currently under development)
