OASIS Service Provisioning Markup Language (SPML) Version 2

Committee Draft 1.0
2005 September 14

Document identifier: pstc-spml2-cd-01.pdf

Location: http://www.oasis-open.org/committees/provision/docs/

Send comments to: pstc-comment@lists.oasis-open.org

Editor:

Gary Cole, Sun Microsystems (Gary.P.Cole@Sun.com)

Contributors:

Jeff Bohren, BMC

Robert Boucher, CA

Doron Cohen, BMC

Gary Cole, Sun Microsystems

Cal Collingham, CA

Rami Elron, BMC

Marco Fanti, Thor Technologies

Ian Glazer, IBM

James Hu, HP

Ron Jacobsen, CA

Jeff Larson, Sun Microsystems

Hal Lockhart, BEA

Prateek Mishra, Oracle Corporation

Martin Raepple, SAP

Darran Rolls, Sun Microsystems

Kent Spaulding, Sun Microsystems

Gavenraj Sodhi, CA

Cory Williams, IBM

Gerry Woods, SOA Software

Abstract:

This specification defines the concepts and operations of an XML-based provisioning request-and-response protocol.

Status:

This is a candidate Committee Specification that is undergoing a vote of the OASIS membership in pursuit of OASIS Standard status.

If you are on the provision list for committee members, send comments there. If you are not on that list, subscribe to the provision-comment@lists.oasis-open.org list and send comments there. To subscribe, send an email message to provision-comment-request@lists.oasis-open.org with the word "subscribe" as the body of the message.

Copyright (C) OASIS Open 2005. All Rights Reserved.
Table of contents

1      Introduction. 7

1.1     Purpose. 7

1.2     Organization. 7

1.3     Audience. 7

1.4     Notation. 8

1.4.1         Normative sections. 8

1.4.2         Normative terms. 8

1.4.3         Typographical conventions. 8

1.4.4         Namespaces. 9

2      Concepts. 10

2.1     Domain Model 10

2.1.1         Requestor 10

2.1.2         Provider 11

2.1.3         Target 11

2.1.3.1       Target Schema. 11

2.1.3.2       Supported Schema Entities. 12

2.1.3.3       Capabilities. 12

2.1.4         Provisioning Service Object (PSO) 13

2.2     Core Protocol 13

2.3     Profile. 13

3      Protocol 14

3.1     Request/Response Model 14

3.1.1         Conversational flow. 16

3.1.2         Status and Error codes. 16

3.1.2.1       Status (normative) 17

3.1.2.2       Error (normative) 17

3.1.2.3       Error Message (normative) 18

3.1.3         Synchronous and asynchronous operations. 19

3.1.3.1       ExecutionMode attribute. 19

3.1.3.2       Async Capability. 19

3.1.3.3       Determining execution mode. 20

3.1.3.4       Results of asynchronous operations (normative) 22

3.1.4         Individual and batch requests. 22

3.2     Identifiers. 22

3.2.1         Request Identifier (normative) 23

3.2.2         Target Identifier (normative) 23

3.2.3         PSO Identifier (normative) 24

3.3     Selection. 26

3.3.1         QueryClauseType. 26

3.3.2         Logical Operators. 26

3.3.3         SelectionType. 27

3.3.3.1       SelectionType in a Request (normative) 27

3.3.3.2       SelectionType Processing (normative) 28

3.3.3.3       SelectionType Errors (normative) 29

3.3.4         SearchQueryType. 29

3.3.4.1       SearchQueryType in a Request (normative) 30

3.3.4.2       SearchQueryType Errors (normative) 31

3.4     CapabilityData. 32

3.4.1         CapabilityDataType. 32

3.4.1.1       CapabilityData in a Request (normative) 33

3.4.1.2       CapabilityData Processing (normative) 34

3.4.1.3       CapabilityData Errors (normative) 37

3.4.1.4       CapabilityData in a Response (normative) 37

3.5     Transactional Semantics. 39

3.6     Operations. 39

3.6.1         Core Operations. 39

3.6.1.1       listTargets. 39

3.6.1.2       add. 50

3.6.1.3       lookup. 56

3.6.1.4       modify. 61

3.6.1.5       delete. 71

3.6.2         Async Capability. 74

3.6.2.1       cancel 75

3.6.2.2       status. 77

3.6.3         Batch Capability. 83

3.6.3.1       batch. 83

3.6.4         Bulk Capability. 90

3.6.4.1       bulkModify. 90

3.6.4.2       bulkDelete. 92

3.6.5         Password Capability. 95

3.6.5.1       setPassword. 95

3.6.5.2       expirePassword. 97

3.6.5.3       resetPassword. 98

3.6.5.4       validatePassword. 100

3.6.6         Reference Capability. 103

3.6.6.1       Reference Definitions. 105

3.6.6.2       References. 106

3.6.6.3       Complex References. 106

3.6.6.4       Reference CapabilityData in a Request (normative) 112

3.6.6.5       Reference CapabilityData Processing (normative) 113

3.6.6.6       Reference CapabilityData Errors (normative) 115

3.6.6.7       Reference CapabilityData in a Response (normative) 115

3.6.7         Search Capability. 116

3.6.7.1       search. 117

3.6.7.2       iterate. 123

3.6.7.3       closeIterator 129

3.6.8         Suspend Capability. 133

3.6.8.1       suspend. 133

3.6.8.2       resume. 135

3.6.8.3       active. 137

3.6.9         Updates Capability. 140

3.6.9.1       updates. 141

3.6.9.2       iterate. 147

3.6.9.3       closeIterator 152

3.7     Custom Capabilities. 157

4      Conformance (normative) 158

4.1     Core operations and schema are mandatory. 158

4.2     Standard capabilities are optional 158

4.3     Custom capabilities must not conflict 158

4.4     Capability Support is all-or-nothing. 159

4.5     Capability-specific data. 159

5      Security Considerations. 160

5.1     Use of SSL 3.0 or TLS 1.0. 160

5.2     Authentication. 160

5.3     Message Integrity. 160

5.4     Message Confidentiality. 160

Appendix A.      Core XSD. 161

Appendix A. Async Capability XSD. 168

Appendix B. Batch Capability XSD. 170

Appendix C. Bulk Capability XSD. 172

Appendix D. Password Capability XSD. 174

Appendix E. Reference Capability XSD. 176

Appendix F. Search Capability XSD. 178

Appendix G. Suspend Capability XSD. 181

Appendix H. Updates Capability XSD. 183

Appendix I. Document References. 186

Appendix J. Acknowledgments. 188

Appendix K. Notices. 189


1.1      Purpose

This specification defines the concepts and operations of Version 2 of the Service Provisioning Markup Language (SPML).  SPML is an XML-based provisioning request-and-response protocol.

1.2      Organization

The body of this specification is organized into three major sections: Concepts, Protocol and Conformance.

·         The Concepts section introduces the main ideas in SPMLv2. Subsections highlight significant features that later sections will discuss in more detail.

·         The Protocol section first presents an overview of protocol features and then discusses the purpose and behavior of each protocol operation. The core operations are presented in an order that permits a continuing set of examples. Subsequent sections present optional operations.

Each section that describes an operation includes:

-          The relevant XML Schema

-          A normative subsection that describes the request for the operation

-          A normative subsection that describes the response to the operation

-          A non-normative sub-section that discusses examples of the operation

·         The Conformance section describes the aspects of this protocol that a requestor or provider must support in order to be considered conformant.

·         A Security and Privacy Considerations section describes risks that an implementer of this protocol should weigh in deciding how to deploy this protocol in a specific environment.

Appendices contain additional information that supports the specification, including references to other documents.

1.3      Audience

The PSTC intends this specification to meet the needs of several audiences.

One group of readers will want to know: "What is SPML?”
A reader of this type should pay special attention to the
Concepts section.

A second group of readers will want to know: "How would I use SPML?"
A reader of this type should read the
Protocol section
(with special attention to the examples).

A third group of readers will want to know: "How must I implement SPML?"
A reader of this type must read the
Protocol section
(with special attention to normative request and response sub-sections).

A reader who is already familiar with SPML 1.0 will want to know: “What is new in SPMLv2?”
A reader of this type should read the
Concepts section thoroughly.

1.4      Notation

1.4.1      Normative sections

Normative sections of this specification are labeled as such.  The title of a normative section will contain the word “normative” in parentheses, as in the following title: “Syntax (normative)”.

1.4.2      Normative terms

This specification contains schema that conforms to W3C XML Schema and contains normative text that describes the syntax and semantics of XML-encoded policy statements.

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in IETF RFC 2119 [RFC2119]

"they MUST only be used where it is actually required for interoperation or to limit behavior which has potential for causing harm (e.g., limiting retransmissions)"

These keywords are capitalized when used to unambiguously specify requirements of the protocol or application features and behavior that affect the interoperability and security of implementations. When these words are not capitalized, they are meant in their natural-language sense.

1.4.3      Typographical conventions

This specification uses the following typographical conventions in text:

Format

Description

Indicates

xmlName

monospace font

The name of an XML attribute, element or type.

attributeName

monospace font
surrounded by
double quotes

An instance of an XML attribute.

‘attributeValue’

monospace font
surrounded by
double quotes

A literal value (of type string).

attributeName=’value’

monospace font name
followed by equals sign and value
surrounded by
single quotes

An instance of an XML attribute value.

Read as “a value of (value) specified for an instance of the (attributeName) attribute.”

{XmlTypeName}
 
or
{ns:XmlTypeName}

monospace font
surrounded by
curly braces

The name of an XML type.

<xmlElement> or
<ns:xmlElement>

monospace font
surrounded by
<>

An instance of an XML element.

Terms in italic boldface are intended to have the meaning defined in the Glossary.

Listings of SPML schemas appear like this.

 

Example code listings appear like this.

1.4.4      Namespaces

Conventional XML namespace prefixes are used throughout the listings in this specification to stand for their respective namespaces as follows, whether or not a namespace declaration is present in the example:

·         The prefix dsml: stands for the Directory Services Markup Language namespace [DSML].

·         The prefix xsd: stands for the W3C XML Schema namespace [XSD].

·         The prefix spml: stands for the SPMLv2 Core XSD namespace
[SPMLv2-CORE].

·         The prefix spmlasync: stands for the SPMLv2 Async Capability XSD namespace.
[SPMLv2-ASYNC].

·         The prefix spmlbatch: stands for the SPMLv2 Batch Capability XSD namespace
[SPMLv2-BATCH].

·         The prefix spmlbulk: stands for the SPMLv2 Bulk Capability XSD namespace
[SPMLv2-BULK].

·         The prefix spmlpass: stands for the SPMLv2 Password Capability XSD namespace
 [SPMLv2-PASS].

·         The prefix spmlref: stands for the SPMLv2 Reference Capability XSD namespace
 [SPMLv2-REF].

·         The prefix spmlsearch: stands for the SPMLv2 Search Capability XSD namespace
 [SPMLv2-SEARCH].

·         The prefix spmlsuspend: stands for the SPMLv2 Suspend Capability XSD namespace
 [SPMLv2-SUSPEND].

·         The prefix spmlupdates: stands for the SPMLv2 Updates Capability XSD namespace
 [SPMLv2-UPDATES].


2        Concepts

SPML Version 2 (SPMLv2) builds on the concepts defined in SPML Version 1. 

The basic roles of Requesting Authority (RA) and Provisioning Service Provider (PSP) are unchanged.  The core protocol continues to define the basis for interoperable management of Provisioning Service Objects (PSO).  However, the concept of Provisioning Service Target (PST) takes on new importance in SPMLv2.

2.1      Domain Model

The following section describes the main conceptual elements of the SPML domain model.  The Entity Relationship Diagram (ERD) in Figure 1 shows the basic relationships between these elements.

Figure 1. Domain model elements

2.1.1      Requestor

A Requesting Authority (RA) or requestor is a software component that issues well-formed SPML requests to a Provisioning Service Provider.  Examples of requestors include:

·         Portal applications that broker the subscription of client requests to system resources

·         Service subscription interfaces within an Application Service Provider

Trust relationship.  In an end-to-end integrated provisioning scenario, any component that issues an SPML request is said to be operating as a requestor.  This description assumes that the requestor and its provider have established a trust relationship between them.  The details of establishing and maintaining this trust relationship are beyond the scope of this specification. 

2.1.2      Provider

A Provisioning Service Provider (PSP) or provider is a software component that listens for, processes, and returns the results for well-formed SPML requests from a known requestor.  For example, an installation of an Identity Management system could serve as a provider.

Trust relationship.  In an end-to-end integrated provisioning scenario, any component that receives and processes an SPML request is said to be operating as a provider.  This description assumes that the provider and its requestor have established a trust relationship between them.  The details of establishing and maintaining this trust relationship are beyond the scope of this specification.

2.1.3      Target

A Provisioning Service Target (PST) or target represents a destination or endpoint that a provider makes available for provisioning actions.

A target is not a provider.  A requestor asks a provider to act upon objects that the provider manages.  Each target is a container for objects that a provider manages.

A target may not be an actual endpoint. A target may represent a traditional user account source (such as a Windows NT domain or a directory service instance), or a target may represent an abstract collection of endpoints.

Every provider exposes at least one target.  Each target represents a destination or endpoint (e.g., a system, application or service—or a set of systems, applications, and services) to which the provider can provision (e.g., create or modify accounts).

A target is a special, top-level object that:

·         A requestor can discover from the provider

·         No requestor can add, modify, delete or otherwise act upon

·         May contain any number of provisioning service objects (PSO) upon which a requestor may act

·         May contain a schema that defines the XML structure of the provisioning service objects (PSO)  that the target may contain

·         May define which schema entities the target supports

·         May expose capabilities:

-          That apply to every supported schema entity

-          That apply only to specific schema entities

The SPMLv2 model does not restrict a provider’s targets other than to specify that:

·         A provider (PSP) must uniquely identify each target that it exposes.

·         A provider must uniquely identify each object (PSO) that a target contains.

·         Exactly one target must contain each object (PSO) that the provider manages.

2.1.3.1Target Schema

The schema for each target defines the XML structure of the objects (PSO) that the target may contain.

SPMLv2 does not specify a required format for the target schema. For example, a target schema could be XML Schema [XSD] or (a target schema could be) SPML1.0 Schema [SPMLv2-Profile-DSML].

Each target schema includes a schema namespace. The schema namespace indicates (to any requestor that recognizes the schema namespace) how to interpret the schema.

A provider must present any object (to a requestor) as XML that is valid according to the schema of the target that contains the object. A requestor must accept and manipulate, as XML that is valid according to the schema of the target, any object that a target contains.

2.1.3.2Supported Schema Entities

A target may declare that it supports only a subset of the entities (e.g., object classes or top-level elements) in its schema. A target that does not declare such a subset is assumed to support every entity in its schema.

A provider must implement the basic SPML operations for any object that is an instance of a supported schema entity (i.e., a schema entity that the target containing the object supports).

2.1.3.3Capabilities

A target may also support a set of capabilities.  Each capability defines optional operations or semantics (in addition to the basic operations that the target must support for each supported schema entity).

A capability must be either "standard" or "custom":

·         The OASIS PSTC defines each standard capability in an SPML namespace.
See the section titled “
Namespaces”.

·         Anyone may define a custom capability in another namespace.

A target may support a capability for all of its supported schema entities or (a target may support a capability) only for specific subset of its supported schema entities.  Each capability may specify any number of supported schema entities to which it applies.  A capability that does not specify at least one supported schema entity implicitly declares that the capability applies to every schema entity that the target supports.

Capability-defined operations. If a capability defines an operation and if the target supports that capability for a schema entity of which an object is an instance, then the provider must support that optional operation for that object.  For example, if a target supports the Password Capability for User objects (but not for Group objects), then a requestor may ask the provider to perform the ‘resetPassword’ operation for any User object (but the provider will fail any request to ‘resetPassword’ for a Group).

If a capability defines more than one operation and a target supports that capability (for any set of schema entities), then the provider must support (for any instance of any of those schema entities on that target) every operation that the capability defines.  See the section titled "Conformance".

Capability-specific data.  A capability may imply that data specific to that capability may be associated with an object.  Capability-specific data are not part of the schema-defined data of an object.  SPML operations handle capability-specific data separately from schema-defined data.  Any capability that implies capability-specific data must define the structure of that data.
See the section titled "
CapabilityData".

Of the capabilities that SPML defines, only one capability actually implies that capability-specific data may be associated with an object.  The Reference Capability implies that an object (that is an instance of a schema entity for which the provider supports the Reference Capability) may contain any number of references to other objects.  The Reference Capability defines the structure of a reference element.  For more information, see the section titled "Reference Capability".

2.1.4      Provisioning Service Object (PSO)

A Provisioning Service Object (PSO), sometimes simply called an object, represents a data entity or an information object on a target.  For example, a provider would represent as an object each account that the provider manages.

NOTE: Within this document, the term “object” (unless otherwise qualified) refers to a PSO.

Every object is contained by exactly one target. Each object has a unique identifier (PSO-ID).

2.2      Core Protocol

SPMLv2 retains the SPML1.0 concept of a “core protocol”.  The SPMLv2 Core XSD defines:

·         Basic operations (such as add, lookup, modify and delete)

·         Basic and extensible data types and elements

·         The means to expose individual targets and optional operations

The SPMLv2 Core XSD also defines modal mechanisms that allow a requestor to:

·         Specify that a requested operation must be executed asynchronously
(or to specify that a requested operation must be executed synchronously)

·         Recognize that a provider has chosen to execute an operation asynchronously

·         Obtain the status (and any result) of an asynchronous request

·         Stop execution of an asynchronous request

Conformant SPMLv2 implementations must support the core protocol, including:

·         The new listTargets operation

·         The basic operations for every schema entity that a target supports

·         The modal mechanisms for asynchronous operations

(For more information, see the section titled “Conformance).

2.3      Profile

SPMLv2 defines two “profiles” in which a requestor and provider may exchange SPML protocol:

·         XML Schema as defined in the “SPMLv2 XSD Profile” [SPMLv2-Profile-XSD].

·         DSMLv2 as defined in the “SPMLv2 DSMLv2 Profile” [SPMLv2-Profile-DSML].

A requestor and a provider may exchange SPML protocol in any profile to which they agree.

SPML 1.0 defined file bindings and SOAP bindings that assumed the SPML1.0 Schema for DSML [SPML-Bind].  The SPMLv2 DSMLv2 Profile provides a degree of backward compatibility with SPML 1.0.  The DSMLv2 profile supports a schema model similar to that of SPML 1.0.

The DSMLv2 Profile may be more convenient for applications that access mainly targets that are LDAP or X500 directory services.  The XSD Profile may be more convenient for applications that access mainly targets that are web services.


3        Protocol

General Aspects. The general model adopted by this protocol is that a requestor (client) asks a provider (server) to perform operations. In the simplest case, each request for an SPML operation is processed individually and is processed synchronously.  The first sub-section, “Request/Response Model”, presents this model and discusses mechanisms that govern asynchronous execution. Sub-sections such as “Identifiers”, “Selection”, “CapabilityData” and “Transactional Semantics” also describe aspects of the protocol that apply to every operation.

Core Operations. In order to encourage adoption of this standard, this specification minimizes the set of operations that a provider must implement. The Core Operations section discusses these required operations.

Standard Capabilities. This specification also defines optional operations.  Some operations are optional (rather than required) because those operations may be more difficult for a provider to implement for certain kinds of targets. Some operations are optional because those operations may apply only to specific types of objects on a target. This specification defines a set of standard capabilities, each of which groups optional operations that are functionally related. The remainder of the Operations section discusses optional operations (such as search) that are associated with SPMLv2’s standard capabilities.
Custom Capabilities. The capability mechanism in SPMLv2 is open and allows an individual provider (or any third party) to define additional custom capabilities.  See the sub-section titled "Custom Capabilities".

3.1      Request/Response Model

The general model adopted by this protocol is that a requestor (client) asks a provider (server) to perform an operation. A requestor asks a provider to perform an operation by sending to the provider an SPML request that describes the operation. The provider examines the request and, if the provider determines that the request is valid, the provider does whatever is necessary to implement the requested operation. The provider also returns to the requestor an SPML response that details any status or error that pertains to the request.

 

   <complexType name="ExtensibleType">

      <sequence>

         <any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>

      </sequence>

      <anyAttribute namespace="##other" processContents="lax"/>

   </complexType>

 

   <simpleType name="ExecutionModeType">

      <restriction base="string">

         <enumeration value="synchronous"/>

         <enumeration value="asynchronous"/>

      </restriction>

   </simpleType>

 

   <complexType name="CapabilityDataType">

      <complexContent>

         <extension base="spml:ExtensibleType">

            <annotation>

               <documentation>Contains elements specific to a capability.</documentation>

            </annotation>

            <attribute name="mustUnderstand" type="boolean" use="optional"/>

            <attribute name="capabilityURI" type="anyURI"/>

         </extension>

      </complexContent>

   </complexType>

 

   <complexType name="RequestType">

      <complexContent>

         <extension base="spml:ExtensibleType">

            <attribute name="requestID" type="xsd:ID" use="optional"/>

            <attribute name="executionMode" type="spml:ExecutionModeType" use="optional"/>

         </extension>

      </complexContent>

   </complexType>

 

   <simpleType name="StatusCodeType">

      <restriction base="string">

         <enumeration value="success"/>

         <enumeration value="failure"/>

         <enumeration value="pending"/>

      </restriction>

   </simpleType>

 

   <simpleType name="ErrorCode">

      <restriction base="string">

         <enumeration value="malformedRequest"/>

         <enumeration value="unsupportedOperation"/>

         <enumeration value="unsupportedIdentifierType"/>

         <enumeration value="noSuchIdentifier"/>

         <enumeration value="customError"/>

         <enumeration value="unsupportedExecutionMode"/>

         <enumeration value="invalidContainment"/>

         <enumeration value="unsupportedSelectionType"/>

         <enumeration value="resultSetTooLarge"/>

         <enumeration value="unsupportedProfile"/>

         <enumeration value="invalidIdentifier"/>

         <enumeration value="alreadyExists"/>

         <enumeration value="containerNotEmpty"/>

      </restriction>

   </simpleType>

 

   <simpleType name="ReturnDataType">

      <restriction base="string">

         <enumeration value="identifier"/>

         <enumeration value="data"/>

         <enumeration value="everything"/>

      </restriction>

   </simpleType>

 

   <complexType name="ResponseType">

      <complexContent>

         <extension base="spml:ExtensibleType">

            <sequence>

               <element name="errorMessage" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>

            </sequence>

            <attribute name="status" type="spml:StatusCodeType" use="required"/>

            <attribute name="requestID" type="xsd:ID" use="optional"/>

            <attribute name="error" type="spml:ErrorCode" use="optional"/>

         </extension>

      </complexContent>

   </complexType>

 

The following subsections describe aspects of this request/response model in more detail:

·         the exchange of requests and responses between requestor and provider

·         synchronous and asynchronous execution of operations

·         individual and batch requests

3.1.1      Conversational flow

A requestor asks a provider to do something by issuing an SPML request. A provider responds exactly once to each request. Therefore, the simplest conversation (i.e., pattern of exchange) between a requestor and a provider is an orderly alternation of request and response. However, the SPML protocol does not require this. A requestor may issue any number of concurrent requests to a single provider.  A requestor may issue any number of concurrent requests to multiple providers.

Recommend requestID. Each SPML request should specify a reasonably unique identifier as the value of “requestID”. See the section titled "Request Identifier (normative)”.  This allows a requestor to control the identifier for each requested operation and (also allows the requestor) to match each response to the corresponding request without relying on the transport protocol that underlies the SPML protocol exchange.

3.1.2      Status and Error codes

A provider’s response always specifies a “status”.  This value tells the requestor what the provider did with (the operation that was described by) the corresponding request.

If a provider’s response specifies “status=’failure’”, then the provider’s response must also specify an “error”.  This value tells the requestor what type of problem prevented the provider from executing (the operation that was described by) the corresponding request.

The “status” and “error” attributes of a response apply to (the operation that is described by) the corresponding request.  This is straightforward for most requests.  The status and batch operations present the only subtleties. 

·         A status request asks for the status of another operation that the provider is already executing asynchronously.  See the section titled "Synchronous and asynchronous operations” below.  A status response has status and error attributes that tell the requestor what happened to the status request itself.  However, the response to a successful status operation also contains a nested response that tells what has happened to the operation that the provider is executing asynchronously.

·         A batch request contains nested requests (each of which describes an operation).  The response to a batch request contains nested responses (each of which corresponds to a request that was nested in the batch request).  See the section titled "Individual and batch requests” below.

3.1.2.1Status (normative)

A provider’s response MUST specify “status” as one of the following values: ‘success’, ‘failure’ or ‘pending’.

·         A response that specifies “status=’success’”
indicates that the provider has completed the requested operation.
In this case, the response contains any result of the operation
and the response MUST NOT specify
error (see below).

·         A response that specifies “status=’failure’”
indicates that the provider could not complete the requested operation. 
In this case, the response MUST specify an appropriate value of
error (see below).

·         A response that specifies “status=’pending’”
indicates that the provider will execute the requested operation asynchronously
(see “
Synchronous and asynchronous operations” below). 
In this case, the response acknowledges the request and contains the
“requestID” value that identifies the asynchronous operation.

3.1.2.2Error (normative)

A response that specifies status=’failure’” MUST specify an appropriate value of “error”.

·         A response that specifies “error=’malformedRequest’”
indicates that the provider could not interpret the request.
This includes, but is not limited to, parse errors.

·         A response that specifies “error=’unsupportedOperation’”
indicates that the provider does not support the operation that the request specified.

·         A response that specifies “error=’unsupportedIdentifierType’”
indicates that the provider does not support the type of identifier specified in the request.

·         A response that specifies “error=’noSuchIdentifier’”
indicates that the provider (supports the type of identifier specified in the request,
but the provider) cannot find the object to which an identifier refers.

·         A response that specifies “error=’unsupportedExecutionMode’”
indicates that the provider does not support the requested mode of execution.

·         A response that specifies “error=’invalidContainment’”
indicates that the provider cannot add the specified object to the specified container.

-          The request may have specified as container an object that does not exist.

-          The request may have specified as container an object that is not a valid container.
The target schema implicitly or explicitly declares each supported schema entity. 
An explicit declaration of a supported schema entity specifies
whether an instance of that schema entity may contain other objects.

-          The request may have specified a container that is may not contain the specified object.
The target (or a system or application that underlies the target) may restrict the types of objects that the provider can add to the specified container.  The target (or a system or application that underlies the target) may restrict the containers to which the provider can add the specified object.

·         A response that specifies “error=’resultSetTooLarge’” indicates that the provider cannot return (or cannot queue for subsequent iteration—as in the case of an overlarge search result) the entire result of an operation. 

In this case, the requestor may be able to refine the request so as to produce a smaller result.  For example, a requestor might break a single search operation into several search requests, each of which selects a sub-range of the original (overlarge) search result.

·         A response that specifies “error=’customError’” indicates that the provider has encountered an error that none of the standard error code values describes. 
In this case, the provider’s response SHOULD provide error information in a format that is available to the requestor.  SPMLv2 does not specify the format of a custom error.

Several additional values of {ErrorCode} apply only to certain operations.  (For example, “error=’unsupportedProfile’” applies only to the listTargets operation.  Currently, “error=’invalidIdentifier’” and “error=’alreadyExists’” apply only to the add operation.)  The section that discusses each operation also discusses any value of {ErrorCode} that is specific to that operation.

3.1.2.3Error Message (normative)

A response MAY contain any number of <errorMessage> elements.  The XML content of each <errorMessage> is a string that provides additional information about the status or failure of the requested operation.

·         A response that specifies status=’failure’” SHOULD contain at least one <errorMessage> that describes each condition that caused the failure.

·         A response that specifies status=’success’” MAY contain any number of <errorMessage> elements that describe warning conditions.

·         A response that specifies status=’success’” SHOULD NOT contain an <errorMessage> element that describes an informational message

The content of an <errorMessage> is intended for logging or display to a human administrator (rather than for programmatic interpretation).


3.1.3      Synchronous and asynchronous operations

A provider may execute a requested operation either synchronously or asynchronously.

·         Synchronous: operation before response. If a provider executes a requested operation synchronously, the provider completes the requested operation before the provider returns a response to the requestor. The response will include the status and any error or result.

·         Asynchronous: response before operation. If a provider executes a requested operation asynchronously, the provider returns to the requestor a response (that indicates that the operation will be executed asynchronously) before the provider executes the requested operation. The response will specify “status=’pending’” and will specify a “requestID” value that the requestor must use in order to cancel the asynchronous operation or (in order to) obtain the status or results of the asynchronous operation.

-          If a request specifies “requestID”, then the provider’s response to that request will specify the same “requestID” value.

-          If the request omits “requestID”, then the provider’s response to that request will specify a “requestID” value that is generated by the provider.

A requestor may specify the execution mode for an operation in its request or (a requestor may omit the execution mode and thus) allow the provider to decide the execution mode (for the requested operation). If the requestor specifies an execution mode that the provider cannot support for the requested operation, then the provider will fail the request.

3.1.3.1ExecutionMode attribute

A requestor uses the optional “executionMode” attribute of an SPML request to specify that the provider must execute the specified operation synchronously or (to specify that the provider must execute the specified operation) asynchronously. If a requestor omits the “executionMode” attribute from an SPML request, the provider decides whether to execute the requested operation synchronously or (to execute the requested operation) asynchronously.

3.1.3.2Async Capability

A provider uses the Async Capability that is defined as part of SPMLv2 to tell any requestor that the provider supports asynchronous execution of requested operations on objects contained by that target. A target may further refine this declaration to apply only to specific types of objects (i.e., for a specific subset of supported schema entities) on the target.

SPMLv2’s Async Capability also defines two operations that a requestor may use to manage other operations that a provider is executing asynchronously:

·         A status operation allows a requestor to check the status (and optionally results) of an operation (or of all operations)

·         A cancel operation asks the provider to stop executing an operation.

For more information, see the section titled "Async Capability".

3.1.3.3Determining execution mode

By default, a requestor allows a provider to decide whether to execute a requested operation synchronously or asynchronously. A requestor that needs the provider to execute a requested operation in a particular manner must specify this in the request. Each subsection that follows describes one of the four possibilities:

·         Requestor specifies synchronous execution

·         Requestor specifies asynchronous execution

·         Provider chooses synchronous execution

·         Provider chooses asynchronous execution

The following subsections normatively apply to every SPMLv2 operation unless the normative text that describes an operation specifies otherwise.

3.1.3.3.1 Requestor specifies synchronous execution (normative)

A requestor MAY specify that an operation must execute synchronously. A requestor that wants the provider to execute an operation synchronously MUST specify "executionMode='synchronous'" in the SPML request.

If a requestor specifies that an operation must be executed synchronously and the provider cannot execute the requested operation synchronously, then the provider MUST fail the operation. If a provider fails an operation because the provider cannot execute the operation synchronously, then the provider’s response MUST specify “status=’failed’ and (the provider’s response MUST also specify) “error=’unsupportedExecutionMode’.

If a requestor specifies that an operation must be executed synchronously and the provider does not fail the request, then the provider implicitly agrees to execute the requested operation synchronously. The provider MUST acknowledge the request with a response that contains any status and any error or output of the operation. The provider’s response MUST NOT specify “status=’pending’”. The provider’s response MUST specify either status='success' or “status=’failed’.

·         If the provider’s response specifies “status=’failed’, then the provider’s response must have an “error” attribute.

·         If the provider’s response specifies “status='success', then the provider’s response MUST contain any additional results (i.e., output) of the completed operation.

3.1.3.3.2 Requestor specifies asynchronous execution (normative)

A requestor MAY specify that an operation must execute asynchronously. A requestor that wants the provider to execute an operation asynchronously MUST specify "executionMode='asynchronous'" in the SPML request.

If a requestor specifies that an operation must be executed asynchronously and the provider cannot execute the requested operation asynchronously, then the provider MUST fail the operation.  If the provider fails the operation because the provider cannot execute the operation asynchronously, then the provider’s response MUST specify “status=’failed’” and (the provider’s response MUST specify) “error=’unsupportedExecutionMode’”.

If a requestor specifies that an operation must be executed asynchronously and the provider does not fail the request, then the provider implicitly agrees to execute the requested operation asynchronously. The provider MUST acknowledge the request with a synchronous response that indicates that the operation will execute asynchronously. The provider’s response MUST specify “status=’pending’” and (the provider’s response MUST specify) “requestID”.

·         If the request specifies a “requestID” value, then the provider’s response MUST specify the same “requestID” value.

·         If the request omits “requestID”, then the provider’s response MUST specify a “requestID” value that uniquely identifies the requested operation within the namespace of the provider.

If the provider’s response indicates that the requested operation will execute asynchronously, the requestor may continue with other processing. If the requestor wishes to obtain the status and results of the requested operation (or to cancel the requested operation), the requestor MUST use the “requestID value that is returned in the provider’s response to identify the operation.

See also the sections titled “Async Capability” and “Results of asynchronous operations (normative)”.

3.1.3.3.3 Provider chooses synchronous execution (normative)

A requestor MAY allow the provider to decide whether to execute a requested operation synchronously or asynchronously.  A requestor that wants to let the provider decide the type of execution for an operation MUST omit the “executionMode” attribute of the SPML request.

If a requestor lets the provider decide the type of execution for an operation and the provider chooses to execute the requested operation synchronously, then the provider’s response MUST indicate that the requested operation was executed synchronously. The provider’s response MUST NOT specify “status=’pending’”. The provider’s response MUST specify either “status='success'” or “status=’failed’”.

·         If the provider’s response specifies “status=’failed’”, then the provider’s response must have an “error” attribute.

·         If the provider’s response specifies “status='success'”, then the provider’s response MUST contain any additional results (i.e., output) of the completed operation.

3.1.3.3.4 Provider chooses asynchronous execution (normative)

A requestor MAY allow a provider to decide whether to execute a requested operation synchronously or asynchronously.  A requestor that wants to let the provider decide the type of execution for an operation MUST omit the “executionMode” attribute of the SPML request.

If a requestor lets the provider decide the type of execution for an operation and the provider chooses to execute the requested operation asynchronously, then the provider’s response must indicate that the  requested operation will execute asynchronously. The provider MUST acknowledge the request with a response that indicates that the operation will execute asynchronously. The provider’s response MUST specify “status=’pending’” and (the provider’s response MUST specify) “requestID”.

·         If the request specifies a “requestID” value, then the provider’s response MUST specify the same “requestID” value.

·         If the request omits “requestID”, then the provider’s response MUST specify a “requestID” value that uniquely identifies the requested operation within the namespace of the provider.

If the provider’s response indicates that the requested operation will execute asynchronously, the requestor may continue with other processing. If the requestor wishes to obtain the status and results of the requested operation (or to cancel the requested operation), the requestor MUST use the “requestID value that is returned in the provider’s response to identify the operation.

See also the sections titled “Async Capability” and “Results of asynchronous operations (normative)”.

3.1.3.4Results of asynchronous operations (normative)

A provider that supports asynchronous execution of requested operations MUST maintain the status and results of each asynchronously executed operation during the period of time that the operation is executing and for some reasonable period of time after the operation completes. Maintaining this information allows the provider to respond to status requests.

A provider that supports asynchronous execution of requested operations SHOULD publish out-of-band (i.e., make available to requestors in a manner that is not specified by this document) any limit on the how long after the completion of an asynchronous operation the provider will keep the status and results of that operation.

3.1.4      Individual and batch requests

A requestor generally requests each operation individually. SPMLv2 also defines a capability to batch requests. If the provider supports this batch capability, a requestor may group any number of requests (e.g., requests to add, modify or delete) into a single request.

Individual. The SPMLv2 core protocol allows a requestor to ask a provider to execute an individual operation. Each request that is part of the SPMLv2 Core XSD asks a provider to perform a single operation.

Batch. SPMLv2 defines batch as an optional operation that allows a requestor to combine any number of requests into a single request. See the section titled "Batch Capability".

3.2      Identifiers

 

   <complexType name="IdentifierType">

      <complexContent>

         <extension base="spml:ExtensibleType">

            <attribute name="ID" type="string" use="optional"/>

         </extension>

      </complexContent>

   </complexType>

 

   <complexType name="PSOIdentifierType">

      <complexContent>

         <extension base="spml:IdentifierType">

            <sequence>

               <element name="containerID" type="spml:PSOIdentifierType" minOccurs="0"/>

            </sequence>

            <attribute name="targetID" type="string" use="optional"/>

         </extension>

      </complexContent>

   </complexType>

 

SPMLv2 uses several different types of identifiers.

·         An instance of {xsd:string} identifies a target.
A target identifier must be unique within the (namespace of the) provider.

·         An instance of {xsd:ID} identifies a request or an operation.

·         An instance of {PSOIdentifierType} identifies an object on a target.
An instance of
{PSOIdentifierType} combines a target identifier with an object identifier.
The target identifier MUST be unique within the (namespace of the) provider.
The object identifier MUST be unique within the (namespace of the) target.

3.2.1      Request Identifier (normative)

RequestID in a request. A requestor SHOULD specify a reasonably unique value for the “requestID” attribute in each request. A "requestID" value need not be globally unique. A "requestID" value needs only to be sufficiently unique to identify each outstanding request. (That is, a requestor SHOULD specify as the value of “requestID” in each SPML request a value that is sufficiently unique to identify each request for which the requestor has not yet received the corresponding response.)

A requestor that uses a transport protocol that is synchronous (such as SOAP/HTTP) MAY omit “requestID”.  The synchronous nature of the transport protocol exchange itself ensures that the requestor can match the provider’s response to the request. (The provider’s response will contain any requestID that is necessary—for example, because the provider executes the requested operation asynchronously. See the topic named “RequestID in a response” immediately below.)

RequestID in a response.  A provider’s response to a request that specifies “requestID” MUST specify the same “requestID” value.

A provider’s response to a request that does not specify a value for “requestID” MAY omit the “requestID” attribute UNLESS the provider executes the requested operation asynchronously.

If the provider executes asynchronously (the operation that was described by) a request that omitted “requestID”, then the provider MUST generate a value that uniquely identifies the operation to the provider and (the provider MUST) specify this value as the value of the “requestID” attribute in the provider’s response.  (This allows the requestor to cancel or to obtain the status of the operation that the provider is executing asynchronously.
See the section titled "
Async Capability".)

3.2.2      Target Identifier (normative)

Each of a provider’s targets has a string identifier. Within a provider’s listTargets response, the “targetID” attribute of each <target> element specifies this identifier. 

TargetID is unique within provider. Each <target> in a provider’s <listTargetsResponse> MUST specify a value for “targetID” that uniquely identifies the target within the namespace of the provider.

Wherever targetID occurs in a request or in a response, the "targetID" must correspond to one of the provider’s targets.  (That is, the value of any “targetID” attribute that a request specifies or (that a request) indirectly contains MUST match the value of the “targetID” attribute that a <target> element in the provider’s <listTargetsResponse> specifies.)

If a request contains an invalid "targetID", the provider’s response SHOULD specify “error=’noSuchIdentifier’”.

3.2.3      PSO Identifier (normative)

PSO Identifier must be unique.  A provider MUST ensure that each object’s PSO Identifier is unique (within the namespace of the provider). Since every instance of {PSOIdentifierType} also specifies the target that contains the object (see the next topic immediately below), the value that identifies an object must be unique within the namespace of the target.

TargetID.  Any instance of {PSOIdentifierType} SHOULD specify “targetID”. 

·         If the provider's <listTargetsResponse> contains only one <target>,
then an instance of
{PSOIdentifierType} MAY omit "targetID". 

·         If the provider's <listTargetsResponse> contains more than one <target>,
then any instance of
{PSOIdentifierType} MUST specify "targetID". 
The value of
“targetID” MUST identify a valid target.  (That is, the value of “targetID” MUST match the “targetID” of a <target> in the provider’s <listTargetsResponse>.  See the section titled “Target Identifier (normative)” above.)

containerID.  Any instance of {PSOIdentifierType} MAY contain at most one <containerID>.  Any <containerID> MUST identify an object that exists on the target.  (That is, the content of any <containerID> in an instance of {PSOIdentifierType} MUST match the <psoID> of an object that exists on a target.  In addition, the value of any "targetID" attribute in the <containerID> element MUST match the value of the "targetID" attribute of the instance of {PSOIdentifierType} that contains the <containerID>.)

ID. Any instance of {PSOIdentifierType} MAY specify “ID”.  This depends on the profile that the requestor and provider have agreed to use.

·         The DSML Profile and the XML Schema Profile both specify that an instance of {PSOIdentifierType} MUST specify “ID”.  The value of “ID” MUST uniquely identify an object within the namespace of the target that “targetID” specifies.

·         Another profile may specify that an instance of {PSOIdentifierType} MAY omit "ID".

Content depends on profile.  The content of an instance of {PSOIdentifierType} depends on the profile that a requestor and provider agree to use. 

·         Both the DSML profile and the XML Schema Profile specify that an instance of {PSOIdentifierType} MUST have an "ID" attribute (see the topic immediately above).  Neither the DSML profile nor the XML Schema Profile specifies XML content for an instance of {PSOIdentifierType}.

·         A profile MAY specify XML content for an instance of {PSOIdentifierType}.

Caution: PSO Identifier is mutable.  A provider MAY change the PSO Identifier for an object. For example, moving an organizational unit (OU) beneath a new parent within a directory service will change the distinguished name (DN) of the organizational unit.  If the provider exposes the organizational unit as an object and (if the provider exposes) the directory service DN as the object’s PSO Identifier, then this move will change the object’s <psoID>.

Recommend immutable PSO Identifier. A provider SHOULD expose an immutable value (such as a globally unique identifier or “GUID”) as the PSO Identifier for each object.  (An immutable PSO Identifier ensures that a requestor's reference to an object remains valid as long as the object exists.)


3.3      Selection

3.3.1      QueryClauseType

SPMLv2 defines a {QueryClauseType} that is used to select objects.  Each instance of {QueryClauseType} represents a selection criterion.

 

   <complexType name="QueryClauseType">

      <complexContent>

         <extension base="spml:ExtensibleType">

         </extension>

      </complexContent>

   </complexType>

 

{QueryClauseType} specifies no element or attribute.  This type is a semantic marker.

·         Any capability may define elements of (types that extend) QueryClauseType.  These query clause elements allow a requestor to search for objects based on capability-specific data. 
(For example, the SPML Reference Capability defines a
<hasReference> element
that enables a requestor to query for objects that have a specific reference. 
The SPML Suspend Capability also defines an
<isActive> element
that enables a requestor to query for objects that are enabled or disabled.)

·         An instance of {SelectionType}, which extends {QueryClauseType}, may filter a set of objects. {SelectionType} may also be used to specify a particular element or attribute of an object.  See the section titled “SelectionType” below.

·         The SPMLv2 Search Capability defines three logical operators that indicate how a provider should combine selection criteria.  Each logical operator is an instance of {LogicalOperatorType}, which extends {QueryClauseType}. 
See the section titled “
Logical Operators” below.

3.3.2      Logical Operators

The SPMLv2 Search Capability defines three logical operators that indicate how a provider should combine selection criteria.

·         The logical operator <and> specifies a conjunct
(that is, the
<and> is true if and only if every selection criterion that the <and> contains is true).

·         The logical operator <or> specifies a disjunct
(that is, the
<or> is true if any selection criterion that the <or> contains is true).

·         The logical operator <not> specifies negation
(that is, the
<not> is true if and only if the selection criterion that the <not> contains is false.)

 

   <complexType name="LogicalOperatorType">

      <complexContent>

         <extension base="spml:QueryClauseType">

         </extension>

      </complexContent>

   </complexType>

 

   <element name="and" type="spmlsearch:LogicalOperatorType"/>

   <element name="or" type="spmlsearch:LogicalOperatorType"/>

   <element name="not" type="spmlsearch:LogicalOperatorType"/>

 

3.3.3      SelectionType

SPMLv2 defines a {SelectionType} that is used in two different ways:

·         An instance of {SelectionType} may specify an element or attribute of an object.
For example, the
<component> of a <modification> specifies the part of an object that a modify operation (or a bulkModify operation) will change.

·         An instance of {SelectionType} may filter a set of objects.
For example, a
<query> may contain a <select> that restricts, based on the schema-defined XML representation of each object, the set of objects that a search operation returns
(or that a
bulkModify operation changes or that a bulkDelete operation deletes).

 

   <complexType name="SelectionType">

      <complexContent>

         <extension base="spml:QueryClauseType">

            <sequence>

               <element name="namespacePrefixMap" type="spml:NamespacePrefixMappingType" minOccurs="0" maxOccurs="unbounded"/>

            </sequence>

            <attribute name="path" type="string" use="required"/>

            <attribute name="namespaceURI" type="string" use="required"/>

         </extension>

      </complexContent>

   </complexType>

 

   <element name="select" type="spml:SelectionType"/>

 

SelectionType. An instance of {SelectionType} has a “path” attribute which value is an expression. An instance of {SelectionType} also contains a “namespaceURI” attribute that indicates (to any provider that recognizes the namespace) the language in which the value of the “path” attribute is expressed.

Namespace Prefix Mappings. An instance of {SelectionType} may also contain any number of <namespacePrefixMap> elements (see the normative section that follows next). Each <namespacePrefixMap> allows a requestor to specify the URI of an XML namespace that corresponds to a namespace prefix that occurs (or that may occur) within the value of the “path” attribute.

3.3.3.1SelectionType in a Request (normative)

namespaceURI. An instance of {SelectionType} MUST have a “namespaceURI” attribute. The value of the “namespaceURI” attribute MUST specify the XML namespace of a query language. (The value of the “path” attribute must be an expression that is valid in this query language—see below.)

path. An instance of {SelectionType} MUST have a “path” attribute. The value of the “path” attribute MUST be an expression that is valid in the query language that the “namespaceURI” attribute specifies.  The “path” value serves different purposes in different contexts.

·         Within a <modification> element, the value of the “path” attribute MUST specify a target schema entity (i.e., an element or attribute) of the object that the provider is to modify.

·         Within a <query> element, the value of the “path” attribute MUST specify a filter that selects objects based on:

-          The presence (or absence) of a specific element or attribute

-          The presence (or absence) of a specific value in the content of an element
or (the presence of absence of a specific value) in the value of an attribute

The value of the “path” attribute MUST be expressed in terms of elements or attributes that are valid (according to the schema of the target) for the type of object on which the provider is requested to operate.

Namespace prefix mappings. An instance of {SelectionType} MAY contain any number of <namespacePrefixMap> elements.

·         Each <namespacePrefixMap> MUST have a “prefix” attribute whose value specifies a namespace prefix (that may occur in the filter expression that is the value of the “path” attribute).

·         Each <namespacePrefixMap> MUST have a “namespace” attribute whose value is the URI for an XML namespace.

A requestor SHOULD use these mappings to define any namespace prefix that the (value of the) “path” attribute contains.

Depends on profile. The profile on which a requestor and provider agree may further restrict an instance of {SelectionType}. For example, a particular profile may allow a <component> sub-element within a modification (or a <select> sub-element within a query) to specify only elements of a schema entity (and not to specify attributes of those elements).

Refer to the documentation of each profile for normative specifics.

3.3.3.2SelectionType Processing (normative)

A provider MUST evaluate an instance of {SelectionType} in a manner that is appropriate to the context in which the instance of {SelectionType} occurs:

·         Within a <modification> element, a provider must resolve the value of the “path” attribute to a schema entity (i.e., to an element or attribute) of the object that the provider is to modify.

·         Within a <query> element, a provider must evaluate the value of the “path” attribute as a filter expression that selects objects based on:

-          The presence (or absence) of a specific element or attribute

-          The presence (or absence) of a specific value in the content of an element
or (the presence of absence of a specific value) in the value of an attribute

Namespace prefix mappings. A provider SHOULD use any instance of <namespacePrefixMap> that an instance of {SelectionType} contains in order to resolve any namespace prefix that the value of the “path” attribute contains.

Depends on profile. The profile on which a requestor and provider agree may further restrict (or may further specify the processing of) an instance of {SelectionType}.  For example, a particular profile may allow a <component> sub-element within a modification (or a <select> sub-element within a query) to specify only elements of a schema entity (and not to specify attributes of those elements).

Refer to the documentation of each profile for normative specifics.

3.3.3.3SelectionType Errors (normative)

A provider’s response to a request that contains an instance of {SelectionType}
MUST specify an error if any of the following is true:

·         The provider does not recognize the value of the “namespaceURI” attribute as indicating an expression language that the provider supports.

·         The provider does not recognize the value of the “path” attribute as an expression that is valid in the language that the “namespaceURI” attribute specifies.

·         The provider does not recognize the value of a “path” attribute as an expression that refers to a schema entity (i.e., element or attribute) that is valid according to the schema of the target.

·         The provider does not support the expression that “path” attribute specifies. 
(For example, the expression may be too complex or the expression may contain syntax that the provider does not support.)

In all of the cases described above, the provider’s response MUST specify either "error='unsupportedSelectionType'" or “error=’customError’”. 

·         In general, the provider’s response SHOULD specify “error=’unsupportedSelectionType’”.  The provider’s response MAY also contain instances of <errorMessage> that describe more specifically the problem with the request.

·         However, a provider’s response MAY specify “error=’customError’”
if the provider's custom error mechanism enables the provider to indicate more specifically
(or to describe more specifically) the problem with the request.

Depends on profile. The profile on which a requestor and provider agree may further restrict (or may further specify the errors related to) an instance of {SelectionType}.  For example, a particular profile may allow a <component> sub-element within a modification (or a <select> sub-element within a query) to specify only elements of a schema entity (and not to specify attributes of those elements).

Refer to the documentation of each profile for normative specifics.

3.3.4      SearchQueryType

SPMLv2 defines a {SearchQueryType} that is used to select objects on a target.

 

   <simpleType name="ScopeType">

      <restriction base="string">

         <enumeration value="pso"/>

         <enumeration value="oneLevel"/>

         <enumeration value="subTree"/>

      </restriction>

   </simpleType>

 

   <complexType name="SearchQueryType">

      <complexContent>

         <extension base="spml:QueryClauseType">

            <sequence>

               <annotation>

                  <documentation>Open content is one or more instances of QueryClauseType (including SelectionType) or LogicalOperator.</documentation>

               </annotation>

               <element name="basePsoID" type="spml:PSOIdentifierType" minOccurs="0"/>

            </sequence>

            <attribute name="targetID" type="string" use="optional"/>

            <attribute name="scope" type="spmlsearch:ScopeType" use="optional"/>

         </extension>

      </complexContent>

   </complexType>

 

   <element name="query" type="spmlsearch:SearchQueryType"/>

 

targetID specifies the target on which to search for objects.

basePsoID specifies the starting point for a query.  Any <basePsoID> MUST identify an existing object to use as a base context or “root” for the search.  That is, a <query> that contains <basePsoID> may select only the specified container and objects in that container.

Scope indicates whether the query should select the container itself, objects directly contained, or any object directly or indirectly contained.

The “scope” attribute restricts the search operation to one of the following:

·         To the base context itself.

·         To the base context and its direct children.

·         To the base context and any of its descendants.

3.3.4.1SearchQueryType in a Request (normative)

targetID.  An instance of {SearchQueryType} MAY specify “targetID”.

·         If the provider's <listTargetsResponse> contains only one <target>,
then a requestor MAY omit the
“targetID” attribute of {SearchQueryType}.

·         If the provider's <listTargetsResponse> contains more than one <target>,
then a requestor MUST specify the
“targetID” attribute of {SearchQueryType}.

basePsoID.  An instance of {SearchQueryType} MAY contain at most one <basePsoID>. 

·         A requestor that wants to search the entire namespace of a target
MUST NOT supply <basePsoID>.

·         A requestor that wants to search beneath a specific object on a target
MUST supply
<basePsoID>.  Any <basePsoID> MUST identify an object that exists on the target.  (That is, any <basePsoID> MUST match the <psoID> of an object that already exists on the target.)

scope.  An instance of {SearchQueryType} MAY have a “scope” attribute. The value of the “scope” attribute specifies the set of objects against which the provider should evaluate the <select> element:

·         A requestor that wants the provider to search only the object identified by <basePsoID>
MUST specify “
scope=’pso’”.  (NOTE: It is an error to specify “scope='pso'” in An instance of {SearchQueryType} that does not contain <basePsoID>. The target is not an object.)
See the section titled “
SearchQueryType Errors (normative)” below.

·         A requestor that wants the provider to search only direct descendants of the target or (that wants to search only direct descendants) of the object specified by <basePsoID> MUST specify “scope=’oneLevel’”.

·         A requestor that wants the provider to search any direct or indirect descendant of the target or (that wants to search any direct or indirect descendant) of the object specified by <basePsoID> MUST specify “scope=’subTree’”.

Open content.  An instance of {SearchQueryType} MUST contain (as open content) exactly one instance of a type that extends {QueryClauseType}.

·         Any capability may define elements of (a type that extends) {QueryClauseType}.  These elements allow a requestor to select objects based on capability-defined data.
See the section titled "
QueryClauseType" above.

·         A <select> element is an instance of {SelectionType}, which extends {QueryClauseType} to filter objects based on schema-defined content. 
See the section titled “SelectionType in a Request (normative)“.

·         Logical Operators such as <and>, <or> and <not> combine individual selection criteria.
A logical operator MUST contain at least one instance of a type that extends
{QueryClauseType} or a (logical operator MUST contain at least one) logical operator.
See the section titled "
Logical Operators" above.

3.3.4.2SearchQueryType Errors (normative)

The response to a request that contains an instance of {SearchQueryType} (e.g., a <query> element) MUST specify an appropriate value of “error” if any of the following is true:

·         The <query> in a <searchRequest> specifies “scope=’pso’” but does not contain <basePsoID>.  (The target itself is not a PSO.)

·         The "targetID" of the instance of {SearchQueryType} does not specify a valid target.

·         An instance of {SearchQueryType} specifies "targetID" and (the instance of {SearchQueryType} also) contains <basePsoID>, but the value of "targetID" in the instance of {SearchQueryType} does not match the value of "targetID" in the <basePsoID>.

·         An instance of {SearchQueryType} contains a <basePsoID>
that does not identify an object that exists on a target.
(That is, the
<basePsoID> does not match the <psoID> of any object that exists on a target.)

·         The provider cannot evaluate an instance of {QueryClauseType} that the instance of {SearchQueryType} contains.

·         The open content of the instance of {SearchQueryType} is too complex for the provider to evaluate.

·         The open content of the instance of {SearchQueryType} contains a syntactic error
(such as an invalid structure of logical operators or query clauses).

·         The provider does not recognize an element of open content that the instance of {SearchQueryType} contains.

Also see the section titled "SelectionType Errors (normative)".

3.4      CapabilityData

Any capability may imply that data specific to that capability may be associated with an object.  Capability-specific data that is associated with an object is not part of the schema-defined data of an object.  SPML operations handle capability-specific data separately from schema-defined data.  Any capability that implies capability-specific data should define the structure of that data.  Any capability that implies capability-specific data may also specify how the core operations should treat that capability-specific data. See the discussion of "Capability-specific data" within the section titled "Conformance (normative)".

However, many capabilities will not imply any capability-specific data (that may be associated with an object). Of the standard capabilities that SPMLv2 defines, only the Reference Capability actually implies that data specific to the Reference Capability may be associated with an object.  (The Suspend Capability supports an <isActive> query clause that allows a requestor to select objects based on the enablement state of each object, but the <isActive> element is not stored as <capabilityData> that is associated with an object.)

The Reference Capability implies that an object (that is an instance of a schema entity for which the provider supports the Reference Capability) may contain any number of references to other objects.  The Reference Capability defines the structure of a reference element. The Reference Capability also specifies how the core operations must treat data specific to the Reference Capability. See the section titled "Reference Capability".

3.4.1      CapabilityDataType

SPMLv2 defines a {CapabilityDataType} that may occur in a request or in a response. Each instance of {CapabilityDataType} contains all of the data that is associated with a particular object and that is specific to a particular capability.

 

   <complexType name=”CapabilityDataType”>

      <complexContent>

         <extension base="spml:ExtensibleType">

            <annotation>

               <documentation>Contains elements specific to a capability.</documentation>

            </annotation>

            <attribute name="mustUnderstand" type="boolean" use="optional"/>

            <attribute name="capabilityURI" type="anyURI"/>

         </extension>

      </complexContent>

   </complexType>

 

      <complexType name="PSOType">

      <complexContent>

         <extension base="spml:ExtensibleType">

            <sequence>

               <element name="psoID" type="spml:PSOIdentifierType"/>

               <element name="data" type="spml:ExtensibleType" minOccurs="0"/>

               <element name="capabilityData" type="spml:CapabilityDataType" minOccurs="0" maxOccurs="unbounded"/>

            </sequence>

         </extension>

      </complexContent>

   </complexType>

 

capabilityURI. An instance of {CapabilityDataType} has a “capabilityURI” attribute that identifies a capability. The value of "capabilityURI" must match the value of the “namespaceURI” attribute of a supported <capability>.

mustUnderstand. An instance of {CapabilityDataType} may also specify a Boolean value for "mustUnderstand". This value indicates whether provider must handle the content (of the instance of {CapabilityDataType}) in a manner that the capability specifies. An instance of {CapabilityDataType} specifies "mustUnderstand='false'" indicates that default processing will suffice. (See the next topic below.)

The "mustUnderstand" attribute is significant only when a request contains the instance of {CapabilityDataType}.
See the section titled "
CapabilityData in a Request (normative)" below.

Default processing. Each <capabilityData> specifies "capabilityURI" and contains all the data associated with an object that is specific to that capability. 
See the section below titled "
CapabilityData in a Request (normative)".
By default, a provider treats the set of data specific to each capability as if it were opaque.  That is, a provider processes the content of an instance of {CapabilityDataType} exactly as it is without manipulating that content in any way. 
See the section titled "
CapabilityData Processing (normative)".

Capability-specific processing. Any capability that implies capability-specific data may specify how operations should handle the data specific to that capability.  Capability-specific handling takes precedence over the default handling. 
See the section titled "
CapabilityData Processing (normative)".

3.4.1.1CapabilityData in a Request (normative)

capabilityURI. An instance of {CapabilityDataType} MUST specify a value of “capabilityURI” that identifies a supported capability.  That is, the (value of the) "capabilityURI" attribute for an instance of {CapabilityDataType} MUST match the (value of the) “namespaceURI” attribute of a <capability> the provider supports for the target (that contains the object to be manipulated) and (that the provider supports on that target) for the schema entity of which the object to be manipulated is an instance.

For normative specifics of supported capabilities,
see the section titled "
listTargetsResponse (normative)".

One capabilityData element per capability. At most one instance of {CapabilityDataType} within a request MAY refer to a specific capability.  That is, a request MUST NOT contain two (and MUST NOT contain more than two) instances of {CapabilityDataType} that specify the same value of "capabilityURI".

This implies that an instance of {CapabilityDataType} that refers to a certain capability MUST contain all the data within that request that is specific to that capability and that is specific to a particular object.

mustUnderstand. An instance of {CapabilityDataType} MAY specify "mustUnderstand". The "mustUnderstand" attribute tells the provider what to do if the provider does not know how to handle the content of an instance of {CapabilityDataType} in any special manner that the corresponding capability specifies. 

·         A requestor that wants the request to fail if the provider cannot provide capability-specific handling for the set of data specific to a certain capability MUST specify "mustUnderstand='true'" on the instance of {CapabilityDataType}
that contains the data specific to that capability.

·         A requestor that will accept default handling for any data specific to a certain capability MUST specify "mustUnderstand='false'" on the instance of {CapabilityDataType} that contains the data specific to that capability or (the requestor MUST) omit the "mustUnderstand" attribute (from the instance of {CapabilityDataType}
that contains the data specific to that capability).

The section titled "CapabilityData Processing (normative)" describes the default handling for capability-specific data.  Any capability for which the default handling is inappropriate MUST specify how operations should handle data specific to that capability.  The section titled "Reference CapabilityData Processing (normative)" specifies handling of data specific to the Reference Capability.

Capability defines structure. Any capability that implies capability-specific data SHOULD specify the structure of that data.  (That is, the capability to which the "capabilityURI" attribute of an instance of {CapabilityDataType} refers SHOULD specify the structure of data that the instance of {CapabilityDataType} contains.) Furthermore, any capability that implies capability-specific data and for which the default processing of capability-specific data is inappropriate MUST specify the structure of that capability-specific data and MUST specify how operations handle that capability-specific data. See the discussion of "Capability-specific data" within the section titled "Conformance".

Of the capabilities that SPMLv2 defines, only the Reference Capability implies that capability-specific data may be associated with an object.  The Reference Capability specifies that an instance of {CapabilityDataType} that refers to the Reference Capability
(e.g., a
<capabilityData> element that specifies "capabilityURI='urn:oasis:names:tc:SPML:2.0:reference'"
MUST contain at least one reference to another object.  The Reference Capability defines the structure of a
<reference> element as {ReferenceType}.)  The Reference Capability also specifies that each <reference> must match a supported <referenceDefinition>.
See the section titled "
Reference CapabilityData in a Request (normative)".

3.4.1.2CapabilityData Processing (normative)

capabilityURI. An instance of {CapabilityDataType} MUST specify a value of “capabilityURI” that identifies a supported capability.  That is, the (value of the) "capabilityURI" attribute for an instance of {CapabilityDataType} MUST match the (value of the) “namespaceURI” attribute of a <capability> the provider supports for the target (that contains the object to be manipulated) and (that the provider supports on that target) for the schema entity of which the object to be manipulated is an instance.

For normative specifics of supported capabilities,
see the section titled "
listTargetsResponse (normative)".

mustUnderstand. The "mustUnderstand" attribute tells a provider whether the default processing of capability-specific data is sufficient for the content of an instance of {CapabilityDataType}.  (The next topic within this section describes the default processing of capability-specific data.)

·         If an instance of {CapabilityDataType} specifies "mustUnderstand='true'", then
the provider MUST handle the data (that the instance of
{CapabilityDataType} contains)
in the manner that the corresponding capability specifies.

If the provider cannot handle the data (that the instance of
{CapabilityDataType} contains) in the manner that the corresponding capability specifies,
then the provider's response MUST specify
"status='failure'".
See the section titled "
CapabilityData Errors (normative)" below.

·         If an instance of {CapabilityDataType} specifies "mustUnderstand='false'"
or an instance of
{CapabilityDataType} omits "mustUnderstand",
then a provider MAY handle the data (that the instance of
{CapabilityDataType} contains)
according to the default processing that is described below.

-          If the provider knows that the corresponding capability (e.g., the Reference Capability) specifies special handling, then the provider SHOULD process the data (that the instance of {CapabilityDataType} contains) in the manner that the corresponding capability specifies.

-          If the provider knows that the corresponding capability (e.g., the Reference Capability) specifies special handling but the provider cannot provide the special handling that the corresponding capability specifies, then the provider MUST handle the data (that the instance of {CapabilityDataType} contains) according to the default processing
that is described below.

-          If the provider does not know whether the corresponding capability specifies special handling, then the provider MUST handle the data (that the instance of {CapabilityDataType} contains) according to the default processing
that is described below.

Default processing. By default, a provider treats the set of data specific to each capability as if it were opaque.  That is, a provider processes the content of an instance of {CapabilityDataType} exactly as it is --without manipulating that content in any way.

(The provider needs to perform capability-specific processing only if the instance of {CapabilityDataType} specifies "mustUnderstand='true'" or if the instance of {CapabilityDataType} refers to the Reference Capability.  See the topic named "mustUnderstand" immediately above within this section.).

·         If an <addRequest> contains an instance of {CapabilityDataType},
then the provider MUST associate the instance of
{CapabilityDataType} exactly as it is
(i.e., without manipulating its content in any way) with the newly created object.

·         If a <modification> contains an instance of {CapabilityDataType},
then the default handling depends on the
"modificationMode" of that <modification>
and also depends on whether an instance of
{CapabilityDataType} that specifies the same "capabilityURI" is already associated with the object to be modified.

-          If a <modification> that specifies "modificationMode='add'"
contains an instance of
{CapabilityDataType},
then the provider MUST append the content of the instance of
{CapabilityDataType} that the <modification> contains exactly as it is to (the content of) any instance of {CapabilityDataType} that is already associated with the object to be modified
and that specifies the same
"capabilityURI".

If no instance of
{CapabilityDataType} that specifies the same "capabilityURI" (as the instance of {CapabilityDataType} that the <modification> contains)
is already associated with the object to be modified,
then the provider MUST the associate with the modified object the
<capabilityData> (that the <modification> contains) exactly as it is  .

-          If a <modification> that specifies "modificationMode='replace'"
contains an instance of
{CapabilityDataType},
then the provider MUST replace entirely any instance of
{CapabilityDataType}
that is already associated with the object to be modified
and that specifies the same
"capabilityURI"
with the instance of
{CapabilityDataType} that the <modification> contains exactly as it is.

If no instance of
{CapabilityDataType} that specifies the same "capabilityURI" (as the instance of {CapabilityDataType} that the <modification> contains)
is already associated with the object to be modified,
then the provider MUST the associate with the modified object the
<capabilityData> (that the <modification> contains) exactly as it is  .

-          If a <modification> that specifies "modificationMode='delete'"
contains an instance of
{CapabilityDataType},
then the provider MUST delete entirely any instance of
{CapabilityDataType}
that is already associated with the object to be modified
and that specifies the same
"capabilityURI"

If no instance of
{CapabilityDataType} that specifies the same "capabilityURI" (as the instance of {CapabilityDataType} that the <modification> contains)
is already associated with the object to be modified, then the provider MUST do nothing. 
In this case, the provider's response MUST NOT specify
"status='failure'"
unless there is some other reason to do so.

Capability-specific handling. Any capability that implies capability-specific data and for which the default processing of capability-specific data is inappropriate MUST specify how (at least the core) operations should process that data.  (That is, the capability to which the "capabilityURI" attribute of an instance of {CapabilityDataType} refers MUST specify how operations should process the data that the instance of {CapabilityDataType} contains if the default processing for capability-specific data is inappropriate.)
See the discussion of "
Capability-specific data" within the section titled "Conformance".

Of the standard capabilities that SPMLv2 defines, only the Reference Capability implies that capability-specific data may be associated with an object.  The Reference Capability specifies how operations should process the content of an instance of {CapabilityDataType} that specifies "capabilityURI='urn:oasis:names:tc:SPML:2.0:reference'".
 See the section titled "
Reference CapabilityData Processing (normative)".

3.4.1.3CapabilityData Errors (normative)

A provider’s response to a request that contains an instance of {CapabilityDataType}
MUST specify an error if any of the following is true:

·         The instance of {CapabilityDataType} specifies "mustUnderstand='true'"
and the provider does not recognize the value of the
“capabilityURI” attribute
as identifying a capability that the provider supports for the target that contains the object to be manipulated and that the provider supports for the schema entity of which the object to be manipulated is an instance.

·         The instance of {CapabilityDataType} specifies "mustUnderstand='true'"
and the capability to which its
“capabilityURI” refers does not specify the structure of data specific to that capability.

·         The instance of {CapabilityDataType} specifies "mustUnderstand='true'" and the capability to which its “capabilityURI” refers does not specify how operations should process data specific to that capability.

·         The request contains two or more instances of {CapabilityDataType} that specify the same value of “capabilityURI”.

In addition, a provider’s response to a request that contains an instance of {CapabilityDataType} MAY specify an error if any of the following is true:

·         The provider does not recognize the value of the “capabilityURI” (that the instance of {CapabilityDataType} specifies) as identifying a capability that the provider supports for the target that contains the object to be manipulated and that the provider supports for the schema entity of which the object to be manipulated is an instance.

Alternatively, the provider MAY perform the default handling as described above
in the section titled "
CapabilityData Processing (normative)".

A provider's response to a request that contains an instance of {CapabilityDataType} SHOULD contain an <errorMessage> for each instance of {CapabilityDataType} that the provider could not process.

Capability-specific errors. Any capability that implies capability-specific data MAY specify additional errors related to that data.  (That is, the capability to which the "capabilityURI" attribute of an instance of {CapabilityDataType} refers MAY specify additional errors related to that instance of {CapabilityDataType}.)

Of the capabilities that SPMLv2 defines, only the Reference Capability implies that capability-specific data may be associated with an object.  The Reference Capability specifies additional errors related to any instance of {CapabilityDataType} that refers to the Reference Capability
See the section titled "
Reference CapabilityData Errors (normative)".

3.4.1.4CapabilityData in a Response (normative)

capabilityURI. An instance of {CapabilityDataType} MUST specify a value of “capabilityURI” that identifies a supported capability.  That is, the (value of the) "capabilityURI" attribute for an instance of {CapabilityDataType} MUST match the (value of the) “namespaceURI” attribute of a <capability> the provider supports for the target (that contains the object to be manipulated) and (that the provider supports on that target) for the schema entity of which the object to be manipulated is an instance.
See the section titled "
listTargetsResponse (normative)".

One per capability. No more than one instance of {CapabilityDataType} within a response may refer to a given capability.  That is, a response MUST NOT contain two (and a request MUST NOT contain more than two) instances of {CapabilityDataType} that specify the same value of "capabilityURI".

This implies that an instance of {CapabilityDataType} that refers to a certain capability MUST contain all the data within that response that is specific to that capability and that is associated with a particular object.

mustUnderstand. An instance of {CapabilityDataType} within a response MAY specify "mustUnderstand". A provider SHOULD preserve any "mustUnderstand" attribute of an instance of {CapabilityDataType}.  See the discussions of the "mustUnderstand" attribute within the sections titled "CapabilityData in a Request (normative)" and "CapabilityData Processing (normative)" above.

Capability defines structure. Any capability that implies capability-specific data MUST specify the structure of that data.  (That is, the capability to which the "capabilityURI" attribute of an instance of {CapabilityDataType} refers MUST specify the structure of data that the instance of {CapabilityDataType} contains.) See the discussion of "Custom Capabilities" within the section titled "Conformance".

Of the capabilities that SPMLv2 defines, only the Reference Capability implies that capability-specific data may be associated with an object.  The Reference Capability specifies that an instance of {CapabilityDataType} that refers to the Reference Capability MUST contain at least one reference to another object.  The Reference Capability defines the structure of a <reference> element as {ReferenceType}.)  The Reference Capability also specifies that each <reference> must match a supported <referenceDefinition>.
See the section titled "
Reference CapabilityData in a Response (normative)".


3.5      Transactional Semantics

SPMLv2 specifies no transactional semantics. This specification defines no operation that implies atomicity. That is, no core operation defines (and no operation that is part of one of SPMLv2’s standard capabilities defines) a logical unit of work that must be committed or rolled back as a unit.

Provisioning operations are notoriously difficult to undo and redo.  For security reasons, many systems and applications will not allow certain identity management operations to be fully reversed or repeated.  (More generally, support for transactional semantics suggests participation in externally managed transactions.  Such participation is beyond the scope of this specification.)

Any transactional semantics should be defined as a capability (or possibly as more than one capability). See the section titled “Custom Capabilities”.  A transactional capability would define operations that imply atomicity or (would define operations) that allow a requestor to specify atomicity. 

Any provider that is able to support transactional semantics should then declare its support for such a capability as part of the provider’s response to the listTargets operation (as the provider would declare its support for any other capability).

3.6      Operations

The first subsection discusses the required Core Operations.

Subsequent subsections discuss any optional operation that is associated with each of the standard capabilities:

·         Async Capability

·         Batch Capability

·         Bulk Capability

·         Password Capability

·         Reference Capability

·         Search Capability

·         Suspend Capability

·         Updates Capability

3.6.1      Core Operations

Schema syntax for the SPMLv2 core operations is defined in a schema associated with the following XML namespace: urn:oasis:names:tc:SPML:2:0 [SPMLv2-CORE]. The Core XSD is included as Appendix A to this document.

A conformant provider must implement all the operations defined in the Core XSD. For more information, see the section entititled "Conformance".

The SPMLv2 core operations include:

·         a discovery operation (listTargets) on the provider

·         several basic operations (add, lookup, modify, delete) that apply to objects on a target

3.6.1.1listTargets

The listTargets operation enables a requestor to determine the set of targets that a provider makes available for provisioning and (the listTargets operation also enables a requestor) to determine the set of capabilities that the provider supports for each target.

The subset of the Core XSD that is most relevant to the listTargets operation follows.

 

   <complexType name="SchemaType">

      <complexContent>

         <extension base="spml:ExtensibleType">

            <sequence>

               <annotation>

                  <documentation>Profile specific schema elements should be included here</documentation>

               </annotation>

               <element name="supportedSchemaEntity" type="spml:SchemaEntityRefType" minOccurs="0" maxOccurs="unbounded"/>

            </sequence>

            <attribute name="ref" type="anyURI" use="optional”/>

         </extension>

      </complexContent>

   </complexType>

 

   <complexType name="SchemaEntityRefType">

      <complexContent>

         <extension base="spml:ExtensibleType">

            <attribute name="targetID" type="string" use="optional”/>

            <attribute name="entityName" type="string" use="optional”/>

            <attribute name="isContainer" type="xsd:boolean" use="optional”/>

         </extension>

      </complexContent>

   </complexType>

 

   <complexType name="CapabilityType">

      <complexContent>

         <extension base="spml:ExtensibleType">

            <sequence>

               <element name="appliesTo" type="spml:SchemaEntityRefType" minOccurs="0" maxOccurs="unbounded"/>

            </sequence>

            <attribute name="namespaceURI" type="anyURI”/>

            <attribute name="location" type="anyURI" use="optional"/>

         </extension>

      </complexContent>

   </complexType>

 

   <complexType name="CapabilitiesListType">

      <complexContent>

         <extension base="spml:ExtensibleType">

            <sequence>

               <element name="capability" type="spml:CapabilityType" minOccurs="0" maxOccurs="unbounded"/>

            </sequence>

         </extension>

      </complexContent>

   </complexType>

 

   <complexType name="TargetType">

      <complexContent>

         <extension base="spml:ExtensibleType">

            <sequence>

               <element name="schema" type="spml:SchemaType" maxOccurs="unbounded"/>

               <element name="capabilities" type="spml:CapabilitiesListType" minOccurs="0"/>

            </sequence>

            <attribute name="targetID" type="string" use="optional"/>

            <attribute name="profile" type="anyURI" use="optional"/>

         </extension>

      </complexContent>

   </complexType>

 

   <complexType name="ListTargetsRequestType">

      <complexContent>

         <extension base="spml:RequestType">

         </extension>

            <attribute name="profile" type="anyURI" use="optional"/>

      </complexContent>

   </complexType>

 

   <complexType name="ListTargetsResponseType">

      <complexContent>

         <extension base="spml:ResponseType">

            <sequence>

               <element name="target" type="spml:TargetType" minOccurs="0" maxOccurs="unbounded"/>

            </sequence>

         </extension>

      </complexContent>

   </complexType>

 

   <element name="listTargetsRequest" type="spml:ListTargetsRequestType"/>

   <element name="listTargetsResponse" type="spml:ListTargetsResponseType"/>

 

ListTargets must be synchronous. Because the requestor cannot know (at the time the requestor asks to listTargets) whether the provider supports asynchronous execution, the listTargets operation must be synchronous.

ListTargets is not batchable. Because the requestor cannot know (at the time the requestor asks the provider to listTargets) whether the provider supports the batch capability, a requestor must not nest a listTargets request in a batch request.

3.6.1.1.1 listTargetsRequest (normative)

A requestor MUST send a <listTargetsRequest> to a provider in order to ask the provider to declare the set of targets that the provider exposes for provisioning operations.

Execution. A <listTargetsRequest> MUST NOT specify "executionMode='asynchronous'". A <listTargetsRequest> MUST specify "executionMode='synchronous'" or (a <listTargetsRequest> MUST) omit "executionMode".

This is because a requestor SHOULD examine each target definition to see whether the target supports the Async Capability before making a request that specifies "executionMode='asynchronous'" (rather than assuming that the provider supports asynchronous execution of requested operations). Since a requestor typically must perform the listTargets operation only once at the beginning of a session, this restriction should not be too onerous.

For more information, see the section titled “Determining execution mode”.

Profile. a <listTargetsRequest> MAY specify "profile". 
Any profile value MUST be a URI (e.g., of an XML namespace) that identifies an SPML profile.

No required content. A <listTargetsRequest> requires no sub-element or XML content.

3.6.1.1.2 listTargetsResponse (normative)

A provider that receives a <listTargetsRequest> from a requestor that it trusts
MUST examine the request and (if the request is valid) return to the requestor a list of the targets that the provider exposes for provisioning operations.

·         If a <listTargetsRequest> does not specify a "profile",
then the
<listTargetsResponse> MUST contain every instance of <target>
that the provider exposes for provisioning operations regardless of the profile or profiles
for (which the provider supports) that target.

·         If a <listTargetsRequest> specifies a "profile" that the provider supports,
then the
<listTargetsResponse> MUST contain only instances of <target>
for which the provider supports the specified profile.

·         If a <listTargetsRequest> specifies a "profile" that the provider does not support,
then the
<listTargetsResponse> MUST specify "status='failure'".
See the topic named "Error" below within this section.

Execution. A provider MUST execute a listTargets operation synchronously.  This is because a provider must allow the requestor to examine each target definition to see whether the target supports the Async Capability (and thus whether the provider might choose to execute a requested operation asynchronously) before the provider chooses to execute a requested operation asynchronously. Since a requestor typically must perform the listTargets operation only once at the beginning of a session, this restriction should not be too onerous.

If a requestor specifies "executionMode='asynchronous'", a provider MUST fail the operation with “error=’unsupportedExecutionMode’”.

For more information, see the section titled “Determining execution mode”.

Status.  A <listTargetsResponse> MUST have a “status” attribute that indicates whether the provider successfully processed the request.  See the section titled "Status (normative)”.

Error. If the provider cannot return a list of its targets, then the <listTargetsResponse> MUST contain an error attribute that characterizes the failure. 
See the general section titled "
Error (normative)”.

In addition, the <listTargetsResponse> MUST specify an appropriate value of "error" if any of the following is true:

·         The <listTargetsRequest> specifies a "profile" and the provider cannot return at least one <target> that supports the specified profile.  In this case, the <listTargetsResponse> SHOULD specify "error='unsupportedProfile'".

Target. A <listTargetsResponse> that specifies “status='success'” MUST contain at least one <target> element. Each <target> SHOULD specify “targetID”.

·         If the <listTargetsResponse> contains only one <target>
then the
<target> MAY omit “targetID”.

·         If the <listTargetsResponse> contains more than one <target>
then each
<target> MUST specify “targetID”.

Any value of “targetID” MUST identify each target uniquely within the namespace of the provider.

Target profile.  Any <target> MAY specify "profile".  Any "profile" value MUST be a URI (e.g., of an XML namespace) that identifies a specific SPML profile. 

If a <target> specifies a "profile", then the provider MUST support for that target
(and for any objects on that target) the behavior that the SPML profile specifies.
Refer to the documentation of each profile for normative specifics.

Schema. A <target> MUST contain at least one <schema> element. Each <schema> element MUST contain (or each <schema> element MUST refer to) some form of XML Schema that defines the structure of XML objects on that target.

Schema content. Each <spml:schema> element MAY include any number of <xsd:schema> elements.

·         If an <spml:schema> element contains no <xsd:schema> element,
then that
<spml:schema> element MUST have a valid “ref” attribute (see below).

·         If an <spml:schema> element contains at least one <xsd:schema> element,
then this takes precedence over the value of any
“ref” attribute of that <spml:schema>.
In this case, the requestor SHOULD ignore the value of any
“ref” attribute.

Each <xsd:schema> element (that an <spml:schema> element contains)
MUST include the XML namespace of the schema.

Schema ref. Each <spml:schema> MAY have a “ref” attribute. 
If an
<spml:schema> has a “ref” attribute, then:
·         The “ref” value MUST be a URI that uniquely identifies the schema. 
·         The “ref” value MAY be a location of a schema document 
(e.g. the physical URL of an XSD file).
A requestor should ignore any “ref” attribute of an <spml:schema> element that contains an <xsd:schema>.  (See the topic named “Schema content” immediately above.)

Supported Schema Entities. A target MAY declare as part of its <spml:schema> the set of schema entities for which the target supports the basic SPML operations (i.e., add, lookup, modify and delete). The target <spml:schema> MAY contain any number of <supportedSchemaEntity> elements. Each <supportedSchemaEntity> MUST refer to an entity in the target schema.  (See the topics named “SupportedSchemaEntity entityName” and “SupportedSchemaEntity targetID” below within this section.)

A provider that explicitly declares a set of schema entities that a target supports has implicitly declared that the target supports only those schema entities. If a target schema contains at least one <supportedSchemaEntity>, then the provider MUST support the basic SPML operations for (objects on that target that are instances of) any target schema entity to which a <supportedSchemaEntity> refers.

A provider that does not explicitly declare as part of a target at least one schema entity that the target supports has implicitly declared that the target supports every schema entity. If a target schema contains no <supportedSchemaEntity>, then the provider MUST support the basic SPML operations for (objects on that target that are instances of) any top-level entity in the target schema.

A provider SHOULD explicitly declare the set of schema entities that each target supports.  In general, the syntactic convenience of omitting the declaration of supported schema entities (and thereby implicitly declaring that the provider supports all schema entities) does not justify the burden that this imposes on each requestor. When a provider omits the declaration of supported schema entities, each requestor must determine the set of schema entities that the target supports.  This process is especially laborious for a requestor that functions without prior knowledge.

SupportedSchemaEntity entityName. Each <supportedSchemaEntity> MUST refer to an entity in the schema (of the target that contains the <supportedSchemaEntity>):

·         In the XSD Profile [SPMLv2-Profile-XSD ], each <supportedSchemaEntity> MUST specify a QName (as the value of its “entityName” attribute).

·         In the DSMLv2 Profile [SPMLv2-Profile-DSML], each <supportedSchemaEntity> MUST specify the name of an objectclass (as the value of its “entityName” attribute).

SupportedSchemaEntity targetID. A <supportedSchemaEntity> SHOULD specify a “targetID”.

·         A provider MAY omit “targetID” in any <supportedSchemaEntity>.
(That is, a provider MAY omit the optional
“targetID” attribute of {SchemaEntityRefType} in a <supportedSchemaEntity> element.)

·         Any “targetID” in a <supportedSchemaEntity> MUST refer to the containing target.
(That is, the value of any
“targetID” attribute that a <supportedSchemaEntity> specifies MUST match the value of the “targetID” attribute of the <target> element that contains the <supportedSchemaEntity> element.)

SupportedSchemaEntity isContainer. A <supportedSchemaEntity> MAY have an “isContainer” attribute that specifies whether an (object that is an) instance of the supported schema entity may contain other objects.

·         If a <supportedSchemaEntity> specifies “isContainer=’true’”, then a provider
MUST allow a requestor to add an object beneath any instance of the schema entity.

·         If a <supportedSchemaEntity> specifies “isContainer=’false’”
(or i
f a
<supportedSchemaEntity> does not specify “isContainer”), then a provider MUST NOT allow a requestor to add an object beneath any instance of the schema entity.

Capabilities. A target may also declare a set of capabilities that it supports. Each capability defines optional operations or semantics. For general information, see the subsection titled "Capabilities" within the "Concepts" section.

A <target> element MAY contain at most one <capabilities> element. A <capabilities> element MAY contain any number of <capability> elements.

Capability.  Each <capability> declares support for exactly one capability:

·         Each <capability> element MUST specify (as the value of its “namespaceURI” attribute) an XML namespace that identifies the capability.

·         Each <capability> element MAY specify (as the value of its “location” attribute) the URL of an XML schema that defines any structure that is associated with the capability
(e.g., an SPML request/response pair that defines an operation—see below).

Capability operations.  An XML schema document that a capability “location” attribute specifies MAY define operations. An XML schema document for a capability MUST define any operation as a paired request and response such that both of the following are true:

·         The (XSD type of the) request (directly or indirectly) extends {RequestType}

·         The (XSD type of the) response (directly or indirectly) extends {ResponseType}

Capability appliesTo.  A target may support a capability for all of the target’s supported schema entities or only for a specific subset of the target’s supported schema entities.  Each capability element may specify any number of supported schema entities to which it applies. A capability that does not specify a supported schema entity to which it applies must apply to every supported schema entity.

A <capability> element MAY contain any number of <appliesTo> elements.

A <capability> element that contains no <appliesTo> element MUST apply to every schema entity that the target supports. If the XML schema for the capability defines an operation, the provider MUST support the capability-defined operation for (any object that is instance of) any schema entity that the target supports. If the capability implies semantic meaning, then the provider MUST apply that semantic meaning to (every object that is an instance of) any schema entity that the target supports.

Capability appliesTo entityName.  Each <appliesTo> element MUST have an “entityName” attribute that refers to a supported schema entity of the containing target. (See the topic named "Supported Schema Entities entityName" earlier in this section.)

·         In the XSD Profile, each <appliesTo> element MUST specify a QName
(as the value of its
“entityName” attribute).

·         In the DSMLv2 Profile [SPMLv2-Profile-DSML], each <appliesTo> element MUST specify the name of an objectclass (as the value of its “entityName” attribute).

An <appliesTo> element MAY have a “targetID” attribute.

·         A provider MAY omit “targetID” in any <appliesTo>.
(That is, a provider MAY omit the optional
“targetID” attribute of {SchemaEntityRefType} in an <appliesTo> element.)

·         Any “targetID” MUST refer to the containing target.
(That is, any
“targetID” attribute of an <appliesTo> element
MUST contain the same value as the
“targetID” attribute
of the
<target> element that contains the <appliesTo> element.)

Capability content. SPMLv2 specifies only the optional <appliesTo> element as content for most capability elements.  However, a declaration of support for the reference capability is special. 

Reference Capability content. A <capability> element that refers to the Reference Capability (i.e., any <capability> element that specifies “namespaceURI=’urn:oasis:names:tc:SPML:2.0:reference’”)
MUST contain (as open content) at least one
<referenceDefinition> element.
(For normative specifics, please s
ee the topic named “Reference Definition” immediately below.
For background and for general information, please see the section titled "
Reference Capability".
For Reference Capability XSD, please see Appendix F.)

ReferenceDefinition. Each <referenceDefinition> element MUST be an instance of {spmlref:ReferenceDefinitionType}.  Each reference definition names a type of reference, specifies a “from” schema entity and specifies a set of “to” schema entities.  Any instance of the “from” schema entity may refer to any instance of any “to” schema entity using the type of reference that the reference definition names.

ReferenceDefinition typeOfReference. Each <referenceDefinition> element MUST have a “typeOfReference” attribute that names the type of reference.

ReferenceDefinition schemaEntity. Each <referenceDefinition> element MUST contain exactly one <schemaEntity> sub-element that specifies a “from” schema entity for that type of reference.

·         The <schemaEntity> MUST have an “entityName” attribute that refers to a supported schema entity of the containing target.  (See topic named the “Supported Schema Entities” earlier in this section.)

·         The <schemaEntity> MAY have a “targetID” attribute.  Any “targetID” that the <schemaEntity> specifies MUST refer to the containing target. 
(That is, any
“targetID” value that a <schemaEntity> specifies
MUST match the value of the
“targetID” attribute of the <target> element
that contains the
<referenceDefinition>.)

ReferenceDefinition canReferTo. Each <referenceDefinition> element MAY contain any number of <canReferTo> sub-elements, each of which specifies a valid “to” schema entity. A <referenceDefinition> element that contains no <canReferTo> element implicitly declares that any instance of any schema entity on any target is a valid “to” schema entity.

·         A <canReferTo> element MUST have an “entityName” attribute that refers to a supported schema entity. The value of the “entityName” attribute MUST be the name of a top-level entity that is valid in the schema.

·         A <canReferTo> element SHOULD have a “targetID” attribute. 

-          If the <listTargetsResponse> contains only one <target>,
then any
<canReferTo> element MAY omit “targetID”.

-          If the <listTargetsResponse> contains more than one <target>,
then any
<canReferTo> element MUST specify “targetID”.

-          If the <canReferTo> element specifies “targetID”,
then the
“entityName” attribute (of the <canReferTo> element)
MUST refer to a supported schema entity of the specified target
(i.e., the
<target> whose “targetID” value matches
the
“targetID” value that the <canReferTo> element specifies).

-           If the <canReferTo> element does not specify “targetID”,
then the
“entityName” attribute (of the <canReferTo> element)
MUST refer to a supported schema entity of the containing target
(i.e., the
<target> that contains the <referenceDefinition>).

ReferenceDefinition referenceDataType. Each <referenceDefinition> element MAY contain any number of <referenceDataType> sub-elements, each of which specifies a schema entity that is a valid structure for reference data. A <referenceDefinition> element that contains no <referenceDataType> element implicitly declares that an instance of that type of reference will never contain reference data.

·         A <referenceDataType> element MUST have an “entityName” attribute that refers to a supported schema entity. The value of the “entityName” attribute MUST be the name of a top-level entity that is valid in the schema.

·         A <referenceDataType> element SHOULD have a “targetID” attribute. 

-          If the <listTargetsResponse> contains only one <target>,
then any
<referenceDataType> element MAY omit “targetID”.

-          If the <listTargetsResponse> contains more than one <target>,
then any
<referenceDataType> element MUST specify “targetID”.

-          If the <referenceDataType> element specifies “targetID”,
then the
“entityName” attribute (of the <canReferTo> element)
MUST refer to a supported schema entity of the specified target
(i.e., the
<target> whose “targetID” value matches
the
“targetID” value that the <referenceDataType> element specifies).

-           If the <referenceDataType> element does not specify “targetID”,
then the
“entityName” attribute (of the <canReferTo> element)
MUST refer to a supported schema entity of the containing target
(i.e., the
<target> that contains the <referenceDefinition>).

3.6.1.1.3 listTargets Examples (non-normative)

In the following example, a requestor asks a provider to list the targets that the provider exposes for provisioning operations.

<listTargetsRequest/>

The provider returns a <listTargetsResponse>.  The “status” attribute of the <listTargetsResponse> element indicates that the listTargets request was successfully processed. The <listTargetsResponse> contains two <target> elements. Each <target> describes an endpoint that is available for provisioning operations.

The requestor did not specify a profile, but both targets specify the XSD profile [SPMLv2-Profile-XSD].  The requestor must observe the conventions that the XSD profile specifies in order to manipulate an object on either target.

If the requestor had specified the DSML profile, then the response would have contained a different set of targets (or would have specified "error='unsupportedProfile'").

<listTargetsResponse status=“success">

      <target targetID=”target1” profile="urn:oasis:names:tc:SPML:2.0:profiles:XSD">

            <schema>

<xsd:schema targetNamespace="urn:example:schema:target1" xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:spml="urn:oasis:names:tc:SPML:2:0" elementFormDefault="qualified">

                  <complexType name="Account">

                        <sequence>

                              <element name="description" type="string" minOccurs="0"/>

                        </sequence>

                        <attribute name="accountName" type="string" use="required"/>

                  </complexType>

                  <complexType name="Group">

                        <sequence>

                              <element name="description" type="string" minOccurs="0"/>

                        </sequence>

                        <attribute name="groupName" type="string" use="required"/>

                  </complexType>

</xsd:schema>

                  <supportedSchemaEntity entityName=”Account”/>

                  <supportedSchemaEntity entityName=”Group”/>

            </schema>

            <capabilities>

                  <capability namespaceURI=”urn:oasis:names:tc:SPML:2.0:bulk”/>

                  <capability namespaceURI=”urn:oasis:names:tc:SPML:2.0:search”/>

                  <capability namespaceURI=”urn:oasis:names:tc:SPML:2.0:password”>

                        <appliesTo entityName=”Account”/>

                  </capability>

                  <capability namespaceURI=”urn:oasis:names:tc:SPML:2.0:suspend”>

                        <appliesTo entityName=”Account”/>

                  </capability>

                  <capability namespaceURI=”urn:oasis:names:tc:SPML:2.0:reference”>

                        <appliesTo entityName=”Account”/>

                        <referenceDefinition typeOfReference=”owner”>

                              <schemaEntity entityName=”Account”/>

                              <canReferTo entityName=”Person” targetID=“target2”/>

                        </referenceDefinition>

                        <referenceDefinition typeOfReference=”memberOf”>

                              <schemaEntity entityName=”Account”/>

                              <canReferTo entityName=”Group”/>

                        </referenceDefinition>

                  </capability>

            </capabilities>

      </target>

 

      <target targetID=“target2” profile="urn:oasis:names:tc:SPML:2.0:profiles:XSD">

            <schema>

<xsd:schema targetNamespace="urn:example:schema:target2" xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:spml="urn:oasis:names:tc:SPML:2:0" elementFormDefault="qualified">

                  <complexType name="Person">

                        <sequence>

                              <element name="dn" type="string"/>

                              <element name="email" type="string" minOccurs="0"/>

                        </sequence>

                        <attribute name="cn" type="string" use="required"/>

                        <attribute name="firstName" type="string" use="required"/>

                        <attribute name="lastName" type="string" use="required"/>

                        <attribute name="fullName" type="string" use="required"/>

                  </complexType>

                  <complexType name="Organization">

                        <sequence>

                              <element name="dn" type="string"/>

                              <element name="description" type="string" minOccurs="0"/>

                        </sequence>

                        <attribute name="cn" type="string" use="required"/>

                  </complexType>

                  <complexType name="OrganizationalUnit">

                        <sequence>

                              <element name="dn" type="string"/>

                              <element name="description" type="string" minOccurs="0"/>

                        </sequence>

                        <attribute name="cn" type="string" use="required"/>

                  </complexType>

</xsd:schema>

                  <supportedSchemaEntity entityName=”Person”/>

                  <supportedSchemaEntity entityName=”Organization” isContainer=”true”/>

                  <supportedSchemaEntity entityName=”OrganizationalUnit” isContainer=”true”/>

            </schema>

            <capabilities>

                  <capability namespaceURI=”urn:oasis:names:tc:SPML:2.0:bulk”/>

                  <capability namespaceURI=”urn:oasis:names:tc:SPML:2.0:search”/>

                  <capability namespaceURI=”urn:oasis:names:tc:SPML:2.0:password”>

                        <appliesTo entityName=”Person”/>

                  </capability>

                  <capability namespaceURI =”urn:oasis:names:tc:SPML:2.0:suspend”>

                        <appliesTo entityName=”Person”/>

                  </capability>

                  <capability namespaceURI =”urn:oasis:names:tc:SPML:2.0:reference”>

                        <appliesTo entityName=”Person”/>

                        <referenceDefinition typeOfReference=”owns”>

                              <schemaEntity entityName=”Person”/>

                              <canReferTo entityName=”Account” targetID=“target1”/>

                        </referenceDefinition>

                  </capability>

            </capabilities>

      </target>

</listTargetsResponse>

This example <listTargetsResponse> contains two instances of <target> that are named target1 and target2.  Each of these targets contains a simple schema.  

The schema for target1 defines two entities: Account and Group.  The schema for target1 declares each of these entities as a supported schema entity. The provider declares that target1 supports the Bulk capability and Search capability for both Account and Group. The provider also declares that target1 supports the Password, Suspend, and Reference capabilities for Account.

The schema for target2 defines three entities: Person, Organization and OrganizationalUnit.  The schema for target2 declares each of these entities as a supported schema entity.  The provider declares that target2 supports the Bulk capability and Search capability for all three schema entities.  The provider also declares that target2 supports the Password, Suspend, and Reference capabilities for instances of Person (but not for instances of Organization or OrganizationalUnit).

Reference Definitions.  Within target1’s declaration of the Reference Capability for Account, the provider also declares two types of references: owner and memberOf. The provider declares that an instance of Account on target1 may refer to an instance of Person on target2 as its owner.  An instance of Account on target1 may also use a memberOf type of reference to refer to an instance of Group on target1.

Within target2’s declaration of the Reference Capability for Person, the provider declares that a Person on target2 may own an Account on target1.  (That is, an instance of Person on target2 may use an "owns" type of reference to refer to an instance of Account on target1.) Note that the “owns” type of reference may be (but is not necessarily) an inverse of the “owner” type of reference.  For more information, please see the section titled “Reference Capability”.

NOTE: Subsequent examples within this section will build on this example, using the target definitions returned in this example. Examples will also build upon each other. An object that is created in the example of the add operation will be modified or deleted in later examples.

3.6.1.2add

The add operation enables a requestor to create a new object on a target and (optionally) to bind the object beneath a specified parent object (thus forming a hierarchy of containment).

The subset of the Core XSD that is most relevant to the add operation follows.

 

   <complexType name=”CapabilityDataType”>

      <complexContent>

         <extension base="spml:ExtensibleType">

            <annotation>

               <documentation>Contains elements specific to a capability.</documentation>

            </annotation>

            <attribute name="mustUnderstand" type="boolean" use="optional"/>

            <attribute name="capabilityURI" type="anyURI"/>

         </extension>

      </complexContent>

   </complexType>

 

   <simpleType name="ReturnDataType">

      <restriction base="string">

         <enumeration value="identifier"/>

         <enumeration value="data"/>

         <enumeration value="everything"/>

      </restriction>

   </simpleType>

 

      <complexType name="PSOType">

      <complexContent>

         <extension base="spml:ExtensibleType">

            <sequence>

               <element name="psoID" type="spml:PSOIdentifierType" />

               <element name="data" type="spml:ExtensibleType" minOccurs="0" />

               <element name="capabilityData" type="spml:CapabilityDataType" minOccurs="0" maxOccurs="unbounded" />

            </sequence>

         </extension>

      </complexContent>

   </complexType>

 

   <complexType name="AddRequestType">

      <complexContent>

         <extension base="spml:RequestType">

            <sequence>

               <element name="psoID" type="spml:PSOIdentifierType" minOccurs="0"/>

               <element name="containerID" type="spml:PSOIdentifierType" minOccurs="0"/>

               <element name="data" type="spml:ExtensibleType"/>

               <element name="capabilityData" type="spml:CapabilityDataType" minOccurs="0" maxOccurs="unbounded" />

            </sequence>

            <attribute name="targetID" type="string" use="optional">

            <attribute name="returnData" type="spml:ReturnDataType" use="optional" default="everything"/>

         </extension>

      </complexContent>

   </complexType>

 

   <complexType name="AddResponseType">

      <complexContent>

         <extension base="spml:ResponseType">

            <sequence>

               <element name="pso" type="spml:PSOType" minOccurs="0"/>

            </sequence>

         </extension>

      </complexContent>

   </complexType>

 

   <element name="addRequest" type="spml:AddRequestType"/>

   <element name="addResponse" type="spml:AddResponseType"/>

 

3.6.1.2.1 addRequest (normative)

A requestor MUST send an <addRequest> to a provider in order to (ask the provider to) create a new object.

Execution. A <addRequest> MAY specify “executionMode”.
See the section titled “
Determining execution mode”.

TargetID. An <addRequest> SHOULD specify targetID”.

·         If the provider exposes only one target in its <listTargetsResponse>,
then a requestor MAY omit the
"targetID" attribute of an <addRequest>.

·         If the provider exposes more than one target in its <listTargetsResponse>,
then a requestor MUST specify the
"targetID" attribute of an <addRequest>.
Any
"targetID" value must specify a valid target.  (That is, the value of any "targetID" in an <addRequest> MUST match the "targetID" of a <target> that is contained in the provider's <listTargetsResponse>.)

psoID.  An <addRequest> MAY contain a <psoID>.  (A requestor supplies <psoID> in order to specify an identifier for the new object.  See the section titled “PSO Identifier (normative)”.)

ContainerID. An <addRequest> MAY contain a <containerID>. (A requestor supplies <containerID> in order to specify an existing object under which the new object should be bound.)

·         A requestor that wants to bind a new object in the top-level namespace of a target
MUST NOT supply <containerID>.

·         A requestor that wants to bind a new object beneath a specific object on a target
MUST supply
<containerID>. Any <containerID> must identify an existing object.
(That is, the content of
<containerID> in an <addRequest> must match the <psoID> of an object that already exists on the target.)

Data. An <addRequest> MUST contain a <data> element that supplies initial content for the new object. A <data> element MUST contain only elements and attributes defined by the target schema as valid for the schema entity of which the object to be added is an instance.

CapabilityData. An <addRequest> element MAY contain any number of <capabilityData> elements. (Each <capabilityData> element contains data specific to a single capability.  Each <capabilityData> element may contain any number of items of capability-specific data. Capability-specific data need not be defined by the target schema as valid for schema entity of which the object to be added is an instance. 
See the section titled "
CapabilityData in a Request (normative)".

ReturnData. An <addRequest> MAY have a “returnData” attribute that tells the provider which types of data to include in the provider’s response.

·         A requestor that wants the provider to return nothing of the added object
MUST specify
“returnData=’nothing’”.

·         A requestor that wants the provider to return only the identifier of the added object
MUST specify
“returnData=’identifier’”.

·         A requestor that wants the provider to return the identifier of the added object
plus the XML representation of the object (as defined in the schema of the target)
MUST specify
“returnData=’data’”.

·         A requestor that wants the provider to return the identifier of the added object
plus the XML representation of the object (as defined in the schema of the target)
plus any capability-specific data that is associated with the object
MAY specify
“returnData=’everything’” or MAY omit the “returnData” attribute
(since
“returnData=’everything’” is the default).

3.6.1.2.2 addResponse (normative)

A provider that receives an <addRequest> from a requestor that the provider trusts MUST examine the content of the <addRequest>. If the request is valid, the provider MUST create the requested object under the specified parent (i.e., target or container object) if it is possible to do so.

PSO Identifier. The provider MUST create the object with any <psoID> that the <addRequest> supplies.  If the provider cannot create the object with the specified <psoID> (e.g., because the <psoID> is not valid or because an object that already exists has that <psoID>), then the provider must fail the request.  See the topic named "Error" below within this section.

Data. The provider MUST create the object with any XML element or attribute contained by the <data> element in the <addRequest>.

CapabilityData. The provider SHOULD associate with the created object the content of each <capabilityData> that the <addRequest> contains. The “mustUnderstand” attribute of each <capabilityData> indicates whether the provider MUST process the content of the <capabilityData> as the corresponding capability specifies.  See the sections titled "CapabilityData in a Request (normative)" and "CapabilityData Processing (normative)".

Also see the section titled "CapabilityData Errors (normative)".

Execution. If an <addRequest> does not specify a type of execution, a provider MUST choose a type of execution for the requested operation.
See the section titled “
Determining execution mode”.

Response. The provider must return to the requestor an <addResponse>.

Status. The <addResponse> MUST have a “status” attribute that indicates whether the provider successfully created the requested object.  See the section titled Status (normative).

PSO and ReturnData. If the provider successfully created the requested object, the <addResponse> MUST contain an <pso> element that contains the (XML representation of the) newly created object.

·         A <pso> element MUST contain a <psoID> element.
The
<psoID> element MUST contain the identifier of the newly created object.
See the section titled “
PSO Identifier (normative)”.

-          If the <addRequest> supplies a <psoID>, then <psoID> of the newly created object
MUST match the
<psoID> supplied by the <addRequest>.
(See the topic named "PSO Identifier" above within this section.)

-          If the <addRequest> does not supply <psoID>, the provider must generate a <psoID>
that uniquely identifies the newly created object.

·         A <pso> element MAY contain a <data> element.

-          If the <addRequest> specified “returnData=’identifier’”
then the
<pso> MUST NOT contain a <data> element.

-          Otherwise, if the <addRequest> specified “returnData=’data’”
or (if the
<addRequest> specified) “returnData=’everything’”
or (if the
<addRequest>) omitted the “returnData” attribute,
then the
<pso> MUST contain exactly one <data> element that contains the XML representation of the object.
This XML must be valid according to the schema of the target for the schema entity of which the newly created object is an instance.

·         A <pso> element MAY contain any number of <capabilityData> elements. Each <capabilityData> element contains a set of capability-specific data that is associated with the newly created object (for example, a reference to another object).
See the section titled "
CapabilityData in a Response (normative)".

-          <