---

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

• ... an encyclopedia. A definition is approximately one sentence, not an essay.
• ... an ontology, thesaurus, controlled vocabulary, nor other knowledge system that defines a set of concepts to represent a subject domain. YAMZ does not compete with any existing or prospective metadata ontology, whether it defines the pick list naming the four color choices in your app, the ten table column headings for recording state-mandated water sample observations, or the set of sixty thousand disease codes specified in an international standard. Instead it provides a pool of candidate terms from which ontologies, defined elsewhere, can pick and choose.
• ... a replacement for <name your field's well-established vocabulary here>. Each YAMZ term is a tiny, free-standing specification – a kind of "nano-standard". For example, every academic domain maintains ontologies, usually as documents that specify which terms are required, optional, broader, narrow, etc. in a given domain. YAMZ offers to ease that burden for the unavoidable work of maintaining term definitions, leaving for others the work of choosing (and linking to) relevant terms and documenting the rules that apply in a given context.
• ... a regular dictionary. While its terms resemble natural language terms, they are actually formal jargon often inspired by natural language. YAMZ should only contain terms that directly support machine-readable descriptions and the metadictionary itself.
• ... a bunch of sub-vocabularies. If your working group in the XYZ domain wants its own version of "thingummy", resist the temptation to create "XYZ_thingummy", or similarly making the domain part of the term string. Instead consider creating "thingummy" and annotating its definition with the tag reference "#XYZ" so that your group can narrow its focus to #XYZ terms as needed. It is a feature that YAMZ is ultimately one large, flat namespace with no domain borders.

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.

• A term string should contain only letters, digits, hyphens, space, and underscores. If the string has more than one word, exactly one space separates each word, and it cannot begin or end with a space or hyphen. (These restrictions make it easier to express terms precisely and in a variety of metadata formats.)
• Although definitions are in English, the term string may be derived from any natural language. Whatever its origin, consideration should be given to making it easy to spell, pronounce, and use in English sentences.
• Prefer creating a term in the singular form, and in such a way that the plural form need not also be defined. This approach is often easier, clearer, and more flexible than creating a term in the plural form.
• A term string need not be unique in the metadictionary, but consider carefully if you want to create a new term with an existing string. Either way, each term gets a unique and persistent concept identifier when it is first created. Two terms with the same term string may be meant to compete with or to complement each other.

Term definition

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

• the class to which the named thing belongs, followed by
• differentiating characteristics that distinguish it from others of its class.

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.