Metadictionary guidelines


What YAMZ is for

YAMZ is an open vocabulary of metadata terms from all domains and from all parts of metadata speech. You are free to use it to search for, use, share, and reference term definitions, as well as to create and edit your own terms, and comment on others' terms. Those freedoms are granted provided you take responsibility for your edits, and in using YAMZ you support a civil environment, do not violate copyright or other laws, and do no harm to its technical infrastructure.

What it is not

YAMZ is not

Term parts

Terms consist of several parts: a term string, definition, unique concept identifier, example section, and comments section. Term definitions should be in English. Newlines (line breaks) are preserved on display.

Term string

A term string (or label) is one or more words that communicate the concept being defined.

Term definition

With the term string established, your term definition should consist of two main parts (see [1] and [2]):

In particular, a definition will usually start with "A", "An", or "The". As an example, for the term "water",

         A clear liquid made up of hydrogen and oxygen molecules.

the class is "clear liquid". If the term string is an acronym, expand it inside parentheses (using capital letters to delineate the acronym), and insert the expansion at the very beginning of the definition. As an example, for the term "ABC",

         (Apple Bovine Cooler) An ointment for treating overheated cows.

Examples and comments

Text in the examples and comments can use all of the references described below. As in definitions, newlines (line breaks) are preserved on display.

Referencing

In term definitions, examples, and comments you can create actionable links to words and concepts defined in YAMZ and elsewhere.

Term references

When you create or edit text, a construct like

         #{t: multi-word term string}
or
         &term

refers to a term (the second is a shorthand for when the term string consists of just one word). After you save your editing, YAMZ converts this to a standard internal form:

         #{t: term string | concept identifier}

On display this reference will look like an ordinary link to the named term, and when your mouse hovers over it that term's definition should appear. Term references can be used liberally inside definitions, examples, and comments.

Tag references

Tag references are like term references, but are meant to appear only in definitions of terms being tagged. A group of one or more tags (no commas between them) is to be separated from the end of the definition by a single newline. While terms are meant to be understandable without tags, a tag definition can explain some context (intent, origin, sub-community, working group, etc.) for a set of terms. On display, a tag reference looks like a link embedded in a little tile. When you hover over it a definition appears, and when you click on it YAMZ performs a search for all terms bearing that tag.

                  #tag

On editing, you can enter a tag by putting a '#' in front of it or using the internal form to which it will be converted. The internal form (in the current software release) is slightly different from the displayed form to make it more unique as a search string. For example, the tag "#foo" becomes

         #{g: xqfoo | hNNNN}

where "hNNNN" is the persistent concept identifier assigned to it. In a list of terms or in its own definition, a tag's term string appears with a '#' in front of it.

External links

If needed, you can also add general links to external content using

         #{k: link string | URL (web address)}
or
         #{k: URL (web address)}

These links are not to be used in the definition proper, but you can enter them in a separate note, such as,

         Note: context for this term's use may be found at #{k: example.com/xyzterms}.

Defining values or substructure

You can list the values or elements that a given term takes on by adding them to the end of its definition (but before any tags). When a term takes elements (has substructure), first start the definition with something like "A structured statement defining ...", followed by distinguishing characteristics. Then, at the end of the definition (but before any tags), add a newline, "Elements: ", and a list of elements. For example, a definition for "collector" might be entered like this:

         A person who collects things of a certain type.
         Elements: &age, &height, &weight
         #geology #botany

A term may have either an element list, a value list, or neither, but not both. A value list should also be placed at the end, as in:

         An indicator of whether the thing is difficult.
         Values: &yes, &no, &maybe
         #finance

Updated

Document last updated 29 April 2016 by jak.