Re: [wsrf] Issue 10: Concrete proposals for Metadata (Action Item)

[Tom Maguire <tmaguire@us.ibm.com>]

Perhaps I was a bit too subtle with the analysis of potential resolutions
and what I believe
is the preferred proposal.  The 3 choices are:

1) Add metadata to portType in annotations
2) Add metadata to portType through attachments (ala policy attachments)
3) Separate metadata document that is related to the portType

The pros and cons of each choice are detailed below.  The conclusion I draw
is
that choice 3 met most of the requirements and had the most desirable set
of attributes.

This choice would likely require our adding another specification to the
WSRF suite
of specifications and deliverables.

Thoughts?

Tom

Tom Maguire/Hawthorne/IBM@IBMUS wrote on 09/17/2004 03:46:26 PM:

>
>
>
>
> There are several ways for WSRF to capture metadata associated with a
> particular portType.
>
> Add metadata to portType in annotations
> Use the xs:documentation element to annotate components in WSDL1.1 and
xsd
> with additional metadata.
>
> <element name="pt1ResourceProperties">
>   <complexType>
>     <sequence>
>       <element ref="type1" minOccurs="0" maxOccurs="1">
>         <documentation>
>           <wsrf:propertyMetadata
>             mutability="mutable"
>             modifiability="read-only" />
>         </documentation>
>       </element>
>       <element ref="type2" minOccurs="0" maxOccurs="1">
>         <documentation>
>           <wsrf:propertyMetadata
>             mutability="mutable"
>             modifiability="read-write" />
>         </documentation>
>       </element>
>     </sequence>
>   </complexType>
> </element>
>
> <element name="type1" type="xs:string"/>
> <element name="type2" type="xs:string"/>
>
> <portType name="pt1" wsrp:ResourceProperties="pt1ResourceProperties">
>   <operation name="GetResourceProperty">
>     <documentation>
>       <wsrf:operationMetadata
>         idempotent="true" />
>     </documentation>
>     <input name="GetResourcePropertyRequest"
>            message="wsrp:GetResourcePropertyRequest" />
>     <output name="GetResourcePropertyResponse"
>            message="wsrp:GetResourcePropertyResponse" />
>     <fault name="ResourceUnknownFault"
>            message="wsrp:ResourceUnknownFault" />
>     <fault name="InvalidResourcePropertyQNameFault"
>            message="wsrp:InvalidResourcePropertyQNameFault" />
>   </operation>
> </portType>
>
> Pros:
>       Uses established extensibility mechanism
> Cons:
>       Mixed content of xs:documentation pretty ugly
>       Metadata is spread all over the place
>       Does not allow implementation specific extension of metadata;
>       metadata is only expressible at the type level
>       Confuses roles of authorship; the person with the knowledge of the
>       metadata might not have write access to xsd or wsdl
>       Substantial change to existing specifications; granularity of
>       expression forces lots of wsdl and xsd changes
>       No ability to have metadata on XML Schema attributes
>       Not sure how to add metadata for components that are not reflected
in
>       WSDL or xsd (notifications, relationships, others?)
>
> Add metadata to portType through attachments (ala policy attachments)
> Use open attribute capabilities to attach metadata to components in
WSDL1.1
> and xsd.
>
> <xs:schema>
>   <xs:attribute name="metadataURIs" type="list of xs:anyURI"/>
> </xs:schema>
>
> <element name="pt1ResourceProperties">
>   <complexType>
>     <sequence>
>       <element ref="type1" minOccurs="0" maxOccurs="1"
>                wsrf:metadataURIs="http://example.com/metadata#MUTABLE
>                             "http://example.com/metadata#READ-ONLY"; />
>       <element ref="type2" minOccurs="0" maxOccurs="1"
>                wsrf:metadataURIs="http://example.com/metadata#MUTABLE
>                             "http://example.com/metadata#READ-WRITE"; />
>     </sequence>
>   </complexType>
> </element>
>
> <element name="type1" type="xs:string"/>
> <element name="type2" type="xs:string"/>
>
> <portType name="pt1" wsrp:ResourceProperties="pt1ResourceProperties">
>   <operation name="GetResourceProperty"
>              wsrf:metadataURIs="http://example.com/metadata#IDEMPOTENT";
/>
>     <input name="GetResourcePropertyRequest"
>            message="wsrp:GetResourcePropertyRequest" />
>     <output name="GetResourcePropertyResponse"
>            message="wsrp:GetResourcePropertyResponse" />
>     <fault name="ResourceUnknownFault"
>            message="wsrp:ResourceUnknownFault" />
>     <fault name="InvalidResourcePropertyQNameFault"
>            message="wsrp:InvalidResourcePropertyQNameFault" />
>   </operation>
> </portType>
>
> Pros:
>       Mechanism that is proposed for WS-Policy
>       Metadata in a separate document
> Cons:
>       URI dereferencing is not clear
>       Confuses roles of authorship (less then documentation approach)
>       Metadata attachments are spread all over the place (potentially
>       metadata is spread all over the place as well)
>       Does not allow implementation specific extension of metadata
>       list of xs:anyURI is problematic for some tools (could use QName I
>       guess)
>       Substantial change to existing specifications; granularity of
>       expression forces lots of wsdl and xsd changes
>       No ability to have metadata on XML Schema attribute
>       Not sure how to add metadata for components that are not reflected
in
>       WSDL or xsd
>       Need to detail separate document structure for metadata
>
> Separate metadata document that is related to the portType
> Define a separate metadata document that has composition and separate
> lifetime from WSDL.  Allow
> connection to metadata document through portType open attributes (QName
and
> location ala wsdlLocation) for
> design time introspection.  Alloc connection to implementation specific
> metadata through resourceProperty
> element or MetadataExchange or both  for runtime introspection.
>
> <element name="pt1ResourceProperties">
>   <complexType>
>     <sequence>
>       <element ref="type1" minOccurs="0" maxOccurs="1"/>
>       <element ref="type2" minOccurs="0" maxOccurs="1"/>
>     </sequence>
>   </complexType>
> </element>
>
> <element name="type1" type="xs:string"/>
> <element name="type2" type="xs:string"/>
>
> <portType name="pt1" wsrp:ResourceProperties="pt1ResourceProperties"
>                      xxx:metadataDescriptor="tns1:pt1MetadataDocument"
>                      xxx:metadataDescriptorLocation="
> http://example.com/md/pt1
>
> http://example.com/md/pt1.md";>
>   <operation name="GetResourceProperty" />
>     <input name="GetResourcePropertyRequest"
>            message="wsrp:GetResourcePropertyRequest" />
>     <output name="GetResourcePropertyResponse"
>            message="wsrp:GetResourcePropertyResponse" />
>     <fault name="ResourceUnknownFault"
>            message="wsrp:ResourceUnknownFault" />
>     <fault name="InvalidResourcePropertyQNameFault"
>            message="wsrp:InvalidResourcePropertyQNameFault" />
>   </operation>
> </portType>
>
> The metadata description document would be structured something like
below.
> It could allow
> for non-WSDL component metadata, as well as specialization and
> reconcilation.
>
> <Definitions
>     xmlns=”http://www.proposedstandards.org/xmlns/MetadataDescriptor”
>     xmlns:tns=”http://example.com/ns/pt1”
>     targetNamespace=”http://example.com/ns/pt1”>
>   <MetadataDescriptor
>     name=”pt1MetadataDescriptor”
>     interface=”tns:pt1”
>     wsdlLocation=”http://example.com/ns/pt1
>                   http://example.com/wsdl/pt1.wsdl” >
>     <Property path=”tns:type1”
>               mutability=”constant”
>               modifiability=”read-only” />
>     <Property path=”tns:type2”
>               mutability=”constant”
>               modifiability=”read-only” />
>   </MetadataDescriptor>
> </Definitions>
>
> Pros:
>       Metadata in a separate document
>       URI dereferencing is clear (follows wsdlLocation model)
>       Roles of authorship are clear and separated
>       Metadata is namespaced and in a single place
>       WSDL tooling and xml tooling minimal impact
>       Allows implementation specific extensions of metadata
>       No change to existing specifications
>       Metadata on attributes should be no problem
> Cons:
>       New mechanism
>       New specification
>       Need to detail separate document structure for metadata
>
>
>
> Issue WSRF10: Need mechanism to express metadata on properties such as
> ‘read-only’
> It is currently not possible to determine property behavior based on
> examining a property document schema. OGSI ServiceData defined some
> metadata for properties to express behaviors such as ‘read-only’. It is
> useful to a client to have access to this and similar metadata about a
> property.
>
> Discussion occurred at the face-to-face July 27, 2004 about this issue.
It
> was generally accepted that there is a need to express meta-data about
> properties.
>
>
>
> Specifications
>
> ·     WS-ResourceProperties, Version 1.1, March 5, 2004
>
>
> Notes
>
>
>
> Proposed Recommendations
>
> One possible solution is to use the annotation element from schema to add
> meta-data about the property.
>
> Another possible solution is to have a secondary document that includes
> meta-data about some or all of the properties in a resource property
> document.
>
> Some interesting resource property meta-data includes:
>
> §        Insertable:bool
> §        Updateable: bool
> §        Deleteable: bool
> §        Readable: bool
> §        Initial Value(s): <any>
> §        Constant: bool
> §        ValidValue: <any> (??)
>
> Concrete proposals to be sent to the list.
>
>
>
> Status: Open since April 28, 2004
>
>
>
> Contact: Bryan Murray
>
>
>
> Cross Reference:
>
>