From KMR Wiki

Main: Draft: Wiki format for Description Set Profile

This is a draft document on how a Description Set Profile [1] is expressed in a Wiki-format. A Description Set Profile (abbreviated DSP in the rest of this document) is not directly intended for human consumption, but with a DSP expressed in a wiki-format it is possible to mix normal wiki-syntax with specific DSP expressions in order to document it, from that source it is possible to create:

The DSP wiki-syntax and how to use is described in this document and is focused on an implementation done for the moinmoin wiki engine [2] with the help of an extension to that wiki-engine. The DSP wiki-syntax itself is independent of wiki engine and is possible to use on another wiki-engine. This of course dependent on if and how the wiki engine of your choice supports extension. The extension in the moinmoin wiki-engine to render a HTML-page for the DSP, described here, has been done by adding a parser extension to the wiki. To call that parser, named DSP, inside a wiki-page the following syntax is used:

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

Anything above and below is parsed according to the normal moinmoin wiki syntax. For more information about parsers in moinmoin-wiki visit http://moinmoin.wikiwikiweb.de/HelpOnParsers

To create the DSP XML a so called action extension for the moinmoin wiki has been implemented, this will be described in the end of this document.

Design and description of the wiki syntax

As stated in the description of Description Set Profile [1], it uses the notion of constraint and templates to describe the structure of a Description Set. There are two levels of templates in the DSP:

These templates furthermore consist of constraints that are used to limit the structure. The relations between the templates and the constraints are depicted in the figure 1 below


Figure 1

The major design choice was to break up the different parts, ie the templates and the constraint, that make up a Description Set Profile and make each part of them as easy to express as possible. 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. Ie if first a Description Template has been declared followed by a Statement Template, this Statement Template is seen as a part of that Description Template declared above it.

In the syntax 4 parts are possible to express on their own:

Before describing the syntax in more detail, below is an empty template to serve as an example of how the structure looks like:

 {{{#!DSP

 Any (moinmoin)wiki-format text, will be placed over the Description Template declared below when rendered
 DT=(ID="" RC=[] min="" max="")

 Any (moinmoin)wiki-format text, that is placed above the Statement 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 DT, ST, NLC and LC the normal moinmoin wiki-syntax can be used.

Some small remarks on the usage of symbols in general in the format, when something in the format can have one and only on value it is placed between citation marks, as an example, see identifier for Description Template below. If the a set of choices is to be expressed the curly brackets are used in most places.

Expressing the different parts of a DSP

As stated above and seen in the template above the 4 basic parts are expressed with:

Each one of these expression has to start on a new line. As can also be seen from the template above it is possible to express normal wiki-syntax in between. This text does also need to start on a new line in order to not be mix up with the DSP wiki-syntax, this text is surrounding 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 for example an ST can be embedded into a table or some similar construct and the main reason for using a wiki, since you both construct the DSP and its documentation. If the keywords DT, ST, NLC or LC needs to start on an new line in the normal wikisyntax, add a backslash ("\") before and 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 and 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:

For a more detailed description about these attributes see the section about Description Template in the description of DSP [DT]. Here conditions for the attributes and possible and default values are described 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 them are declared the parenthesis should be left empty. The Statment Templates that belong to a Description Template are the ones that are declared under until a new declaration of a Description Template occurrs.

Example of a declaration of a Description Template:

  DT=(ID="Person" 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 is allowed to span over more than one line and the attributes inside are separated with a blankspace and is allowed to be in any order. Expressed inside the parenthesis are the attributes:

For a more detailed description about these attributes see the section about Statement Template in the description of the DSP [ST], where conditions for the attributes and possible and default values are described in more detail. Example of the parts described above:

 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 Dublin Core Abstract Model. To express constraints on a Statement Template they will be declared under the Statement Template that they belong to and they also need to start on a new line.

Expressing a literal value constraint

When an Statement Template has got the type constraint set to Literal it is possible to further constrain the possible values, ie 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 have to start on a new line. Inside the parenthesis the following parts can be expressed:

For a more detailed description about the attributes for Literal Value Constraints see the section about this in the description of the DSP [LC], where conditions on the attributes and possible and default values are described in more detail.

Example 1 of how to express an LC:
LC=( {[value="SomeEncoding" lang="en" SES="http://www.example.org/someSyntaxEncodingScheme"]})

Example 2 of how to express an LC with languageConstraint:
LC=( LangC=(occurrence="optional" {en, sv, es}))

Expressing a non-literal Value Constraint

When an Statement Template has got the type constraint set to NonLiteral it is possible to further constrain the possible values, ie a Non-literal Value Constraint. 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 over more than one line. Inside the parenthesis the following parts can be expressed:

For a more detailed description about the attributes for Non-Literal Value Constraints see the section about this in the description of the DSP [NLC], where conditions on the attributes and possible and default values are described in more detail.

Example 1 of 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 example from http://dublincore.org/architecturewiki/DescriptionSetProfile in wiki-format:

Example 1:

 {{{#!DSP

 DT=()

 ST=(PC={http://purl.org/dc/terms/title})

 ST=(PC={http://purl.org/dc/terms/description})

 }}}

Example 2

 {{{#!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})

 }}}

Usage example

The implementation of this syntax has been done as an extension to the the moinmoin wiki engine. Below follows an example and it will show how the syntax will be rendered in HTML and also how the resulting XML looks like.

Example of the syntax:

With the extension to the moinmoin wiki engine installed the syntax described in this document can be used on a page. It will be parsed as a Description Set Profile, below is an example:

 {{{#!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 will display the following when the page is called:

Description template

Title


Propertyhttp://purl.org/dc/terms/title
Literal?Yes
DefinitionA name given to the resource.
Value (Literal)Syntax Encoding Scheme:
Occurrence: disallowed

Language Constraint:
Occurrence: optional

Creator


Propertyhttp://purl.org/dc/terms/creator
Literal?No
DefinitionAn entity primarily responsible for making the resource.
CommentExamples of a Creator include a person, an organization, or a service. Typically, the name of a Creator should be used to indicate the entity.
Value(Non-Literal)Value URI Constraint:
Occurrence: disallowed

Vocabulary Encoding Scheme Constraint:
Occurrence: disallowed

Value String Constraint:
-Syntax Encoding Syntax Constraint:
Occurrence: "disallowed"

-Language Constraint:
Occurrence: "disallowed"

As can be seen here the Statement Template and the Literal and Non-Literal Value constraints are rendered in a table in HTML. That table can be integrated into another table declared in the normal wiki-syntax, as done above.

The resulting XML

From the wiki-syntax an action-extension has been 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. Below is the XML for the example syntax given above:

 <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> 
Retrieved from http://kmr.nada.kth.se/wiki/Main/MoinMoinWikiFormatSuggestion1
Page last modified on August 14, 2007, at 08:46 PM