Schema for .NET My Services Infrastructure types including security related types, system document, message headers, etc. Copyright (c) 2001 Microsoft Corporation. All rights reserved. This element encapsulates a subject that includes a userId, and a combined application and platformId. The subject element is matched against the incoming message to determine which role, if any, is to be used to authorize and scope continued message processing. The match algorithm is very simple. The userId in the message chooses the set of matching subjects. Once this set of subjects is identified, a test for subjects containing credType attributes is done relative to the credType passed in the license. Matching subject entries remain. If no subjects match, all subjects containing credType are discarded; only those subjects that do not contain credType are kept. Then the combined platform ID and application ID select a matching subject. Matching subject entries remain. If no subjects match, all subjects containing appAndPlatformId attributes are discarded; only those subjects that do not contain this attribute are kept. These remaining subjects are considered to represent the set of possible roles to be used for the request. The referenced roleDefinitions are extracted from the roleMap and sorted; only the highest priority roleDefinition is kept. This ID represents an authenticated userId. It must always be specified. This optional attribute specifies a credential type value which represents the type of credential used to authenticate the userId. During a match operation, this value may be used to further qualify the set of subjects that match in the userId dimension. This optional attribute specifies the authenticated ID of an application-platform combination. For example, the PUID of calendar@microsoft.com represents the calendar application at Microsoft. The PUID of office@windows represents the Office application running on the Microsoft® Windows® platform. This type defines a role record that defines a matching subject, an optional scope reference, the roleTemplate for this entry, and some maintenance information. This element specifies optional notes that may be used to specify the reasoning behind adding this role to the roleList. This optional element specifies a time after which the subject entry is no longer considered valid for matching purposes. If this element is missing, the subject entry does not expire. This attribute specifies the scope within this document that is in effect for this matching authorizationEntry. This item specifies the name of the roleTemplate in the service's roleMap to which this role is bound. This element encapsulates a roleList for the identity. This is a first-class root document type that specifies the sharing allowed over the content document. This element encapsulates all the elements that make up a roleMap, which include document class relative roleTemplate, priority, name, method, and per-method scope. An individual roleTemplate defines the maximum scope of information and the methods allowed to access that information for each request mapped into the template. This element defines a scope which may be referred to by roles within this roleMap to indicate what portions of the document are visible to this role for the specified method. This element encapsulates the definition of a role. The attribute set for this element includes the document class that this roleTemplate refers to, the name of the roleTemplate, and the priority of the roleTemplate. This element contains a description of this roleTemplate that specifies the capabilities a caller will have when accessing information through this role. This element specifies the methods available within this roleTemplate by name and by scope. When a subject maps to a roleTemplate, the method in the request must match one of these elements for the message to continue to flow. If the method exists, the data available to the method is a function of the scope referenced by this method, combined with an optional scope referenced by the role defined in the roleList. This element specifies the name of the method. This attribute specifies the scope within this document that is in effect for this method. This element specifies the name of the role. This element is a SOAP-SEC compliant license that identifies the sender of this message to the recipient. The contents are encoded and encrypted using algorithms demonstrated and documented in the .NET My Services client access runtime. This license includes all elements needed to identify the sender of the .NET My Services message. An identity license must be present in all .NET service requests and is always contained within a SOAP-SEC licenses tag. This element specifies the identity of the sender of the message in the form of a Kerberos AP request:

{servicePrincipalName, [{Uk, Kx3, {A/Y, g}}Kh ]Kp , {T}Kx3, otherKerberosStuff }

which is easily transformed into:

userId: The user on whose behalf this message is being sent. The user can be an actual user, or an identity representing an arbitrary user account. This value is extractable as a Passport Unique ID (PUID).
appAndPlatformId: The PUID that represents the licenses granted to an application, and a platform on which the application runs.

This element is a SOAP-SEC compliant license that does two things:

When presented to a .NET service in a SOAP-SEC licenses tag during a .NET My Services request message, it specifies to the .NET service the authorized role of the sender of the message. The .NET service is free to accept this license when it regards the license as valid. If .NET My Services does not regard the license as valid, it is free to ignore the license, perform its own role evaluation, and possibly issue a new license in a response header.
.NET services are the grantors of this type of license and the content is totally opaque to the sender.
When this license appears in a SOAP-SEC licenses tag during a .NET My Services response message, this license is considered issued to the recipient for an undetermined amount of time. On a subsequent request, this license may be presented and may allow accelerated processing of the request.

The request header is used to specify request-specific arguments including the service being addressed, the method being accessed, the document being manipulated, how the response should be processed, and key information used to locate the document (including the PUID that owns the document, the document instance, and the cluster). The request header must occur in each request message. This element specifies key information used to zoom in on the document being manipulated. This information includes the PUID that owns the document, the instance ID of the document, and the cluster or partition key used to locate the machine resources that hold the document.

In certain situations, a client will want to send the same message to a number a instances of a particular service. To do this, the client can repeat this element multiple times. The cluster attributes in all elements must match each other, but the puid and instance attributes may differ. A unique response message is generated for each key specified.

The entire contents of this element come from the .NET Services service. This element specifies the PUID of the entity that "owns" the service being accessed. This element specifies the particular instance of the service for the ID being accessed. For example, if a given ID is provisioned with multiple .NET Calendar documents on the same cluster and in the same data center, the documents would differ only by this value. This element specifies information used by the .NET My Services system to locate the document on a particular back-end server or database. It is used as the virtual partition key for the document being addressed. This technique is preferable to computing this partition key based on some hash of the puid/instance. This element contains the name of the service being accessed by this request message. For example, to access the .NET Profile service, this attribute will have the value "myProfile". This element specifies the document class being accessed by this message. Valid values include:

content: the main content document
roleList: the authorization list document
system: the global system document
policy: TBD

This element specifies the method being accessed within the service. For example, to access one of the standard methods, valid values would include:

insertRequest
deleteRequest
replaceRequest
updateRequest
queryRequest

This element, coupled with rev/via, controls how a response to this request is generated and delivered. Valid values include:

always: Always generate a response message and deliver to rev/via.
never: Never generate a response message.
faultOnly: Generate a response message, but only if the request message results in a fault message.

This element contains information related to the response message. In current implementations, this information is limited to the role that was computed for the sender, assuming the original request was formed well enough to progress this far through the .NET My Services message-processing system. This header element must be present in all response messages. This optional attribute contains the role that was computed for the sender. If the original request message was malformed and did not make it far enough through the message processor to compute a value for this element, the role attribute will be missing from the response header. This situation typically occurs whenever the identity header is so malformed that the basic set of sender identity PUIDs cannot be extracted from the service ticket. The echoBack header is a header element that applications can use to pass additional correlation data or out-of-band data between the request and the response recipients. It is considered bad form to use this header during synchronous, piggy-backed responses (because in that situation, the call stack should be all that is required to keep sufficient context), or during cases where responses are not generated or are only generated during fault conditions. If the UUIDs in the path/id and path/relatesTo are insufficient to provide correlation data, the echoBack header can be used to pass arbitrarily structured XML between the service requester and the recipient of the associated .NET My Services response.

.NET services make no attempt to process or inspect the contents of this header. They simply transmit the header from the request message to the response message and treat it as an opaque body of XML. This element defines version information describing this instance of the .NET service. This element defines major, minor, and build number version information. This element defines the major product release string (for example, ".NET My Services Beta 1".) This element defines the class of the service to differentiate between different implementations. This attribute specifies the major version number of the .NET service. This attribute specifies the minor version number of the .NET service. This attribute specifies the build number of the .NET service. This attribute specifies the quick-fix engineering (QFE) version number of the .NET service. This element defines the date and time that the .NET My Services system was built. The time is always in UTC (Z-relative) form. This element defines details of the build, including the machine that generated the build, the branch ID of the software that contributed to the build, the type of build (chk/fre), and whether the build was generated by an official build-release process. This attribute specifies the machine that generated the build. This attribute specifies the software branch ID for the source code that contributed to this build. This attribute specifies the type of build. A value of chk indicates that this is a checked or debug build. A value of fre indicates that this is a retail build. This attribute indicates whether the build was produced by an official build process (value of yes), or an unofficial process (value of no). This element defines the methodMap. While it is true that, in most cases, the roleMap section contains a definitive list of methods, these methods are likely to be scattered about the roleMap in various templates. This section contains the definitive, non-duplicated list of methods available within the service. This element defines a method that is available within this service. This attribute specifies the name of a method available within this service. This element defines the various schemas that define the data structures and shape of information managed by this service. Each schema is defined by its namespace URI, its location, and a preferred namespace alias. This element defines a schema that defines data structures and the shape of information managed by this service. Multiple schema elements exist for each service, one for each logical grouping of information exposed by the service. This attribute specifies the namespace URI of this schema. This attribute specifies the location (in the form of a URI) of the resource containing the schema. When a schema is reachable through a variety of URIs, one schema element will exist for each location. This attribute specifies the preferred alias to be used, if possible, when manipulating information covered by this schema in the context of this service. This element defines the wsdlMap for this service. This map includes the location of WSDL documents, DISCO documents, and WSIL documents for this Web service. These documents are used by applications to understand the format of messages that may be sent to the various services. This element is used to specify the location of a WSDL file for this service. Multiple entries may exist pointing to the same file hosted in multiple locations, or to variations on the content within the WSDL files. This attribute is a URI that specifies the location of the WSDL file. This element is used to specify the location of a DISCO file for this service. Multiple entries may exist pointing to the same file hosted in multiple locations, or to variations on the content within the DISCO files. This attribute is a URI that specifies the location of the DISCO file. This element is used to specify the location of a WSIL file for this service. Multiple entries may exist pointing to the same file hosted in multiple locations, or to variations on the content within the WSIL files. This attribute is a URI that specifies the location of the WSIL file. This is the response action that is to be taken by the client upon receiving this fault message. Contents of this element can be:

correct: A correctable error was detected. The client should reform the request message, correcting the noted error, and resubmit the message. If the client is unable to correct the message, the client should accept the failure condition and execute approriate recovery logic.
retry: A transient error has occured. The client should resubmit the message (ensuring that a new message ID is used).
giveUp: An uncorrectable error was detected. The client should accept the failure condition and execue appropriate recovery logic.

When a request is being processed by a service, it may be traveling through multiple sections of the service code. The faultChain element contains a list of errors if there are multiple errors along the processing path of a message. Because a section of the service or the server may overwrite the error code with a more general error, this list gives a history of failures for this particular request.

faultChain contains multiple fault elements. Each fault element contains details about an error condition which this request has caused to occur during its processing. This element provides details about a failure condition that was encountered during the processing of a .NET My Services message.

code and shortDescription are two of the child elements this element can have. These elements contain pairs defined by the error code documentation to help client applications determine the reason for a failure of a message. The longDescription element child of this element contains context-based information about the error. For example, the shortDescription element may contain "Syntax Error", whereas this element indicates what the real syntax error was.

Users of services and client application developers should depend only on the code element value within a fault to determine what happened. Descriptions are not a part of the contract.

Order of fault elements may change and the order of a set of faults for a certain message is not a part of the contract between a client and a .NET My Services server; only the recommended action to fix the problem is. Application developers should consider the fact that the order of faults may change from service to service, and from version to version; there is no requirement to keep the order and descriptions. This is done on purpose, in order to simplify client application development. This element contains the hexadecimal error code for this fault entry in the fault chain. This element contains the short description for this fault entry in the fault chain. This element contains the long and context-sensitive description for this fault entry in the fault chain.