Skip to topic | Skip to bottom
Grimoires
Grimoires.MetadataDesign

Start of topic | Skip to actions

Metadata interface design document

Introduction

The metadata interface allows users to annotate entities within the grimoires registry. Within this document xsd represents the namespace http://www.w3.org/2001/XMLSchema, meta is the namespace http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd

Data structures

metadata

Metadata represents the annotation that is attached to entities within Grimories. It is defined in XML schema as
  <xsd:element name="metadata"             type="meta:Metadata"/>
  <xsd:complexType name="Metadata">
    <xsd:sequence>
      <xsd:element ref="meta:metadataType"/>
      <xsd:element ref="meta:metadataValue"/>
    </xsd:sequence>
    <xsd:attribute ref="meta:metadataKey" use="required"/>
  </xsd:complexType>
Any metadata in Grimoires consists of three items:
  1. metadataKey: unique key assigned by Grimoires when you publish a new piece of annotation
  2. metadataType: URI representing the type of annotation
  3. metadataValue: the value of the annotation. Can be either a string, a URI or an RDF triple.

MetadataValue? is defined as

  <xsd:element name="metadataValue"         type="meta:MetadataValue"/>
  <xsd:complexType name="MetadataValue">
    <xsd:choice>
      <xsd:element ref="meta:triplesAssertion"/>
      <xsd:element ref="meta:stringValue"/>
      <xsd:element ref="meta:uriValue"/>
    </xsd:choice>
  </xsd:complexType>

The following is an example of specifying a metadata with a string value:

   <meta:metadata meta:metadataKey="">
      <meta:metadataType>http://www.hogwarts.edu#headmaster</meta:metadataType>
      <meta:metadataValue>
         <meta:stringValue>Albus Dumbledore</meta:stringValue>
      </meta:metadataValue>
   </meta:metadata>

Another example for a metadata with a URI value:

   <meta:metadata meta:metadataKey="">
      <meta:metadataType>http://www.harrypotter.org#dumbledore</meta:metadataType>
      <meta:metadataValue>
         <meta:uriValue>http://www.lordoftherings.org#gandalf</meta:uriValue>
      </meta:metadataValue>
   </meta:metadata>

A triples assertion is defined as:

  <xsd:element name="triplesAssertion"     type="meta:TriplesAssertion"/>
  <xsd:complexType name="TriplesAssertion">
    <xsd:sequence>
      <xsd:element name="triples"            type="xsd:string"/>
      <xsd:element name="resourceIdentifier" type="xsd:string"/>
      <xsd:element name="language"           type="xsd:string"/>
      <xsd:element name="base"               type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>

Add example of RDF triple here!

metadataInfo

This is a response message from Grimoires. In addition of all the elements and attributes of #MetaData, it contains information about the author (not implemented yet) and last edited date of the metadata. It is defined as
  <xsd:element name="metadataInfo"             type="meta:MetadataInfo"/>
  <xsd:complexType name="MetadataInfo">
    <xsd:sequence>
      <xsd:element ref="meta:metadataType"/>
      <xsd:element ref="meta:metadataValue"/>
      <xsd:element ref="meta:author"/>
      <xsd:element ref="meta:date"/>
    </xsd:sequence>
    <xsd:attribute ref="meta:metadataKey" use="required"/>
  </xsd:complexType>

entityReference

An entity reference is a reference to things stored within Grimories. This can be the serviceKey for a UDDI businessService, or a message part within a WSDL file.

An entity reference for a UDDI businessService with a serviceKey 123456 looks like this:

   <meta:entityReference entityType="http://www.uddi.org/schema/uddi_v2.xsd#serviceKey">
      <meta:stringKey>123456</meta:stringKey>
   </meta:entityReference>

The entity reference for a UDDI businessEntity looks similar:

   <meta:entityReference entityType="http://www.uddi.org/schema/uddi_v2.xsd#businessKey">
      <meta:stringKey>78901</meta:stringKey>
   </meta:entityReference>

To annotate a WSDL file, you will first need to publish it in Grimoires. This is done via the WSDL interface. For more information, consult the WSDLInterfaceGuide. Using the BlastnWSDL as an example, to refer to the message part with name in0, you will need the message namespace, message name, and the message part name of the message part:

  <meta:entityReference entityType="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd#messagePartReference">
    <meta:messagePartReference>
      <meta:messageNamespace>http://www.ebi.ac.uk/alignment::blastn_ncbi::derived</meta:messageNamespace>
      <meta:messageName>runRequest1</meta:messageName>
      <meta:messagePartName>in0</meta:messagePartName>
    </meta:messagePartReference>
  </meta:entityReference>

To refer the operation run, you'll need its port type name, port type namespace, and operation name:

  <meta:entityReference entityType="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd#operationReference">
    <meta:operationReference>
      <meta:portTypeNamespace>http://www.ebi.ac.uk/alignment::blastn_ncbi::derived</meta:portTypeNamespace>
      <meta:portTypeName>AnalysisWSAppLabImpl</meta:portTypeName>
      <meta:operationName>run</meta:operationName>
    </meta:operationReference>
  </meta:entityReference>

metadataQuery

The metadataQuery and metadataQueryBag structures are used in query operations in the metadata interface. The metadataQueryBag is a sequence of 1 or more metadataQuery structures:
  <xsd:element name="metadataQueryBag" type="meta:MetadataQueryBag"/>
  <xsd:complexType name="MetadataQueryBag">
    <xsd:sequence>
      <xsd:element ref="meta:metadataQuery" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

Each metadataQuery specifies a metadataType and a metadataValue to search on. An optional findQualifiers can be used. Currently, only two findQualifier (wildCardSearch and caseSensitiveSearch) are supported for string based metadataValues. By default string comparisons are done as exact string matches.

An example of a metadataQuery for a URI metadataValue:

  <meta:metadataQuery>
    <meta:metadataType>http://www.harrypotter.org#dumbledore</meta:metadataType>
    <meta:metadataValue>
       <meta:uriValue>http://www.lordoftherings.org#gandalf</meta:uriValue>
    </meta:metadataValue>
  </meta:metadataQuery>

Another example of a metadataQuery, this time using the wildCardSearch findQualifier:

  <meta:metadataQuery>
    <findQualifiers>
      <findQualifier>wildCardSearch</findQualifier>
    </findQualifiers>
    <meta:metadataType>http://www.hogwarts.edu#headmaster</meta:metadataType>
    <meta:metadataValue>
      <meta:stringValue>Albus</meta:stringValue>
    </meta:metadataValue>
  </meta:metadataQuery>
This metadata query specifies a search all for strings that contains Albus.

faultDetail

Errors in the processing of metadata commands in Grimoires are communicated via faultDetail and faultDetailList elements within the SOAP Fault element. Here is an example of an error:
<soapenv:Fault>
  <faultcode>soapenv:Server.generalException</faultcode>
  <faultstring/>
  <detail>
    <ns1:faultDetailList xmlns:ns1="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd">
      <ns1:faultDetail errorCode="E_invalidKeyPassed" errorNumber="10210">
        <errorMessage>entityReference did not match with any known entity</errorMessage>
      </ns1:faultDetail>
    </ns1:faultDetailList>
    ....
  </detail>
</soapenv:Fault>
The detail of the error can be found within the errorMessage element.

Publish_metadata interface

This section introduces the interface for publishing metadata to existing entities in Grimoires. Entities supported for annotation includes UDDI businessEntities, businessServices, tModel and bindingTemplates, and WSDL message parts and operations. Publishing UDDIv2 entities in Grimoires is exactly like publishing in other UDDI registries (see UDDIUserGuide). To publish WSDL files, consult the WSDLInterfaceGuide.

Assuming that your Grimoires is installed at http://localhost:8080/grimoires, then this interface is available at http://localhost:8080/grimoires/services/publish_metadata. Two operations are present in this interface: addMetadataToEntity and deleteMetadata.

addMetadataToEntity

Suppose a UDDI service named STRING_CONCAT is published in Grimoires with a serviceKey 12345. You want to add a comment that the service can only be accessed in the US. To publish this metadata, the addMetadataToEntity operation of the publish_metadata interface is used:
<meta:addMetadataToEntity 
      xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api"
      xmlns:uddi="urn:uddi-org:api_v2">
   <meta:entityReference entityType="http://www.uddi.org/schema/uddi_v2.xsd#serviceKey">
      <meta:stringKey>12345</meta:stringKey>
   </meta:entityReference>
   <meta:metadata meta:metadataKey="">
      <meta:metadataType>http://purl.org/dc/terms/accessRights</meta:metadataType>
      <meta:metadataValue>
         <meta:stringValue>service is only available within US</meta:stringValue>
      </meta:metadataValue>
   </meta:metadata>
</meta:addMetadataToEntity>

The addMetadataToEntity message contains two elements --- #EntityReference and #MetaData. To annotate a different entity or to publish a different metadata, construct a suitable #EntityReference and #MetaData according to the guidelines described earlier in this article.

In this example, we use accessRights defined by the Dublin Core Metadata Initiative as our metadataType. The metadataKey is left empty, indicating this is a new piece of metadata. If a metadataKey is specified, the existing metadata with the specified key will be replaced.

If the operation is successful, grimoires return a #MetadataInfo message:

<metadataInfo ns1:metadataKey="67890"
              xmlns="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd" 
              xmlns:ns1="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd">
  <metadataType>http://purl.org/dc/terms/accessRights</metadataType>
  <metadataValue>
    <triplesAssertion xsi:nil="true"/>
    <stringValue>service is only available within US</stringValue>
    <uriValue xsi:nil="true"/>
  </metadataValue>
  <author xsi:nil="true"/>
  <date>Mon Jan 31 11:58:53 GMT 2005</date>
</metadataInfo>

Here, the metadataKey 67890 is assigned to the metadata attached to the STRING_CONCAT service.

deleteMetadata

To delete the metadata published in the example in #AddMetadataToEntity, you will need its metadataKey (67890 here):
<meta:deleteMetadata xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api">
   <meta:metadataKey>67890</meta:metadataKey>
</meta:deleteMetadata>

Inquire_metadata interface

This section explains the operations of the inquire_metadata interface. Assuming that your Grimoires is installed at http://localhost:8080/grimoires, then this interface is available at http://localhost:8080/grimoires/services/inquire_metadata. There are three operations available at this interface: get_entityMetadata, get_metadataDetail and find_entityByMetadata.

get_entityMetadata

You can retrieve metadata attached to entities in Grimoires using the get_entityMetadata message. To retrieve metadata attached to the STRING_CONCAT service in the previous example:
<meta:get_entityMetadata 
        xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api"
        xmlns:uddi="urn:uddi-org:api_v2">
  <meta:entityReference entityType="http://www.uddi.org/schema/uddi_v2.xsd#serviceKey">
    <meta:stringKey>12345</meta:stringKey>
  </meta:entityReference>
</meta:get_entityMetadata>

On success, a metadataInfos message is returned. This is a list of zero or more #MetadataInfo:

<metadataInfos xmlns="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd">
  <metadataInfo ns1:metadataKey="98d60e47-53f8-477b-9608-9c0cfd2cb986"
                xmlns:ns1="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd">
    <metadataType>http://purl.org/dc/terms/accessRights</metadataType>
    <metadataValue>
      <stringValue>service is only available within US</stringValue>
    </metadataValue>
    <date>Mon Jan 31 11:58:53 GMT 2005</date>
  </metadataInfo>
</metadataInfos>

get_metadataDetail

The operation retrieves the details of a piece of metadata using its metadataKey. Assuming the metadataKey is 67890:
<meta:get_metadataDetail xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api">
   <meta:metadataKey>67890</meta:metadataKey>
</meta:get_metadataDetail>

If the operation is successful, a #MetadataInfo message is returned.

find_entityByMetadata

This operations allows you to search for entities containing specific pieces of metadata using #MetadataQuery:
<meta:find_entityByMetadata xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api">
  <meta:metadataQueryBag>
    <meta:metadataQuery/>
    [<meta:metadataQuery/> ...]
  </meta:metadataQueryBag>
</meta:find_entityByMetadata>

On success, Grimoires returns an entityReferenceList containing #EntityReferences that are annotated with the specified metadata. The format of the entityReferenceList is

  <xsd:element name="entityReferenceList"          type="meta:EntityReferenceList"/>
  <xsd:complexType name="EntityReferenceList">
    <xsd:sequence>
      <xsd:element ref="meta:entityReference" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

UDDI specific operations

Services from this interface is available at http://localhost:8080/grimoires/services/inquire_uddiMetadata.

find_service

This operation adds a #MetadataQueryBag to the normal UDDIv2 find_service function. It is defined as:
  <xsd:element name="find_service" type="meta:Find_service"/>
  <xsd:complexType name="Find_service">
    <xsd:sequence>
      <xsd:element ref="meta:findQualifiers" minOccurs="0"/>
      <xsd:element ref="uddi:name" minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element ref="uddi:categoryBag" minOccurs="0"/>
      <xsd:element ref="uddi:tModelBag" minOccurs="0"/>
      <xsd:element ref="meta:metadataQueryBag" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="generic" type="string" use="required"/>
    <xsd:attribute name="maxRows" type="int" use="optional"/>
    <xsd:attribute name="businessKey" type="uddi:businessKey" use="optional"/>
  </xsd:complexType>

For example, you want to search for a service with the name "Great Service" and created by "John Smith" (ie metadataType = http://purl.org/dc/elements/1.1/creator, metadataValue = John Smith):

<meta:find_service generic="2.0"
                   uddi:businessKey=""
                   xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api"  
                   xmlns:uddi="urn:uddi-org:api_v2">
   <uddi:name>Great Service</uddi:name>
   <meta:metadataQueryBag>
     <meta:metadataQuery>
       <meta:metadataType>http://purl.org/dc/elements/1.1/creator</meta:metadataType>
       <meta:metadataValue>
          <meta:stringValue>John Smith</meta:stringValue>
       </meta:metadataValue>
     </meta:metadataQuery>
   </meta:metadataQueryBag>
</meta:find_service>

On success, a UDDIv2 ServiceList? is returned.

WSDL specific operations

A collection of WSDL specifc operation are available at the inquire_wsdlMetadata interface. Assuming that your Grimoires is installed at http://localhost:8080/grimoires, this interface is available at http://localhost:8080/grimoires/services/inquire_wsdlMetadata.

find_interfaceByMessagePartMetadata

This opertion searches all WSDL files published in Grimoires to find those that have certain metadata attached to their message parts. The search criteria is specified using a #MetadataQueryBag. Following is an example:

<meta:find_interfaceByMessagePartMetadata xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api">
  <meta:metadataQueryBag>
    <meta:metadataQuery>
      <meta:metadataType>http://www.harrypotter.org#dumbledore</meta:metadataType>
      <meta:metadataValue><meta:uriValue>http://www.lordoftherings.org#gandalf</meta:uriValue></meta:metadataValue>
    </meta:metadataQuery>
  </meta:metadataQueryBag>
</meta:find_interfaceByMessagePartMetadata>

On success, a #UriBag is returned. It is defined as:

  <xsd:element name="uriBag"          type="meta:uriBag"/>
  <xsd:element name="uri" type="xsd:anyURI"/>
  <xsd:complexType name="uriBag">
    <xsd:sequence>
      <xsd:element ref="meta:uri" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

An example:

<uriBag xmlns="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd">
   <uri> http://www.ecs.soton.ac.uk/~sm/blastn.wsdl</uri>
</uriBag>

find_interfaceByOperationMetadata

This opertion searches all WSDL files published in Grimoires to find those that have certain metadata attached to their operations. The search criteria is specified using a #MetadataQueryBag. It has a similar syntax to find_interfaceByMessagePartMetadata:
  <xsd:element name="find_interfaceByOperationMetadata" type="meta:Find_interfaceByOperationMetadata"/>
  <xsd:complexType name="Find_interfaceByOperationMetadata">
    <xsd:sequence>
      <xsd:element ref="meta:metadataQueryBag"/>
    </xsd:sequence>
  </xsd:complexType>

On success, a #UriBag is returned.

-- SylviaWong - 31 Jan 2005
example basic operations section
-- SylviaWong - 15 Feb 2005
data structure - metadata
-- SylviaWong - 16 Feb 2005
data structure - entity reference, metadataQuery, faultDetail, metadataInfo
inquire_metadata, publish_metadata
WSDL operations - find_interfaceByOperationMetadata, find_interfaceByMessagePartMetadata
-- SylviaWong - 17 Feb 2005
UDDI operations - find_service

to top


You are here: Grimoires > MetadataDesign

to top

Copyright 2004 by the University of Southampton