Metadata for WS-Resources WS-Resource Metadata Descriptor OASIS WSRF F2F Tuesday, October 26th, 2004 Steve Graham Bryan Murray Tom Maguire William Vambenepe

Motivation Support a broad and evolving range of WS-Resource types Need to be able to discover the descriptions of these resources Interfaces (described in WSDL) Additional descriptors The broader the range of WS-Resources to be supported, the more descriptive information required

Requirements Define an information model representing metadata about operations, resource properties and other information associated with a WS-Resource interface. Define a standard annotation for associating meta data descriptions with other description artifacts of the WS-Resource, particularly its WSDL 1.1 portType and its resource properties document definition. Define the standard schema for representing the aspects of the information model.

WS-Resource Metadata Descriptor Defines a mechanism for providing additional description on interfaces and WS-Resource implementations: Properties Operations Extensibility for other descriptions Description is required at both: design time No WS-Resources available (install, provisioning) Development of support for new WS-Resources execution time Introspection of WS-Resources

Overview WS-Resource Descriptor document for each portType Canonical “Canonical” manageability portTypes Combined by reference Combined by copy-and-paste. Individual portType descriptors are combined via references into a document that specializes the description of the interface Describes Most derived manageability portType for a managed resource. Defines the schema for the resourceProperties document that represents the state of the resource. OperatingSystem descriptor OperatingSystem portType Implements Windows2003Server descriptor Windows2003Server Managed resource type Individual resource types that implement the port type provides its own descriptor that forms a template that resources of the type will match LinuxRedHat descriptior LinuxRedHat Managed resource type Windows2003Server WS-Resource LinuxRedHat WS-Resource

Operating System portType … xmlns:os=”http://example.com/ns/OperatingSystem” … <portType name="OperatingSystem“ wsrf-rp:ResourceProperties="os:OSResourceProperties" wsrf-rp:derivedFrom="id:Identification" ..wsrmd:metadataDescriptor=”os:OperatingSystemDescriptor” ..wsrmd:metadataDescriptorLocation=”http://example.com/ns/OperatingSystem http://example.com/prototypes/OperatingSystem.wsrmd”> </portType> Line 003 contains a portType declaration for a portType named OperatingSystem in the namespace corresponding to the os: namespace prefix declaration. Line 004 indicates the global XML element declaration of the root element of the resource properties document associated with any WS-Resource whose Web service implements the os:OperatingSystem portType. Line 005 indicates this portType extends the portType named Identification from the namespace corresponding to the id: namespace prefix declaration. This means that the os:OperatingSystem includes all of the resource properties and operations defined by the id:Identification portType. Line 006 identifies that a Prototype has been defined for this interface identified by the QName os:OperatingSystemPrototype. Line 007 and 008 indicate that information about Prototypes in the namespace corresponding to the os: namespace prefix declaration can be found by dereferencing http://example.com /prototypes/OperatingSystem.wsrmp. The OperatingSystem portType is an extension of the Identification portType. The portType annotation for the Resource Property GED (next page). …and where that descriptor is located. The prototype which corresponds to this portType.

Operating System Property definitions … xmlns:os="… <element name="OSResourceProperties"> <complexType> <sequence> <element ref="os:numberOfProcesses" minOccurs="0" maxOccurs="1"/> <element ref="os:totalSwapSpaceSize" minOccurs="0" maxOccurs="1"/> <element ref="os:processor" minOccurs="1" maxOccurs="unbounded"/> </sequence> </complexType> </element> <element name="numberOfProcesses" type="xsd:int" /> <element name="totalSwapSpaceSize" type="xsd:unsignedLong" /> <element name="processor" type="os:Processor" /> <complexType name="Processor"> <element name="processorFamily" type="xsd:string" minOccurs="1" maxOccurs="1" /> <element name="manufacturer" type="xsd:string" minOccurs="1" maxOccurs="1" /> <element name="serialNumber" type="xsd:string" minOccurs="1" maxOccurs="1" />

Identification Property definitions <element name="Identification"> <complexType> <sequence> <element ref="ResourceType" minOccurs="0" maxOccurs="1"/> <element ref="ResourceID" minOccurs="0" maxOccurs="1"/> </sequence> </complexType> </element> <element name="ResourceType" type="list of xs:anyURI" /> <element name="ResourceID" type="xsd:string" />

Identification portType Descriptor (001) <Definitions (002) xmlns=”http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd” (003) xmlns:id=”http://example.com/ns/Identification” (004) targetNamespace=”http://example.com/ns/Identification”> (005) <MetadataDescriptor (006) name=”IdentificationMetadataDescriptor” (007) interface=”id:Identification” (008) wsdlLocation=”http://example.com/ns/Identification (009) http://example.com/wsdl/Identification.wsdl” > (010) <Property path=”id:ResourceID” (011) mutability=”constant” (012) modifiability=”read-only” /> (013) <Property path=”id:ResourceType” (014) mutability=”constant” (015) modifiability=”read-only” /> (016) </MetadataDescriptor> (017)</Definitions> The Definitions component is a container for a set of MetadataDescriptor components. The Definitions component defines a targetNamespace which forms the {namespace} property of all components it contains. The MetadataDescriptor component is a container for a set of metadata descriptions and constraints on a WS-Resource. The MetadataDescriptor component contains additional information that describes or constrains various aspects of a WS-Resource. Line (001) contains a Definitions element defining Prototype elements for the target namespace identified in line (004). There is one Prototype element child of this Definitions element (lines (005)–(016)). The name of the Prototype is contained in line (006). This together with the namespace prefix declaration in line (003) corresponding to the targetNamespace of the Definitions element means the QName of the Prototype is id:IdentificationPrototype. Line (007) identifies the QName of the portType (interface) to which this Prototype is associated. The location of WSDL for the Identification portType is expressed in the wsdlLocation attribute in lines (008)-(009). This follows the pattern of the wsdli:wsdlLocation attribute defined in the WSDL 2.0 specification [WSDL 2.0]. Lines (010)-(015) show two Property elements containing further metadata information about resource properties defined in the resource properties document for the Identification portType. Lines (010)-(012) contain the first Property element that references the QName of the id:ResourceID resource property. Line (011) indicates that the id:ResourceID resource property element will always have a constant value. Line (012) states that the id:ResourceID resource property is read-only, meaning that it cannot be changed by a requestor using the SetResourceProperties operation as defined in WS-ResourceProperties [WS‑ResourceProperties]. The second Property element, in lines (013)-(015), references the QName of the id:ResourceType resource property in line (013). This resource property element has the same metadata attributes as id:ResourceIdentifier. This descriptor corresponds to the Identification portType. The ResourceID resource property element of the id:Identification resource property document. Will always have a constant value …and it cannot be changed by the wsrp:SetResourceProperties operation. Path expression defined by the following BNF: (1) path ::= ResourceProperty Qualifier [AttributeIdentifier] (2) ResourceProperty ::= Qname (vc: QName MUST correspond to a resource property declaration). (3) Qualifier ::= [‘/’ [Qname | NCName]]* (vc: the path must locate a node in the descendant axis of the ResourceProperty element) (4) AttributeIdentifier ::= / @ [Qname | NCName] (vc: the AttributeIdentifier must identify an attribute information element contained on the element identified by the ResourceProperty and Qualifier productions). The Identification portType is at this location. The ResourceType resource property element of the id:Identification resource property document.

Operating System portType Descriptor (001) <Definitions (002) xmlns=”http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd” (003) xmlns:id=”http://example.com/ns/Identification” (004) xmlns:os=”http://example.com/ns/OperatingSystem” (005) targetNamespace=”http://example.com/ns/OperatingSystem”> (006) <MetadataDescriptor (007) name=”OperatingSystemMetadataDescriptor” (008) interface=”os:OperatingSystem” (009) wsdlLocation=”http://example.com/ns/OperatingSystem (010) http://example.com/wsdl/OperatingSystem.wsdl” (011) specializes=”id:IdentificationMetadataDescriptor” (012) metadataDescriptorLocation=”http://example.com/ns/Identification (013) http://example.com/metadataDescriptors/Identification.wsrmd” > … next page Property metadata descriptions (037) </MetadataDescriptor> (038) </Definitions> Lines (001) to (038) contain a Definitions element for the http://example.com/ns/OperatingSystem namespace. Lines (006) to (037) contain the definition of the Prototype with QName os:OperatingSystem prototype. Line (008) indicates that this prototype corresponds to the OperatingSystem portType. Lines (009)-(010) gives the location of the WSDL document that defines elements associated with the namespace URI associated with the os: prefix (i.e. the WSDL definitions element that defines the OperatingSystem portType). Line (011) indicates that this prototype definition extends a Prototype definition named id:Identification. Lines (012) and (013) indicate that a prototype Definition can be found for the id: namespace at http://example.com /prototypes/Identification.wsrmp. Because this prototype component is an extension of another prototype component, a consumer of this description must understand the combination of both prototype components. This descriptor specializes the Identification descriptor. This descriptor corresponds to the OperatingSystem portType. The Identification MetadataDescriptor is at this location.

Operating System Descriptor Properties (014) <Property path=”id:ResourceType”> (015) <ValidValues> (016) <id:ResourceType>OperatingSystem</id:ResourceType> (017) <id:ResourceType>SuSELinux</id:ResourceType> (018) <id:ResourceType>IBMzOS</id:ResourceType> (019) <id:ResourceType>MicrosoftWindows_XP</id:ResourceType> (020) </ValidValues> (021) </Property> (022) <Property path="os:numberOfProcesses" (023) mutability="mutable" (024) modifiability="read-only" /> (025) <Property path=”os:processor” (026) mutability=”constant” (027) modifiability=”read-only” /> (028) <Property path=”os:processor/os:processorFamily”> (029) <ValidValues> (030) <os:processorFamily>Pentium Family</os:processorFamily> (031) <os:processorFamily>Power PC 750</os:processorFamily> (032) <os:processorFamily>68xxxx Family</os:processorFamily> (033) <os:processorFamily>IBM390 Family</os:processorFamily> (034) <os:processorFamily>G5</os:processorFamily> (035) </ValidValues> (036) </Property> This property element augments any property element that may appear in the Identification prototype. Lines (014)-(036) contains the four properties described in this prototype example. Lines (014)-(021) contains the Property element describing the id:ResourceType resource property from the Identification portType. This Property element augments any Property element for id:ResourceType that may appear in the prototype for the Identification prototype. Lines (015)-(020) contain an additional set of ValidValues that the id:ResourceType resource property may contain. Lines (022)-(024) contain the os:numberOfProcesses Property element which references the QName of the os:numberOfProcesses resource property. Line (023) indicates that the value of the os:numberOfProcesses may change over time. Line (024) indicates that, the os:numberOfProcesses can not be changed by a requestor using the SetResourceProperties operation as defined in WS-ResourceProperties [WS‑ResourceProperties]. The next three Property elements all reference the same QName, the os:processor. Each of these property components however address different scopes within the resource property element. Representation of scopes is through the scope attribute information item. The scope is a path expression that defines the node within the descendant axis of the resource property to which the description applies. Lines (025)-(027) describe aspects of the os:processor that apply to the entire contents of the os:processor resource property. Lines (028)-(036) describe valid values for a subcomponent of os:processor (its os:processorFamily child element). The os:numberOfProcesses resource property elements value may change over time. The set of valid values the ResourceType resource property element may contain (restrictive) associated with a WS-Resource or type OperatingSystem.

Windows XP WS-Resource Descriptor (001) <Definitions (002) xmlns=”http://docs.oasis-open.org/wsrf/2004/10/wsrf-WS-ResourceMetadataDescriptor-1.0-draft-01.xsd” (003) xmlns:id=”http://example.com/ns/Identification” (004) xmlns:os=”http://example.com/ns/OperatingSystem” (005) targetNamespace=”http://example.com/ns/OperatingSystem/WinXP”> (006) <MetadataDescriptor (007) name=”WindowsXPPrototype” (008) interface=”os:OperatingSystem” (009) wsdlLocation=”http://example.com/ns/OperatingSystem (010) http://example.com/ns/OperatingSystem.wsdl” (011) specializes=”os:OperatingSystemMetadataDescriptor” (012) metadataDescriptorLocation=”http://example.com/ns/OperatingSystem (013) http://example.com/metadataDescriptors/OperatingSystem.wsrmd” > … next page Property metadata descriptions (026) </MetadataDescriptor> (027) </Definitions> Line (008) indicates that this prototype corresponds to the OperatingSystem portType, and line (011) indicates that this prototype extends the “base” prototype for the OperatingSystem prototype at the given URL. Because this prototype component is an extension of another prototype component, a consumer of this description must understand the combination of both prototype components.

Windows XP WS-Resource Properties (014) <Property path=”id:ResourceType”> (015) <ValidValues> (016) <id:ResourceType>OperatingSystem</id:ResourceType> (017) <id:ResourceType>MicrosoftWindows_XP</id:ResourceType> (018) </ValidValues> (019) </Property> (020) <Property path=”os:processor/os:processorFamily” (021) <ValidValues> (022) <os:processorFamily>Pentium Family</os:processorFamily> (023) <os:processorFamily>AMD</os:processorFamily> (024) </ValidValues> (025) </Property> Prototype encloses two Property elements. Lines (014)-(019) contain a description of the id:ResourceType resource property, further constraining the set of ValidValues for a Windows XP WS-Resource. Lines (020)-(025) constrain the os:processorFamily sub-element of the os:processor resource property by giving additional constraints on the ValidValues.

Logical Model logical model depicting the relationship between the various elements of meta data description and those elements the metadata describes.

Information Model This model is depicted as a set of components with properties, each aspect of a WS-Resource metadata component having its own set of properties. An XML Infoset representation for these components is also provided. How the XML Infoset representation of a given set of WS-Resource prototype components is constructed is outside the scope of this specification.

Key design decisions Provides templates to describe instantiated resources implementations of those interfaces All instances of a resource conform to the same descriptor document Exactly one ‘Descriptor’ document associated with a WSDL interface or portType Descriptor ‘points to’ the WSDL document with which it is associated Allows additional domain specific extensions – e.g. for notifications, relationships

Pseudo Schemas

Definitions <Definitions targetNamespace=”xs:anyURI” {anyAttribute}* > <documentation />? <MetadataDescriptor /> * {any}* </Definitions> The properties of a Prototype component are as follows: {name} a name of a Prototype component. {namespace} a namespace URI of the Prototype component. {QName} a combination of the {name} and {namespace} of the Prototype component. {interface} a QName identifying a Web services interface definition with which this Prototype is associated. {wsdlLocation} a set of URI pairs, each pair associating a namespace URI with a URL of a document containing a WSDL definition of that namespace. This is the same mechanism as is used in WSDL 2.0. {prototypeLocation} a set of URI pairs, each pair associating a namespace URI with a URL of a document containing a prototype Definitions definition of that namespace. {extended Prototypes} a set of zero or more QNames of Prototype components. {properties} A set of zero or more Property components {operations} A set of zero or more Operation components {notifications} A set of zero or more Notification components.

MetadataDescriptor <Operation /> * <MetadataDescriptor name=”xs:NCName” interface=”xs:QName” specializes=”list of xs:QName”? wsdlLocation=”list of xs:anyUri”? metadataDescriptorLocation=”list of xs:anyUri”? {anyAttribute}* > <documentation /> ? <Property /> * <Operation /> * {any}* </MetadataDescriptor> The properties of a Prototype component are as follows: {name} a name of a Prototype component. {namespace} a namespace URI of the Prototype component. {QName} a combination of the {name} and {namespace} of the Prototype component. {interface} a QName identifying a Web services interface definition with which this Prototype is associated. {wsdlLocation} a set of URI pairs, each pair associating a namespace URI with a URL of a document containing a WSDL definition of that namespace. This is the same mechanism as is used in WSDL 2.0. {prototypeLocation} a set of URI pairs, each pair associating a namespace URI with a URL of a document containing a prototype Definitions definition of that namespace. {extended Prototypes} a set of zero or more QNames of Prototype components. {properties} A set of zero or more Property components {operations} A set of zero or more Operation components {notifications} A set of zero or more Notification components.

Property <Property path=”xs:QName [/ [xs:QName | xs:NCName ]]* [/@[xs:QName | xs:NCName ]]?” mutability=”[constant|appendable|mutable]” ? modifiability=”[read-only|read-write]” ? subscribability=”xs:boolean” ? {anyAttribute}* > <documentation />? [ <ValidValues> {any}* </ValidValues> | <ValidValueRange lowerBound="xs:anySimpleType"? upperBound="xs:anySimpleType"? /> ] ? <StaticValues> {any}* </StaticValues> ? {any}* </Property> The properties of a Property component are as follows: {scope} the XML element to which the Property applies. This is composed of a required resourceProperty sub-component and an optional path expression indicating a child element of the resourceProperty to which the Property component is scoped. {interface} a QName of a WSDL 1.1 portType or WSDL 2.0 interface to which the {resourceProperty} is associated. {modifiability} an xs:string enumeration of “constant”, “appendable”, or “mutable”. {mutability} an xs:string enumeration of “read-only” or “read-write”. {validValues} zero or one ValidValues components. {staticValues} zero or one StaticValues components. {initialValues} zero or one InitialValues components.

Path of a Property component (Overlaps) Overlapping path iff, A1 = B1. This is equivalent to saying that Property A and Property B pertain to the same Resource Property, but either or both of those components may pertain only to a descendant of the resource property. For example, if the {path} of Property A is “tns:a/b” and the {path} of Property B is “tns:a”, we say that the {path} of Property A and the {path} of Property B overlap.

Path of a Property component (identical) identical path iff, for each value of i, Ai = Bi. This is equivalent to saying the {path} of Property A is equivalent to the {path} of Property B.

Path of a Property component (narrower) “narrower” path iff the path length of Property B is less than the Path length of Property A, and for each value of i, where i is less than the path length of B, Ai = Bi. This is equivalent to saying that Property A is scoped to a more specific sub part of the resource property. For example, if the {path} of Property A is “tns:a/b” and the {path} of Property B is “tns:a”, we say that Property A has narrower scope, it describes or constrains only the descendant nodes of the resource property “tns:a” rooted at the element “b”. Property B has a “broader” (or less narrow) path, in that it pertains to the entire resource property “tns:a”.

Operation <Operation name=”xs:NCName” inputMessage=“xs:QName” ? outputMessage=”xs:QName” ? idempotent=”xs:Boolean” ? {anyAttribute}* > <documentation>? {any} </Operation> The properties of an Operation component are as follows: {name} the name of the wsdl operation to which the Operation applies. This must correspond to a name of an operation defined for the WSDL interface identified by the {interface} property of the Operation component. {interface} a QName of a WSDL 1.1 portType or WSDL 2.0 interface to which the Operation component is associated. {operation} the wsdl operation to which this Operation component applies. It is identified by the {interface} scoping the wsdl portType or interface and the {name} identifying the operation name within that wsdl portType or interface. {idempotent} an xs:boolean indicating, if true, that the wsdl operation corresponding to this Operation component is idempotent.