KMR > Wiki > Main > MoinMoinWikiFormatSuggestion1

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 Description Set Profile rendered as an HTML-page for human consumption
A formal serialization in XML for the same Description Set Profile

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:

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

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:

Description template, directly corresponds to the description of it above.
Statement Template, that also corresponds to the description above. However, a Statement can be either a Literal Statement Template or Non-Literal Statement Template. Of which type it is can be expressed inside.
Non-Literal Value Constraint, this corresponds to the value constraints for a Non-Literal Statement Template
Literal Value Constraint this corresponds to the value constraints for a Literal Statement Template

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:

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 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:

Identifier, use the keyword "ID" followed by a "=" and a valid XML ID String inside citation 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 citation mark as the value, example expression: min="1"
Maximum occurrence constraint, use the keyword "max" followed by a "=" with a non negative integer inside citation mark as the value, example expression: max="1"

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:

Property list constraint or Sub-property constraint, to declare this start with the keyword "PC" followed by "=" and one and only one of the following:
- on URI within surrounding citation marks to declare a Sub Property Constraint, example expression: PC="http://purl.org/dc/elements/1.1/creator"
- a set of URI:s, 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 citation mark as the value, example expression: min="1"
Maximum occurrence constraint, use the keyword "max" followed by a "=" with a non negative integer inside citation mark as the value, example expression: max="1"
Type Constraint, is declared with the keyword "type" followed by a "=" and then either "Literal" or "NonLiteral" inside citation 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 on can be made according to the description of DSP [Statement Template type], Example: type="literal"

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:

Constraints on Syntax Encoding Scheme, a set of such constraint are declared with the keyword "SESConstraint" followed by a "=" and a left parenthesis, a right parenthesis close the expression. Inside the parenthesis the following can be declared:
- Syntax Encoding Scheme constraint that decides the occurrence of a Syntax Encoding Scheme constraint, starts with the keyword "occurrence" that have the possible values of 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, that states the syntax encoding schemes allowed for the literal, 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, are the literals that are allowed as values and are declared as a set inside curly braces, each entry inside the curly braces are declared inside angle 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 a ISO language tag are the valid values, for Syntax Encoding Scheme a URI is a valid value. Example expression {[value="A simple String" lang="en"], [...]}
Constraints on the langugae, 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" that have the possible values of mandatory, optional or disallowed. If this part is not declared it will by default be "optional", example syntax: occurrence="mandatory"
- Literal language list constraint are 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 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:

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 that the value may be an instance of (in the form of a URI) and is declared inside angle-brackets with comma and a blankspace as a separator. Example: {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. 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, is used if a vocabulary encoding scheme must be given. This is declared almost the same way as ValueURIConstraint, but with the keyword "VESConstraint" used instead. Example
VESConstraint=( occurrence="mandatory" {http://www.example.com/uri3, http://www.example.com/uri4})
Value String Constraint are declared by using the keyword "VStringConstraint" and with its argument inside left and right parenthesis. Inside the following is declared:
- Minimum occurrence constraint, use the keyword "min" followed by a "=" with a non zero Integer inside citation mark as the value, example expression: min="1"
- Maximum occurrence constraint, use the keyword "max" followed by a "=" with a non zero Integer inside citation mark 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 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

Property	http://purl.org/dc/terms/title
Literal?	Yes
Definition	A name given to the resource.
Value (Literal)	Syntax Encoding Scheme: Occurrence: disallowed Language Constraint: Occurrence: optional

Creator

Property	http://purl.org/dc/terms/creator
Literal?	No
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.
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>

No comments