Difference between revisions of "Open Metadata Registry Step-By-Step Instruction"

From Metadata-Registry
Jump to: navigation, search
(Register an Element Set (Properties or Classes))
Line 65: Line 65:
  
 
[[Register Concepts]]
 
[[Register Concepts]]
 +
 +
==Register an Element Set (Properties or Classes)==
 +
 +
To Register Concepts, see:
 +
 +
In the context of these instructions, the term '''Element''' is used to refer to Properties or Classes when a distinction is unnecessary.  When only one or the other is addressed, for instance when instructions refer only to Properties or only to Classes the distinction will be made in the instruction.
 +
 +
We realize that the use of the term Element is not optimal, but until the software is revised we will continue to use it as needed in the instructions.
 +
 +
 +
===Step 3a: Register Property Vocabularies===
 +
 +
A set of properties or classes (also called here an Element Set or an Element Vocabulary) starts with a description of the set or vocabulary as a collective whole.  Once the Agent has been registered, a new vocabulary form can be invoked by clicking on the (Add) link showing after the '''Element Sets''' link on the right hand browse menu (note that the (Add) portion will not appear if the user is not logged in, and clicking on the Element Sets link will produce a link of already registered Element Sets). A basic template allowing a description of an Element Set will appear, divided into sections. In general, users should tab through the form to take best advantage of the Registry defaults.
 +
 +
[[Image:Register property set.jpg]]
 +
 +
'''DETAIL'''
 +
; Owner
 +
: User is provided with a drop-down list of all the agents for which the user is enabled to act.  The user must choose one to be the owner of the vocabulary.
 +
; Label
 +
: The label is a human-readable descriptive label for the element set as a whole. This text will be displayed in lists of element sets and should be optimized for a human reader, preferably without combined words or camel case.
 +
 +
'''NAMESPACE'''
 +
; Name
 +
: The user provides here unique token representing this particular element set. This will be used as the prefix identifying this URI in RDF or a qname in XML.  This name should be terse and contain no spaces.  Camel case is preferred.
 +
; URI
 +
: The URI assigned to this element set. By default this will be a concatenation of the Registry default domain and the element set Name. If another domain is desired for the Element Set and its individual properties, the desired namespace must be entered here manually, overriding the normal Registry default.  The namespace designated here will then become the default for the registration of individual properties later on in the workflow.
 +
 +
'''DOCUMENTATION'''
 +
; URL
 +
: A non-Registry URL that contains more information about this element set. This information is optional, but useful, if the vocabulary already has a presence on the web.
 +
; Note
 +
: A note about this element set.  This is optional, and may contain any information that may be relevant to users of the vocabulary.
 +
; Tags
 +
: In this space may be entered free text tags identifying communities of practice for which this element set is intended. At present, it is not possible to use these tags to search for related vocabularies, but this functionality will be added later.
 +
 +
'''DEFAULTS'''
 +
; Status
 +
: The drop down menu supplies a status that will serve as a default status for the properties of this element set as they are created. Once a vocabulary is registered, the statuses of individual properties must be changed individually--a change made to the vocabulary as a whole will not proliferate throughout the vocabulary.  This allows each property to be maintained separately as part of a vocabulary development process.
 +
; Language
 +
: The drop down menu supplies a default language for the properties of this element set as the properties are created.  When desired, individual property statements can be overridden with a non-default language, providing the capability for a multilingual property vocabulary.
 +
 +
When the desired parts of the form are filled in, the user should click on the SAVE button at the bottom of the page.
 +
 +
Elements will display in the order that they are entered.  The display can be changed to Alphabetical or Reverse Alphabetical by clicking the 'Label' link on the blue section above the list. When the sort is changed a small arrow indicating the direction of the sort will appear.
 +
 +
===Step 4a: Register Individual Properties===
 +
 +
Once the top level vocabulary description is saved, it will appear with several tabs above the description: '''Detail''' (which displays the full description for the element vocabulary), '''Elements''' (which displays in list form all the elements in the vocabulary), '''History''' (which gives a full history of changes made), and '''Maintainers''' (which gives a full list of those approved to manage the vocabulary, and their roles).  To add elements to the vocabulary, click on the '''Elements''' tab: if no elements are yet available in that vocabulary, the Registry will respond with that message, and below it will be a link to create an Element.  If that link is invoked, a form will be returned:
 +
 +
[[Image:RegisterIndividProp.jpg]]
 +
 +
The form includes the following:
 +
 +
; Type
 +
: A drop down menu allows the use of four types: class, subclass, property, and subproperty.
 +
; Label
 +
: This is a human-friendly label for this property and is required for every Property. The label should be optimized for human viewing and may have spaces.  Combined words and camel case are not recommended.
 +
; Name
 +
: This is a machine-compatible label for this property and is required for every Property. Names should begin with lower case for properties/subproperties and upper case for classes/subclasses, and should not include spaces. Combined words and camel case ARE recommended for names.
 +
; URI
 +
: The URI is generated by the system, based on the default supplied in the vocabulary description created earlier, but it may be overridden by the user.
 +
; Description
 +
: A description of the property or class.  In most cases the description should be a formal definition.
 +
; Comment
 +
: The comment may be an extension of the definition with examples of use, or a comment on the usage of the property in special cases.
 +
; Domain
 +
: Each property may be related to one or more classes by a ''has domain'' relationship. Where it is stated that a property has such a relationship with a class and the property is part of a property/value pair, it follows that the described resource is an instance of that class. (From the [[http://dublincore.org/documents/abstract-model/ Dublin Core Abstract Model]].)
 +
; Range
 +
: Each property may be related to one or more classes by a ''has range'' relationship. Where it is stated that a property has such a relationship with a class and the property is part of a property/value pair, it follows that the value is an instance of that class. [[http://dublincore.org/documents/abstract-model/ Dublin Core Abstract Model]].)
 +
; Status
 +
: This is the overall status of this Element. Individual elements of this property may have a different status.
 +
; Language
 +
: This is the default language for all statements of this element. If languages other than the default are desired for particular statements, the default language can be overridden.
 +
; Note
 +
: Notes for the application of particular statements or to reflect sources of definitions or other relevant human-readable purposes can be added here.
 +
 +
Additional classes or properties needed for the element vocabulary can be added by repeating the process.
 +
 +
Subclass and subproperty relationships should be added after the Classes and Properties have been completed.  The Registry expects that when an element is a subclass or subproperty, the higher level is already present. When describing a subclass or subproperty, a drop down list presents all classes or properties available in the vocabulary, ensuring that only appropriate relationships are made, and that relationships are reciprocal.
 +
 +
===Step 5a: Editing or Extending Existing Elements/Properties===
 +
 +
When a set of elements/properties are initially registered, a number of maintenance actions are available to manage the vocabulary.  Data can be edited (corrections, additions of text to definitions, deletions, etc.) or extended (statements added, relationships added).
 +
 +
====Editing/Maintaining Existing Elements/Properties====
 +
 +
Starting with a list of existing elements, either click the edit button to the right of the element, or go to the detail for the element itself by clicking on the name or URL from the list, and choosing the edit button from the bottom of the display. (If the edit button does not appear on the list or the detail display for the property, either the user is not signed in, or the user is not authorized to edit this particular element set.)
 +
 +
 +
[[Image:ElementList.jpg]]
 +
 +
 +
Once the edit screen is displayed, any visible data can be modified and any empty text boxes can be filled in.  Note that when displaying the detail for a class or property, information on subclass or subproperty relationships does not display in this view and cannot be added or edited from the detail edit screen.  See the instructions for Extending Existing Elements/Properties to add or edit those relationships.
 +
 +
[[Image:ElementDetailEdit.jpg]]
 +
 +
====Extending Existing Elements/Properties====
 +
 +
An alternate approach to editing, which allows access to all the properties at a statement level (including subclass and subproperty relationships), starts from the list of Elements. Clicking on the element to be edited, and, when the detail is displayed, clicking on the Statements tab, provides a list of all property statements, with available actions in the right hand column.
 +
 +
 +
[[Image:ElementStatementDisplay.jpg]]
 +
 +
 +
From this view, the actions available for each statement are visible in the right hand column. Some statements can be edited, others can be deleted, and the defaults (which show no actions in the right hand column) show no actions; they must be changed using the detail edit screen shown above. At the bottom of the display, a button to invoke a form to add new statements can be clicked. This is one method available to add new hasSubproperty relationships from the property itself (the other method is to add a new 'parent' property to a subproperty). Because element properties can have multiple relationships, care should be taken to ensure that reciprocals are correct. Because existing relationships cannot be edited directly via the detail editing screen, relationships that require change must be deleted first, then added back in their changed version.
 +
 +
[[Image:CreatingNewStatement.jpg]]
 +
 +
 +
Adding Property statements for elements identified as classes is more limited, because classes must have 'one-to-one' hierarchies.  Therefore, the drop down list for element properties includes:
 +
 +
* label
 +
* description
 +
* comment
 +
* subpropertyOf
 +
* note
 +
* domain
 +
* range
 +
 +
While the drop down list for elements identified as classes includes:
 +
 +
* label
 +
* description
 +
* comment
 +
* note

Revision as of 14:01, 24 September 2010

The instructions below are intended to assist users to begin working effectively on the [Open Metadata Registry]. The same instructions apply for users of the [Open Metadata Registry Sandbox].

User Management Step-by-Step

Register an Individual

On the upper right hand corner of every Registry page is a tab, which, for a user not signed in says:

* sign in/register | about

When clicked on sign in/register, the following page appears:

UserRegStep1sm.jpg

A new user must register by clicking the box that says click here to create a new account which allows the user to fill in four boxes, all mandatory:

  • a login name
  • a password
  • a password confirmation
  • an email address

The email address is used only for password retrieval, when a user forgets his or her password, is used for no other purpose, nor shared with any other service or individual.


UserRegStep2sm.jpg

Results: A new user account is created. The user should note the login name and password, as well as the email address entered at the time of new account registration.

Register an Agent

Now that you are logged in, you can add a resource owner. Every schema or vocabulary must be owned by a resource owning agent, which can be registered as either an individual or an organization.

To register an agent, click on the (Add) link next to Resource Owners in the Browse box on the right side of the page and fill out the resulting form. Owner Name and Email are required fields. As with user registration, email addresses are kept private. When you register an agent, you become the registrar of that agent and an Agent Administrator for that organization or individual. Other users and administrators can be added later.

Agent Registration Page


DEFINITIONS:


An Agent Administrator is defined as: "One or more persons authorized to maintain one or more Agent records." This Agent Administrator is automatically the Vocabulary Administrator and Maintainer for all element sets or vocabularies owned by that Agent, and authorized to:

  • Edit/Delete Agent Records (an Agent can only be deleted by an Admin if there are no associated Vocabularies)
  • Designate other registered users as:
    • Agent Administrators for that Agent
    • Agent Contacts for that Agent (can receive notifications but has no explicit role in vocabulary development)
    • Vocabulary Administrator for individual Vocabularies owned by that Agent
    • Vocabulary Maintainers for individual Vocabularies owned by that Agent

A Vocabulary Administrator is defined as: "One or more persons responsible for editorial functions related to one or more submitted vocabularies. The user who registers a Vocabulary becomes the Administrator for that Vocabulary." The Vocabulary Administrator is authorized to:

  • Act as Vocabulary Maintainer
  • Designate other registered users as Vocabulary Maintainers

A Vocabulary Maintainer is defined as: "A registered user designated as responsible for maintaining a Vocabulary." The Vocabulary Maintainer is authorized to edit vocabulary properties and concepts.

Add Another Agent Administrator

Add Another Vocabulary Administrator

Add Another Maintainer



Register Properties

Register Concepts

Register an Element Set (Properties or Classes)

To Register Concepts, see:

In the context of these instructions, the term Element is used to refer to Properties or Classes when a distinction is unnecessary. When only one or the other is addressed, for instance when instructions refer only to Properties or only to Classes the distinction will be made in the instruction.

We realize that the use of the term Element is not optimal, but until the software is revised we will continue to use it as needed in the instructions.


Step 3a: Register Property Vocabularies

A set of properties or classes (also called here an Element Set or an Element Vocabulary) starts with a description of the set or vocabulary as a collective whole. Once the Agent has been registered, a new vocabulary form can be invoked by clicking on the (Add) link showing after the Element Sets link on the right hand browse menu (note that the (Add) portion will not appear if the user is not logged in, and clicking on the Element Sets link will produce a link of already registered Element Sets). A basic template allowing a description of an Element Set will appear, divided into sections. In general, users should tab through the form to take best advantage of the Registry defaults.

Register property set.jpg

DETAIL

Owner
User is provided with a drop-down list of all the agents for which the user is enabled to act. The user must choose one to be the owner of the vocabulary.
Label
The label is a human-readable descriptive label for the element set as a whole. This text will be displayed in lists of element sets and should be optimized for a human reader, preferably without combined words or camel case.

NAMESPACE

Name
The user provides here unique token representing this particular element set. This will be used as the prefix identifying this URI in RDF or a qname in XML. This name should be terse and contain no spaces. Camel case is preferred.
URI
The URI assigned to this element set. By default this will be a concatenation of the Registry default domain and the element set Name. If another domain is desired for the Element Set and its individual properties, the desired namespace must be entered here manually, overriding the normal Registry default. The namespace designated here will then become the default for the registration of individual properties later on in the workflow.

DOCUMENTATION

URL
A non-Registry URL that contains more information about this element set. This information is optional, but useful, if the vocabulary already has a presence on the web.
Note
A note about this element set. This is optional, and may contain any information that may be relevant to users of the vocabulary.
Tags
In this space may be entered free text tags identifying communities of practice for which this element set is intended. At present, it is not possible to use these tags to search for related vocabularies, but this functionality will be added later.

DEFAULTS

Status
The drop down menu supplies a status that will serve as a default status for the properties of this element set as they are created. Once a vocabulary is registered, the statuses of individual properties must be changed individually--a change made to the vocabulary as a whole will not proliferate throughout the vocabulary. This allows each property to be maintained separately as part of a vocabulary development process.
Language
The drop down menu supplies a default language for the properties of this element set as the properties are created. When desired, individual property statements can be overridden with a non-default language, providing the capability for a multilingual property vocabulary.

When the desired parts of the form are filled in, the user should click on the SAVE button at the bottom of the page.

Elements will display in the order that they are entered. The display can be changed to Alphabetical or Reverse Alphabetical by clicking the 'Label' link on the blue section above the list. When the sort is changed a small arrow indicating the direction of the sort will appear.

Step 4a: Register Individual Properties

Once the top level vocabulary description is saved, it will appear with several tabs above the description: Detail (which displays the full description for the element vocabulary), Elements (which displays in list form all the elements in the vocabulary), History (which gives a full history of changes made), and Maintainers (which gives a full list of those approved to manage the vocabulary, and their roles). To add elements to the vocabulary, click on the Elements tab: if no elements are yet available in that vocabulary, the Registry will respond with that message, and below it will be a link to create an Element. If that link is invoked, a form will be returned:

RegisterIndividProp.jpg

The form includes the following:

Type
A drop down menu allows the use of four types: class, subclass, property, and subproperty.
Label
This is a human-friendly label for this property and is required for every Property. The label should be optimized for human viewing and may have spaces. Combined words and camel case are not recommended.
Name
This is a machine-compatible label for this property and is required for every Property. Names should begin with lower case for properties/subproperties and upper case for classes/subclasses, and should not include spaces. Combined words and camel case ARE recommended for names.
URI
The URI is generated by the system, based on the default supplied in the vocabulary description created earlier, but it may be overridden by the user.
Description
A description of the property or class. In most cases the description should be a formal definition.
Comment
The comment may be an extension of the definition with examples of use, or a comment on the usage of the property in special cases.
Domain
Each property may be related to one or more classes by a has domain relationship. Where it is stated that a property has such a relationship with a class and the property is part of a property/value pair, it follows that the described resource is an instance of that class. (From the [Dublin Core Abstract Model].)
Range
Each property may be related to one or more classes by a has range relationship. Where it is stated that a property has such a relationship with a class and the property is part of a property/value pair, it follows that the value is an instance of that class. [Dublin Core Abstract Model].)
Status
This is the overall status of this Element. Individual elements of this property may have a different status.
Language
This is the default language for all statements of this element. If languages other than the default are desired for particular statements, the default language can be overridden.
Note
Notes for the application of particular statements or to reflect sources of definitions or other relevant human-readable purposes can be added here.

Additional classes or properties needed for the element vocabulary can be added by repeating the process.

Subclass and subproperty relationships should be added after the Classes and Properties have been completed. The Registry expects that when an element is a subclass or subproperty, the higher level is already present. When describing a subclass or subproperty, a drop down list presents all classes or properties available in the vocabulary, ensuring that only appropriate relationships are made, and that relationships are reciprocal.

Step 5a: Editing or Extending Existing Elements/Properties

When a set of elements/properties are initially registered, a number of maintenance actions are available to manage the vocabulary. Data can be edited (corrections, additions of text to definitions, deletions, etc.) or extended (statements added, relationships added).

Editing/Maintaining Existing Elements/Properties

Starting with a list of existing elements, either click the edit button to the right of the element, or go to the detail for the element itself by clicking on the name or URL from the list, and choosing the edit button from the bottom of the display. (If the edit button does not appear on the list or the detail display for the property, either the user is not signed in, or the user is not authorized to edit this particular element set.)


ElementList.jpg


Once the edit screen is displayed, any visible data can be modified and any empty text boxes can be filled in. Note that when displaying the detail for a class or property, information on subclass or subproperty relationships does not display in this view and cannot be added or edited from the detail edit screen. See the instructions for Extending Existing Elements/Properties to add or edit those relationships.

ElementDetailEdit.jpg

Extending Existing Elements/Properties

An alternate approach to editing, which allows access to all the properties at a statement level (including subclass and subproperty relationships), starts from the list of Elements. Clicking on the element to be edited, and, when the detail is displayed, clicking on the Statements tab, provides a list of all property statements, with available actions in the right hand column.


ElementStatementDisplay.jpg


From this view, the actions available for each statement are visible in the right hand column. Some statements can be edited, others can be deleted, and the defaults (which show no actions in the right hand column) show no actions; they must be changed using the detail edit screen shown above. At the bottom of the display, a button to invoke a form to add new statements can be clicked. This is one method available to add new hasSubproperty relationships from the property itself (the other method is to add a new 'parent' property to a subproperty). Because element properties can have multiple relationships, care should be taken to ensure that reciprocals are correct. Because existing relationships cannot be edited directly via the detail editing screen, relationships that require change must be deleted first, then added back in their changed version.

CreatingNewStatement.jpg


Adding Property statements for elements identified as classes is more limited, because classes must have 'one-to-one' hierarchies. Therefore, the drop down list for element properties includes:

  • label
  • description
  • comment
  • subpropertyOf
  • note
  • domain
  • range

While the drop down list for elements identified as classes includes:

  • label
  • description
  • comment
  • note