A MoinMoin Wiki Syntax for Description Set Profiles

Creator:	Fredrik Enoksson Knowmania HB, Sweden
Date Issued:	2008-10-06
Identifier:	http://dublincore.org/specifications/dublin-core/dsp-wiki-syntax/2008-10-06/
Replaces:	Not applicable
Is Replaced By:	Not applicable
Latest Version:	http://dublincore.org/specifications/dublin-core/dsp-wiki-syntax/
Status of Document:	This is a DCMI Working Draft
Description of Document:	This document describes a Wiki syntax for a Description Set Profile as defined in the DCMI Working Draft "Description Set Profiles: A constraint language for Dublin Core™ Application Profiles" of March 2008.

Table of contents

1. About this document
2. Design and description of the wiki syntax
3. Usage example
4. References

---

1. About this document

This document describes a MoinMoin wiki syntax for a Description Set Profile as defined in the DCMI Working Draft "Description Set Profiles: A constraint language for Dublin Core™ Application Profiles" of March 2008 [DC-DSP], which in turn is based on the DCMI Abstract Model [ABSTRACT-MODEL]. It is recommended to have some understanding of the concepts of Description Set Profile (abbreviated DSP in the rest of this document) before reading this document.

A DSP is a way of describing structural constraints on a description set and is not directly intended for human consumption. However, with the wiki syntax for DSPs described here, it is possible to mix normal wiki syntax with DSP-specific wiki syntax in order to document an Application Profile. This means that from the same source it is possible to create:

• A Dublin Core™ Application Profile that contains wiki syntax for a Description Set Profile, but is rendered as an HTML page for human consumption
• A formal serialization in XML for the same Description Set Profile, used for machine (computer) consumption.

The DSP wiki syntax and its use is described in this document. The syntax has been implemented for the MoinMoin wiki engine [MOINMOIN] with the help of an extension to the wiki engine. The extension to the MoinMoin wiki engine for rendering HTML pages was done by adding a parser extension. The parser, named "DSP", is called from within a wiki page using the following syntax:

 {{{#!DSP
  /* Here the specific Description Set Profile wiki syntax to be parsed */
 }} }

Anything above and below the three curly brackets is parsed according to the normal MoinMoin wiki syntax. For more information about parsers in MoinMoin wikis, see [MOINMOIN-PARSERS]. In order to generate an XML representation of a DSP, a so-called "action extension" for the MoinMoin wiki has been implemented. How this is used to retrieve the XML is described below.

Source code for the MoinMoin software is available at [WIKI-SYNTAX-SOFTWARE]. Slide decks about the wiki syntax are available at [EPRINTS] and [WIKI-SYNTAX].

2. Design and description of the wiki syntax

The "Description Set Profile" specification [DC-DSP] uses the notion of ''constraints'' and ''templates'' to describe the structure of a Description Set. There are two levels of templates in a DSP:

• Description templates, which contain the statement templates that apply to a single kind of description as well as constraints on the described resource
• Statement templates, which contain all of the constraints on the property, value strings, vocabulary encoding schemes, etcetera, that apply to a single kind of statement.

These templates, moreover, consist of constraints that are used to limit the structure. The relations between the templates and the constraints are depicted in the following figure:

The hierarchical structure of the DSP is reused in the syntax in such a way that, when a template or constraint has been declared, it is a part of the first declared template above that it can be a part of according to the hierarchy (see figure above). For example, if a Description Template is declared, and this is followed by a Statement Template, this Statement Template is seen as a part of that Description Template.

In the syntax, four parts may be expressed on their own:

• Description template, which directly corresponds to the description above.
• Statement Template, which also corresponds to the description above. However, a Statement can be either a_Literal Statement Template_ or Non-Literal Statement Template.
• Non-Literal Value Constraint, which corresponds to the value constraints for a Non-Literal Statement Template
• Literal Value Constraint, which corresponds to the value constraints for a Literal Statement Template

The following empty template serves as an example of the structure:

  {{{#!DSP

 MoinMoin-wiki-format text will be placed over the template below when rendered.
 DT=(ID="" RC=[] min="" max="" standalone="yes|no|both")

 MoinMoin-wiki-format text will be placed over the template below when rendered.
 ST=(ID="" min="" max="" type="" PC=(""|{,})) 
    
 NLC=(description="" [] 
         VURIConstraint=( occurrence="mandatory|optional|disallowed" {,})
         VESConstraint=( occurrence="mandatory|optional|disallowed" {,})
         VStringConstraint=(min="" max="" {[value="" lang="" SES=""], [...]} 
                           LangC=(occurrence="mandatory|optional|disallowed" {,})
                           SESConstraint=(occurrence="mandatory|optional|disallowed" {,})
                          )
        )

 ST=(ID="" min="" max="" type="" PC=(""|{,})) 

 LC=({[value="" lang="" SES=""], [...]} 
        LangC=(occurrence="mandatory|optional|disallowed" {,})
        SESConstraint=(occurrence="mandatory|optional|disallowed" {,})
       )
 )
 ST=(...)
 DT=(...)
 ST=(...)
 ST=(...)
 }} }

In between each expressed Description Template (DT), Statement Template (ST), NonLiteral Constraint (NLC) and Literal Constraint (LC), the normal MoinMoin wiki syntax can be used.

When something in the format can have one and only one value, it is placed between quotation marks; see, for example, "identifier" in the Description Template below. If a set of choices is to be expressed, curly brackets are used.

Expressing the different parts of a DSP

As previously stated and seen in the template above, the four basic parts are expressed with:

• DT for a Description Template
• ST for a Statement Template
• NLC for a NonLiteral Value Constraint
• LC for a Literal Value Constraint

Each one of these expressions must start on a new line. As can also be seen from the template above, it is possible to express normal wiki syntax in between these DSP-wiki syntax expressions. This text also needs to start on a new line so as not to be mixed with the DSP wiki syntax. This text surrounds the parts of a DSP in the resulting HTML but will be ignored when creating the XML for the DSP. This means that the HTML that is created to document an ST, for example, can be embedded into a table or some similar HTML construct. If any of the wiki-syntax keywords (DT, ST, NLC or LC) need to be used at the start of a new line in the normal wiki syntax, precede the keywords with a backslash (""); the backslash will be ignored in the resulting HTML.

Expressing a Description Template

Start a new line with "DT" followed by "=" and a starting left parenthesis; in order to close the declaration a right parenthesis is needed. The expression inside the parenthesis is allowed to span over more than one line. Expressed inside the parenthesis are the attributes:

• Identifier, use the keyword "ID" followed by a "=" and a valid XML ID String inside quotation marks. Example expression:
  ID="Person"
• Resource Class Membership Constraint, is expressed in a list with the keyword RC followed by "=" and a list with the URIs inside angle brackets separated by a comma and a blankspace. Example expression:
  RC=[http://www.anyuri.net/someResourceConstraint, http://www.anyuri.net/someOtherResourceConstraint]
• Minimum occurrence constraint, use the keyword "min" followed by a "=" with a non negative integer inside quotation marks as the value. Example expression:
  min="1"
• Maximum occurrence constraint, use the keyword "max" followed by a "=" with a non negative integer inside quotation marks as the value. Example expression:
  max="1"
• Standalone, use the keyword standalone followed by a "=" with one of the following strings as possible values: "yes", "no" or "both" inside quotation marks. Example expression:
  standalone="yes"

For a more detailed description of these attributes see Section 5 in [DC-DSP]; conditions for the attributes and possible and default values are described here in more detail.

The attributes of a Description Template can be declared inside the parenthesis in any order with blankspace as separator. If none of these are declared, the parenthesis should be left empty. The Statement Templates that belong to a Description Template follow afterwards until a new Description Template is declared. Example of a declaration of a Description Template:
DT=(ID="Person" standalone="yes" RC=[http://www.anyuri.net/someResourceConstraint, http://www.anyuri.net/someOtherResourceConstraint] min="1" max="1")

Expressing a Statement Template

A Statement Template is expressed in a similar way to the Description Template, starting on a new line with "ST=" followed by a left parenthesis and then closed by a right parenthesis. The expression inside the parenthesis may span over more than one line and the attributes inside are separated with a blankspace and may be in any order. Expressed inside the parenthesis are the attributes:

• Property list constraint or Sub-property constraint. To declare this, start with the keyword "PC" followed by "=" and only one of the following:
  • one URI within surrounding quotation marks to declare a Sub Property Constraint. Example expression:
    PC="http://purl.org/dc/elements/1.1/creator"
  • a set of URIs, by using curly braces with comma and a blankspace as a separator to declare a Property List Constraint. Example expression:
    PC={http://purl.org/dc/elements/1.1/creator, http://xmlns.com/foaf/0.1/name}
• Minimum occurrence constraint, use the keyword "min" followed by a "=" with a non negative integer inside quotation marks as the value. Example expression:
  min="1"
• Maximum occurrence constraint, use the keyword "max" followed by a "=" with a non negative integer, larger than the minimum occurrence constraint, inside quotation marks as the value. Example expression:
  max="1"
• Type Constraint. This is declared with the keyword "type" followed by a "=" and then either "''Literal''" or "''NonLiteral''" inside quotation marks. The value of this attribute decides if a Statement Template is of type Literal Statement Template or Non-literal Statement Template. If the attribute is not declared it will default to be both and no further value constraints can be made according to the description of DSP Statement Template type. Example:
  type="literal"

For a more detailed description of these attributes, see the section about Statement Template in the draft DSP specification, where conditions for the attributes and possible and default values are described in more detail. An example:
ST=(min="1" max="10" PC="http://purl.org/dc/elements/1.1/creator" type="literal")

A Statement Template can be of either the type Literal Statement Template and have a Literal Value Constraint or of the type Non-literal Statement Template and have a Non-literal Value Constraint. These constraints correspond to the ''Literal value surrogates'' and ''Non-literal value surrogates'' respectively in the DCMI Abstract Model [ABSTRACT-MODEL]. To express constraints on a Statement Template they will be declared under the Statement Template to which they belong and must start on a new line.

Expressing a literal value constraint

When a Statement Template has the type constraint set to Literal, it is possible to further constrain the possible values by declaring a Literal Value Constraint. To express this constraint the keyword "LC" followed by a "=" and a left parenthesis is used; at the end, a right parenthesis is used to close the expression. The declaration of a Literal value constraint must start on a new line. Inside the parenthesis the following parts can be expressed:

• Constraints on Syntax Encoding Scheme. A set of such constraints are declared with the keyword "SESConstraint" followed by a "=" and a left parenthesis, with a right parenthesis to close the expression. Inside the parenthesis the following can be declared:
  • Syntax Encoding Scheme constraint. The occurrence of a Syntax Encoding Scheme constraint is declared with the keyword "occurrence", with the possible values ''mandatory'', ''optional'' or ''disallowed''. If this part is not declared it will by default be "optional". Example syntax:
    occurrence="mandatory"
  • Syntax Encoding Scheme list constraint. This declares the syntax encoding schemes allowed for the literal. These are declared as a set of options (in the form of a URI) inside curly brackets, separated by a comma and a blankspace. Example syntax:
    {http://purl.org/dc/terms/URI}
• Literal list constraint. Literals allowed as values are declared as a set inside curly braces. Entries inside the curly braces are declared inside square brackets and are separated with a comma and a blank space. Inside each entry a value is declared with the keyword "value" followed by a "=" and the value as a string. After the value either a language or a Syntax Encoding Scheme can be declared with the keywords "lang" or "SES" used respectively followed by a "=" and the value. For the language, ISO language tags are valid values; for Syntax Encoding Schemes, a URI is a valid value. Example expression:
  {[value="A simple String" lang="en"], [...]}
• Constraints on the language, are declared by using the keyword "LangC" followed by "=" and a pair of parenthesis that inside contain:
  • Literal language constraint, that decides the occurrence of a language constraint, starts with the keyword "occurence", which has the possible values ''mandatory'', ''optional'' or ''disallowed''. If this part is not declared it will by default be "optional". Example syntax:
    occurrence="mandatory"
  • Literal language list constraint is declared as a set of languages choices expressed inside curly braces with comma and a blankspace as a separator. If no constraint is to be given this part can be left out. Example expression:
    {en, sv, es}

For a more detailed description about the attributes for Literal Value Constraints, see the corresponding section in the draft DSP specification, where conditions on the attributes and possible and default values are described in more detail.

• Example 1, how to express an LC:
  LC=( {[value="A typical string" lang="en"]})
• Example 2, how to express an LC with languageConstraint:
  LC=( LangC=(occurrence="optional" {en, sv, es}))

Expressing a non-literal Value Constraint

When a Statement Template has a type constraint set to NonLiteral it is possible to further constrain the possible values. To declare this constraint, start on a new line and use the keyword "NLC" followed by a "=" and a left parenthesis; at the end of the NLC a right parenthesis is used to close the expression. The expression is allowed to span more than one line. Inside the parenthesis the following parts can be expressed:

• Description template reference. This is a reference to a description template that may be used to describe the value. Example expression:
  description="ref"
• Class membership constraint. Classes of which the value may be an instance (in the form of a URI) are declared inside curly brackets with comma and a blankspace as a separator. Example expression:
  {http://www.example.com/exampleURI1, ...}
• Value URI Constraint, are expressed with the keyword "VURIConstraint" with a following "=" followed by a left parenthesis and it is closed with a right one. Inside two arguments are provided:
  • Value URI list constraint: URIs that are allowed as value URIs. These are declared as a set and expressed inside curly braces with comma and a blankspace as a separator. Example expression:
    {http://www.example.com/uri1, http://www.example.com/uri2}
  • Value URI occurrence constraint, that have the possible values of ''mandatory'', ''optional'' or ''disallowed''. Example syntax:
    occurrence="mandatory"
  • Example of the ValueURIConstraint construct:
    VURIConstraint=( occurrence="mandatory" {http://www.example.com/uri1, http://www.example.com/uri2})
• Vocabulary encoding scheme constraint. This is used in cases where a vocabulary encoding scheme must be given. This is declared almost the same way as ValueURIConstraint, but with the keyword "VESConstraint" used instead. Example expression:
  VESConstraint=( occurrence="mandatory" {http://www.example.com/uri3, http://www.example.com/uri4})
• Value String Constraint. This is declared by using the keyword "VStringConstraint" and with its argument inside left and right parenthesis. Inside the following are declared:
  • Minimum occurrence constraint, use the keyword "min" followed by a "=" with a non zero Integer inside quotation marks as the value. Example expression:
    min="1"
  • Maximum occurrence constraint, use the keyword "max" followed by a "=" with a non zero Integer inside quotation marks as the value. Example expression:
    max="1"
  • Apart from the ''maximum'' and ''minimum occurrence constraint'' the rest of the declaration of a Value String Constraint are done the same way as a Literal Constraint.

For a more detailed description about the attributes for Non-Literal Value Constraints see the corresponding section in the draft DSP specification, where conditions on the attributes and possible and default values are described in more detail.

• Example 1, how to declare an NLC:
  NLC=(description="ref" {http://www.example.com/exampleURI1})
• Example 2 of an NLC with ValueURIConstraint:
  NLC=(description="ref" VURIConstraint=( occurrence="mandatory" {http://www.example.com/uri1, http://www.example.com/uri2}))
• Example 3 of an NLC with VESConstraint:
  NLC=(description="ref" VESConstraint=( occurrence="mandatory" {http://www.example.com/uri3, http://www.example.com/uri4}))
• Example 4 of an NLC with ValueStringConstraint:
  NLC=(description="ref" VStringConstraint=(min="1" max="1" {[value="someFormat:Format2" lang="en" SES="http://www.example.org/someSyntaxEncodingScheme"]}

Examples

The DC-XML examples in the draft Description Set Profile specification [DC-DSP], Section 9, in wiki format:

DC Example:

{{{#!DSP 
DT=()
ST=(PC={http://purl.org/dc/terms/title})
ST=(PC={http://purl.org/dc/terms/description})
}}}

FOAF Example:

{{{#!DSP
DT=( ID="Person" RC=[http://xmlns.com/foaf/0.1/Person] min=1 max=1 )
ST=( min=1 max=1 type="literal" PC={http://xmlns.com/foaf/0.1/name} ) 
ST=( type="literal" PC={http://xmlns.com/foaf/0.1/knows} )
NLC=({http://xmlns.com/foaf/0.1/Person})
}} }

3. Usage example

This syntax has been implemented as an extension to the MoinMoin wiki engine. The following example shows how the syntax will be rendered in HTML and in the resulting XML.

Example of the syntax

With the extension to the MoinMoin wiki engine installed, the syntax described in this document can be used in a wiki page. When the extension is executed, the wiki document will be parsed as a Description Set Profile as follows:

{{{#!DSP
== Description template ==
DT=(min="1" max="1" standalone="yes")

=== Title ===
----
ST=(type="literal" PC={http://purl.org/dc/terms/title})
|| Definition || A name given to the resource. ||
LC=(LangC=(occurrence="optional") SESConstraint=(occurrence="disallowed") )

=== Creator ===
----
ST=(type="nonliteral" PC={http://purl.org/dc/terms/creator})
|| Definition || An entity primarily responsible for making the resource. ||
|| Comment || Examples of a Creator include a person, an organization, or a service. 
Typically, the name of a Creator should be used to indicate the entity. ||
NLC=( VURIConstraint=( occurrence="disallowed") VESConstraint=( occurrence="disallowed" ) VStringConstraint=(max="1" 
LangC=(occurrence="optional") SESConstraint=(occurrence="disallowed") ) )
}}}

The resulting HTML:

The example of the syntax above renders in HTML as a readable Web page.

The resulting XML:

An action extension was implemented in order to create XML from the DSP wiki syntax. The XML for a DSP can be retrieved by adding "?action=DSP2XML" at the end of the URL of the page that contains a DSP, as inhttp://dublincore.org/architecturewiki/EprintsApplicationProfile?action=DSP2XML. Running the action will retrieve XML such as:

 <DescriptionSetTemplate>

   <DescriptionTemplate maxOccur="1" minOccur="1">

     <StatementTemplate type="literal">
       <Property>http://purl.org/dc/terms/title</Property>

       <LiteralConstraint>
         <SyntaxEncodingSchemeOccurrence>"disallowed"</SyntaxEncodingSchemeOccurrence>
         <LanguageOccurrence>"optional"</LanguageOccurrence>
       </LiteralConstraint>

     </StatementTemplate>

     <StatementTemplate type="nonliteral">
       <Property>http://purl.org/dc/terms/creator</Property>

       <NonliteralConstraint>
         <ValueURIOccurrence>disallowed</ValueURIOccurrence>
         <VocabularyEncodingSchemeOccurrence>disallowed</VocabularyEncodingSchemeOccurrence>
	 <ValueStringConstraint maxOccur="1">
           <SyntaxEncodingSchemeOccurrence>"disallowed"</SyntaxEncodingSchemeOccurrence>
           <LanguageOccurrence>"optional"</LanguageOccurrence>
         </ValueStringConstraint>
       </NonliteralConstraint>

     </StatementTemplate>

   </DescriptionTemplate maxOccur="1" minOccur="1">

 </DescriptionSetTemplate> 

Scholarly Works Application Profile

The Scholarly Works Application Profile (also known as Eprints Application Profile) has been expressed using the wiki syntax described here [EPRINTS]. As of October 2008, the wiki file is available athttp://dublincore.org/architecturewiki/EprintsApplicationProfile. Snapshots have been archived here both of the raw wiki file [EPRINTS-RAW] and of the XML output of the wiki software [EPRINTS-XML].

References

[ABSTRACT-MODEL]
DCMI Abstract Model DCMI Recommendation. 2007-06-04
http://dublincore.org/specifications/dublin-core/abstract-model/2007-06-04/

[DC-DSP]
Description Set Profiles: A constraint language for Dublin Core™ Application Profiles. DCMI Working Draft. 2008-03-31.
http://dublincore.org/specifications/dublin-core/dc-dsp/2008-03-31/

[EPRINTS]
Expressing the Scholarly Works (Eprints) DC Application Profile using the DSP wiki syntax.
http://dublincore.org/specifications/dublin-core/dsp-wiki-syntax/2008-10-06/2007-08-28.dsp-eprint.pdf

[EPRINTS-RAW]
Raw MoinMoin wiki file for Scholarly Works Application Profile, captured from http://dublincore.org/architecturewiki/EprintsApplicationProfile on 6 October 2007.
http://dublincore.org/specifications/dublin-core/dsp-wiki-syntax/2008-10-06/EprintsApplicationProfile-20081006-raw.txt

[EPRINTS-XML]
XML generated from the Scholarly Works Application Profile, captured from http://dublincore.org/architecturewiki/EprintsApplicationProfile?action=DSP2XML on 6 October 2008.
http://dublincore.org/specifications/dublin-core/dsp-wiki-syntax/2008-10-06/EprintsApplicationProfile.xml

[MOINMOIN]
The MoinMoin Wiki Engine.
http://moinmo.in/

[MOINMOIN-PARSERS]
MoinMoin Wiki Parsers.
http://moinmo.in/HelpOnParsers

[WIKI-SYNTAX]
A Wiki Syntax for DC Description Set Profiles, DC-2007, Singapore.
http://dublincore.org/specifications/dublin-core/dsp-wiki-syntax/2008-10-06/dcap-model_printout.pdf

[WIKI-SYNTAX-SOFTWARE]
http://dublincore.org/specifications/dublin-core/dsp-wiki-syntax/2008-10-06/DescriptionSetProfile-dist.zip