OASIS Openopen access

ebXML Registry Services and Protocols v3.0 (2005-05-01)

OASIS Open · OASIS Open

OASIS Open · Standards · License: Open Access

ebxml os protocols registry regrep rs v3.0

oasis, standard, oasis open, specification, open standard, oasis_regrep-rs-3.0-os, ebxml, registry, services, and, protocols, v3.0, regrep-rs-3.0-os, regrep, rs, os, 3.0

ebXML Registry Services and Protocols Version 3.0

OASIS Standard, 2 May, 2005

5 6

Document identifier: regrep-rs-3.0-os

7 8

Location: http://docs.oasis-open.org/regrep-rs/v3.0/

Editors:

Name Sally Fuger Farrukh Najmi Nikola Stojanovic

Affiliation Individual Sun Microsystems RosettaNet

10 11

Contributors: Name Diego Ballve Ivan Bedini Kathryn Breininger Joseph Chiusano Peter Kacandes Paul Macias Carl Mattocks Matthew MacKenzie Monica Martin Richard Martell Duane Nickull Goran Zugic

Affiliation Individual France Telecom The Boeing Company Booz Allen Hamilton Adobe Systems LMI Government Consulting CHECKMi Adobe Systems Sun Microsystems Galdos Systems Inc Adobe Systems ebXMLsoft Inc.

May 2, 2005 Page 1 of 133

12 13 14

Abstract: This document defines the services and protocols for an ebXML Registry A separate document, ebXML Registry: Information Model [ebRIM], defines the types of metadata and content that can be stored in an ebXML Registry.

15 16 17 18 19

Status: This document is an OASIS ebXML Registry Technical Committee Approved Draft Specification.

20 21 22 23

Committee members should send comments on this specification to the [email protected] list. Others should subscribe to and send comments to the [email protected] list. To subscribe, send an email message to [email protected] with the word "subscribe" as the body of the message.

24 25 26 27

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the OASIS ebXML Registry TC web page (http://www.oasis-open.org/committees/regrep/).

May 2, 2005 Page 2 of 133

28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44

Table of Contents 1 Introduction.............................................................................................................................................13 1.1 Audience.........................................................................................................................................13 1.2 Terminology....................................................................................................................................13 1.3 Notational Conventions...................................................................................................................13 1.3.1 UML Diagrams.........................................................................................................................13 1.3.2 Identifier Placeholders.............................................................................................................13 1.3.3 Constants.................................................................................................................................13 1.3.4 Bold Text..................................................................................................................................14 1.3.5 Example Values......................................................................................................................14 1.4 XML Schema Conventions.............................................................................................................14 1.4.1 Schemas Defined by ebXML Registry....................................................................................14 1.4.2 Schemas Used By ebXML Registry........................................................................................15 1.5 Registry Actors................................................................................................................................16 1.6 Registry Use Cases........................................................................................................................16 1.7 Registry Architecture......................................................................................................................16 1.7.1 Registry Clients........................................................................................................................17

1.7.1.1 Client API............................................................................................................................................17

1.7.2 Registry Service Interfaces......................................................................................................17 1.7.3 Service Interface: Protocol Bindings.......................................................................................17 1.7.4 Authentication and Authorization............................................................................................18 1.7.5 Metadata Registry and Content Repository............................................................................18 2 Registry Protocols..................................................................................................................................19 2.1 Requests and Responses...............................................................................................................19 2.1.1 RegistryRequestType..............................................................................................................19

47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62

2.1.1.1 Syntax:................................................................................................................................................19 2.1.1.2 Parameters:.........................................................................................................................................20 2.1.1.3 Returns:............................................................................................................................................... 20 2.1.1.4 Exceptions:........................................................................................................................................20

2.1.2 RegistryRequest......................................................................................................................20 2.1.3 RegistryResponseType...........................................................................................................20 2.1.3.1 Syntax:................................................................................................................................................21 2.1.3.2 Parameters:.........................................................................................................................................21

2.1.4 RegistryResponse...................................................................................................................21 2.1.5 RegistryErrorList......................................................................................................................21

2.1.5.1 Syntax:................................................................................................................................................22 2.1.5.2 Parameters:.........................................................................................................................................22

2.1.6 RegistryError............................................................................................................................22

2.1.6.1 Syntax:................................................................................................................................................22 2.1.6.2 Parameters:.........................................................................................................................................22

67 68 69 70 71 72

3 SOAP Binding........................................................................................................................................24 3.1 ebXML Registry Service Interfaces: Abstract Definition.................................................................24 3.2 ebXML Registry Service Interfaces SOAP Binding........................................................................25 3.3 ebXML Registry Service Interfaces SOAP Service Template........................................................25 3.4 Mapping of Exception to SOAP Fault ............................................................................................26 regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 3 of 133

73 74 75 76 77 78 79 80 81

4 HTTP Binding.........................................................................................................................................27 4.1 HTTP Interface URL Pattern...........................................................................................................27 4.2 RPC Encoding URL........................................................................................................................27 4.2.1 Standard URL Parameters......................................................................................................27 4.2.2 QueryManager Binding...........................................................................................................28 4.2.2.1 Sample getRegistryObject Request...................................................................................................28 4.2.2.2 Sample getRegistryObject Response.................................................................................................28 4.2.2.3 Sample getRepositoryItem Request...................................................................................................29 4.2.2.4 Sample getRepositoryItem Response................................................................................................29

4.2.3 LifeCycleManager HTTP Interface..........................................................................................29 4.3 Submitter Defined URL...................................................................................................................29 4.3.1 Submitter defined URL Syntax................................................................................................30 4.3.2 Assigning URL to a RegistryObject ........................................................................................30 4.3.3 Assigning URL to a Repository Item ......................................................................................31 4.4 File Path Based URL......................................................................................................................31 4.4.1 File Folder Metaphor...............................................................................................................31 4.4.2 File Path of a RegistryObject..................................................................................................31

4.4.2.1 File Path Example...............................................................................................................................32

4.4.3 Matching URL To Objects.......................................................................................................32 4.4.4 URL Matches a Single Object.................................................................................................32 4.4.5 URL Matches Multiple Object.................................................................................................33 4.4.6 Directory Listing.......................................................................................................................33 4.4.7 Access Control In RegistryPackage Hierarchy.......................................................................34 4.5 URL Resolution Algorithm..............................................................................................................34 4.6 Security Consideration...................................................................................................................34 4.7 Exception Handling.........................................................................................................................35 5 Lifecycle Management Protocols...........................................................................................................36 5.1 Submit Objects Protocol.................................................................................................................36 5.1.1 SubmitObjectsRequest............................................................................................................36

82 83 84 85 86 87 88

92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118

5.1.1.1 Syntax:................................................................................................................................................36 5.1.1.2 Parameters:.........................................................................................................................................37 5.1.1.3 Returns:...............................................................................................................................................37 5.1.1.4 Exceptions:.........................................................................................................................................37

5.1.2 Unique ID Generation..............................................................................................................37 5.1.3 ID Attribute And Object References........................................................................................37 5.1.4 Audit Trail................................................................................................................................38 5.1.5 Sample SubmitObjectsRequest..............................................................................................38 5.2 The Update Objects Protocol.........................................................................................................38 5.2.1 UpdateObjectsRequest...........................................................................................................39 5.2.1.1 Syntax:................................................................................................................................................39 5.2.1.2 Parameters:.........................................................................................................................................39 5.2.1.3 Returns:............................................................................................................................................... 39 5.2.1.4 Exceptions:........................................................................................................................................39

5.2.2 Audit Trail................................................................................................................................40 5.3 The Approve Objects Protocol........................................................................................................40 5.3.1 ApproveObjectsRequest.........................................................................................................40

May 2, 2005 Page 4 of 133

119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148

5.3.1.1 Syntax:................................................................................................................................................40 5.3.1.2 Parameters:.........................................................................................................................................40 5.3.1.3 Returns:...............................................................................................................................................41 5.3.1.4 Exceptions:........................................................................................................................................41

5.3.2 Audit Trail................................................................................................................................41 5.4 The Deprecate Objects Protocol....................................................................................................41 5.4.1 DeprecateObjectsRequest......................................................................................................41 5.4.1.1 Syntax:................................................................................................................................................42 5.4.1.2 Parameters:.........................................................................................................................................42 5.4.1.3 Returns:...............................................................................................................................................42 5.4.1.4 Exceptions:........................................................................................................................................42

5.4.2 Audit Trail................................................................................................................................42 5.5 The Undeprecate Objects Protocol................................................................................................42 5.5.1 UndeprecateObjectsRequest..................................................................................................43 5.5.1.1 Syntax:................................................................................................................................................43 5.5.1.2 Parameters:.........................................................................................................................................43 5.5.1.3 Returns:...............................................................................................................................................44 5.5.1.4 Exceptions:........................................................................................................................................44

5.5.2 Audit Trail................................................................................................................................44 5.6 The Remove Objects Protocol........................................................................................................44 5.6.1 RemoveObjectsRequest.........................................................................................................44 5.6.1.1 Syntax:................................................................................................................................................44 5.6.1.2 Parameters:.........................................................................................................................................45 5.6.1.3 Returns:...............................................................................................................................................45 5.6.1.4 Exceptions:........................................................................................................................................45

5.7 Registry Managed Version Control.................................................................................................46 5.7.1 Version Controlled Resources.................................................................................................46 5.7.2 Versioning and Object Identification.......................................................................................46 5.7.3 Logical ID.................................................................................................................................46 5.7.4 Version Identification...............................................................................................................46

150

5.7.4.1 Version Identification for a RegistryObject.........................................................................................47 5.7.4.2 Version Identification for a RepositoryItem........................................................................................47

151

5.7.5 Versioning of ExtrinsicObject and Repository Items...............................................................47

152

5.7.5.1 ExtrinsicObject and Shared RepositoryItem......................................................................................48

153

164

5.7.6 Versioning and Composed Objects.........................................................................................48 5.7.7 Versioning and References.....................................................................................................48 5.7.8 Versioning and Audit Trail.......................................................................................................48 5.7.9 Inter-versions Association.......................................................................................................49 5.7.10 Client Initiated Version Removal...........................................................................................49 5.7.11 Registry Initiated Version Removal.......................................................................................49 5.7.12 Locking and Concurrent Modifications..................................................................................49 5.7.13 Version Creation....................................................................................................................49 5.7.14 Versioning Override...............................................................................................................50 6 Query Management Protocols...............................................................................................................51 6.1 Ad Hoc Query Protocol...................................................................................................................51 6.1.1 AdhocQueryRequest...............................................................................................................51

165

6.1.1.1 Syntax:................................................................................................................................................51

149

154 155 156 157 158 159 160 161 162 163

May 2, 2005 Page 5 of 133

168

6.1.1.2 Parameters:.........................................................................................................................................52 6.1.1.3 Returns:...............................................................................................................................................52 6.1.1.4 Exceptions:........................................................................................................................................52

169

6.1.2 AdhocQueryResponse............................................................................................................52

170 171

6.1.2.1 Syntax:................................................................................................................................................52 6.1.2.2 Parameters:.........................................................................................................................................53

172

6.1.3 AdhocQuery.............................................................................................................................53

173 174

6.1.3.1 Syntax:................................................................................................................................................53 6.1.3.2 Parameters:.........................................................................................................................................53

175

6.1.4 ReponseOption.......................................................................................................................53

176

6.1.4.1 Syntax:................................................................................................................................................54 6.1.4.2 Parameters:.........................................................................................................................................54

166 167

177 178 179 180 181

6.2 Iterative Query Support..................................................................................................................54 6.2.1 Query Iteration Example.........................................................................................................55 6.3 Stored Query Support.....................................................................................................................55 6.3.1 Submitting a Stored Query......................................................................................................55

183

6.3.1.1 Declaring Query Parameters..............................................................................................................55 6.3.1.2 Canonical Context Parameters...........................................................................................................56

184

6.3.2 Invoking a Stored Query..........................................................................................................56

185

6.3.2.1 Specifying Query Invocation Parameters...........................................................................................57

186

6.3.3 Response to Stored Query Invocation....................................................................................57 6.3.4 Access Control on a Stored Query..........................................................................................57 6.3.5 Canonical Query: Get Client’s User Object............................................................................58 6.4 SQL Query Syntax..........................................................................................................................58 6.4.1 Relational Schema for SQL Queries.......................................................................................58 6.4.2 SQL Query Results.................................................................................................................58 6.5 Filter Query Syntax.........................................................................................................................59 6.5.1 Filter Query Structure..............................................................................................................59 6.5.2 Query Elements.......................................................................................................................59 6.5.3 Filter Elements........................................................................................................................60

182

187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212

6.5.3.1 FilterType............................................................................................................................................61 6.5.3.2 SimpleFilterType.................................................................................................................................61 6.5.3.3 BooleanFilter.......................................................................................................................................62 6.5.3.4 FloatFilter............................................................................................................................................62 6.5.3.5 IntegerFilter.........................................................................................................................................63 6.5.3.6 DateTimeFilter....................................................................................................................................63 6.5.3.7 StringFilter...........................................................................................................................................63 6.5.3.8 CompoundFilter..................................................................................................................................63

6.5.4 Nested Query Elements..........................................................................................................64 6.5.5 Branch Elements.....................................................................................................................64 6.6 Query Examples.............................................................................................................................65 6.6.1 Name and Description Queries...............................................................................................65 6.6.2 Classification Queries.............................................................................................................66 6.6.2.1 Retrieving ClassificationSchemes......................................................................................................66 6.6.2.2 Retrieving Children of Specified ClassificationNode..........................................................................66 6.6.2.3 Retrieving Objects Classified By a ClassificationNode......................................................................66 6.6.2.4 Retrieving Classifications that Classify an Object..............................................................................67

May 2, 2005 Page 6 of 133

213

6.6.3 Association Queries................................................................................................................67

214

6.6.3.1 Retrieving All Associations With Specified Object As Source...........................................................67 6.6.3.2 Retrieving All Associations With Specified Object As Target............................................................67 6.6.3.3 Retrieving Associated Objects Based On Association Type.............................................................68 6.6.3.4 Complex Association Query...............................................................................................................68

215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258

6.6.4 Package Queries.....................................................................................................................68 6.6.5 ExternalLink Queries...............................................................................................................69 6.6.6 Audit Trail Queries..................................................................................................................70 7 Event Notification Protocols...................................................................................................................71 7.1 Use Cases.......................................................................................................................................71 7.1.1 CPP Has Changed..................................................................................................................71 7.1.2 New Service is Offered............................................................................................................71 7.1.3 Monitor Download of Content..................................................................................................71 7.1.4 Monitor Price Changes............................................................................................................71 7.1.5 Keep Replicas Consistent With Source Object.......................................................................71 7.2 Registry Events...............................................................................................................................71 7.3 Subscribing to Events.....................................................................................................................72 7.3.1 Event Selection........................................................................................................................72 7.3.2 Notification Action....................................................................................................................72 7.3.3 Subscription Authorization.......................................................................................................73 7.3.4 Subscription Quotas................................................................................................................73 7.3.5 Subscription Expiration............................................................................................................73 7.3.6 Subscription Rejection.............................................................................................................73 7.4 Unsubscribing from Events.............................................................................................................73 7.5 Notification of Events......................................................................................................................73 7.6 Retrieval of Events..........................................................................................................................74 7.7 Pruning of Events............................................................................................................................74 8 Content Management Services.............................................................................................................75 8.1 Content Validation..........................................................................................................................75 8.1.1 Content Validation: Use Cases...............................................................................................75 8.1.1.1 Validation of HL7 Conformance Profiles............................................................................................75 8.1.1.2 Validation of Business Processes......................................................................................................75 8.1.1.3 Validation of UBL Business Documents............................................................................................75

8.2 Content Cataloging.........................................................................................................................76 8.2.1 Content-based Discovery: Use Cases....................................................................................76 8.2.1.1 Find All CPPs Where Role is “Buyer”.................................................................................................76 8.2.1.2 Find All XML Schema’s That Use Specified Namespace..................................................................76 8.2.1.3 Find All WSDL Descriptions with a SOAP Binding............................................................................76

8.3 Abstract Content Management Service.........................................................................................76 8.3.1 Inline Invocation Model ...........................................................................................................77 8.3.2 Decoupled Invocation Model...................................................................................................78 8.4 Content Management Service Protocol..........................................................................................79 8.4.1 ContentManagementServiceRequestType.............................................................................79 8.4.1.1 Syntax:................................................................................................................................................79 8.4.1.2 Parameters:........................................................................................................................................80 8.4.1.3 Returns:..............................................................................................................................................80

May 2, 2005 Page 7 of 133

259

8.4.1.4 Exceptions:........................................................................................................................................80

260

8.4.2 ContentManagementServiceResponseType..........................................................................80

261

8.4.2.1 Syntax:................................................................................................................................................80 8.4.2.2 Parameters:........................................................................................................................................81

262 263 264 265 266 267 268 269 270 271

8.5 Publishing / Configuration of a Content Management Service......................................................81 8.5.1 Multiple Content Management Services and Invocation Control Files...................................82 8.6 Invocation of a Content Management Service...............................................................................83 8.6.1 Resolution Algorithm For Service and Invocation Control File...............................................83 8.6.2 Audit Trail and Cataloged Content..........................................................................................83 8.6.3 Referential Integrity.................................................................................................................83 8.6.4 Error Handling.........................................................................................................................83 8.7 Validate Content Protocol...............................................................................................................84 8.7.1 ValidateContentRequest.........................................................................................................84

275

8.7.1.1 Syntax:................................................................................................................................................84 8.7.1.2 Parameters:........................................................................................................................................85 8.7.1.3 Returns:..............................................................................................................................................85 8.7.1.4 Exceptions:........................................................................................................................................85

276

8.7.2 ValidateContentResponse......................................................................................................85

277

8.7.2.1 Syntax:................................................................................................................................................85 8.7.2.2 Parameters:........................................................................................................................................85

272 273 274

278 279 280

8.8 Catalog Content Protocol................................................................................................................86 8.8.1 CatalogContentRequest..........................................................................................................86

284

8.8.1.1 Syntax:................................................................................................................................................86 8.8.1.2 Parameters:........................................................................................................................................87 8.8.1.3 Returns:..............................................................................................................................................87 8.8.1.4 Exceptions:........................................................................................................................................87

285

8.8.2 CatalogContentResponse.......................................................................................................87

286

8.8.2.1 Syntax:................................................................................................................................................87 8.8.2.2 Parameters:........................................................................................................................................88

281 282 283

287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305

8.9 Illustrative Example: Canonical XML Cataloging Service..............................................................88 8.10 Canonical XML Content Cataloging Service................................................................................89 8.10.1 Publishing of Canonical XML Content Cataloging Service...................................................90 9 Cooperating Registries Support.............................................................................................................91 9.1 Cooperating Registries Use Cases...............................................................................................91 9.1.1 Inter-registry Object References.............................................................................................91 9.1.2 Federated Queries..................................................................................................................91 9.1.3 Local Caching of Data from Another Registry.........................................................................91 9.1.4 Object Relocation....................................................................................................................91 9.2 Registry Federations.......................................................................................................................92 9.2.1 Federation Metadata...............................................................................................................92 9.2.2 Local Vs. Federated Queries...................................................................................................93 9.2.2.1 Local Queries......................................................................................................................................93 9.2.2.2 Federated Queries..............................................................................................................................93 9.2.2.3 Membership in Multiple Federations..................................................................................................94

9.2.3 Federated Lifecycle Management Operations........................................................................94 9.2.4 Federations and Local Caching of Remote Data....................................................................94 9.2.5 Caching of Federation Metadata.............................................................................................94 regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 8 of 133

306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326

9.2.6 Time Synchronization Between Registry Peers......................................................................94 9.2.7 Federations and Security........................................................................................................94 9.2.8 Federation Lifecycle Management Protocols .........................................................................95 9.2.8.1 Joining a Federation...........................................................................................................................95 9.2.8.2 Creating a Federation.........................................................................................................................95 9.2.8.3 Leaving a Federation..........................................................................................................................95 9.2.8.4 Dissolving a Federation......................................................................................................................95

9.3 Object Replication..........................................................................................................................96 9.3.1 Use Cases for Object Replication...........................................................................................96 9.3.2 Queries And Replicas.............................................................................................................96 9.3.3 Lifecycle Operations And Replicas.........................................................................................97 9.3.4 Object Replication and Federated Registries.........................................................................97 9.3.5 Creating a Local Replica.........................................................................................................97 9.3.6 Transactional Replication........................................................................................................97 9.3.7 Keeping Replicas Current.......................................................................................................97 9.3.8 Lifecycle Management of Local Replicas................................................................................98 9.3.9 Tracking Location of a Replica................................................................................................98 9.3.10 Remote Object References to a Replica..............................................................................98 9.3.11 Removing a Local Replica.....................................................................................................98 9.4 Object Relocation Protocol.............................................................................................................98 9.4.1 RelocateObjectsRequest.......................................................................................................101

329

9.4.1.1 Parameters:......................................................................................................................................101 9.4.1.2 Returns:............................................................................................................................................101 9.4.1.3 Exceptions:......................................................................................................................................101

330

9.4.2 AcceptObjectsRequest..........................................................................................................101

331

9.4.2.1 Parameters:......................................................................................................................................102 9.4.2.2 Returns:............................................................................................................................................102 9.4.2.3 Exceptions:......................................................................................................................................102

327 328

332 333

350

9.4.3 Object Relocation and Remote ObjectRefs..........................................................................102 9.4.4 Notification of Object Relocation To ownerAtDestination.....................................................103 9.4.5 Notification of Object Commit To sourceRegistry.................................................................103 9.4.6 Object Ownership and Owner Reassignment......................................................................103 9.4.7 Object Relocation and Timeouts...........................................................................................103 10 Registry Security................................................................................................................................104 10.1 Security Use Cases....................................................................................................................104 10.1.1 Identity Management...........................................................................................................104 10.1.2 Message Security................................................................................................................104 10.1.3 Repository Item Security.....................................................................................................104 10.1.4 Authentication.....................................................................................................................104 10.1.5 Authorization and Access Control.......................................................................................104 10.1.6 Audit Trail............................................................................................................................104 10.2 Identity Management..................................................................................................................105 10.3 Message Security.......................................................................................................................105 10.3.1 Transport Layer Security.....................................................................................................105 10.3.2 SOAP Message Security.....................................................................................................105

351

10.3.2.1 Request Message Signature..........................................................................................................105

334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349

May 2, 2005 Page 9 of 133

352 353 354 355 356 357

10.3.2.2 Response Message Signature.......................................................................................................105 10.3.2.3 KeyInfo Requirements....................................................................................................................106 10.3.2.4 Message Signature Validation........................................................................................................106 10.3.2.5 Message Signature Example..........................................................................................................106 10.3.2.6 Message With RepositoryItem: Signature Example.......................................................................107 10.3.2.7 SOAP Message Security and HTTP/S...........................................................................................109

371

10.3.3 Message Confidentiality......................................................................................................109 10.3.4 Key Distribution Requirements...........................................................................................109 10.4 Authentication.............................................................................................................................109 10.4.1 Registry as Authentication Authority...................................................................................110 10.4.2 External Authentication Authority........................................................................................110 10.4.3 Authenticated Session Support...........................................................................................110 10.5 Authorization and Access Control..............................................................................................110 10.6 Audit Trail....................................................................................................................................110 11 Registry SAML Profile........................................................................................................................112 11.1 Terminology................................................................................................................................112 11.2 Use Cases for SAML Profile.......................................................................................................112 11.2.1 Registry as SSO Participant: ..............................................................................................112 11.3 SAML Roles Played By Registry.................................................................................................113 11.3.1 Service Provider Role..........................................................................................................113

372

11.3.1.1 Service Provider Requirements......................................................................................................113

373

377

11.4 Registry SAML Interface.............................................................................................................114 11.5 Requirements for Registry SAML Profile ..................................................................................114 11.6 SSO Operation............................................................................................................................114 11.6.1 Scenario Actors...................................................................................................................114 11.6.2 SSO Operation – Unauthenticated HTTP Requestor.........................................................115

378

11.6.2.1 Scenario Sequence.........................................................................................................................115

379

11.6.3 SSO Operation – Authenticated HTTP Requestor..............................................................116 11.6.4 SSO Operation – Unuthenticated SOAP Requestor...........................................................116

358 359 360 361 362 363 364 365 366 367 368 369 370

374 375 376

380 381

11.6.4.1 Scenario Sequence.........................................................................................................................117

382

11.6.5 SSO Operation – Authenticated SOAP Requestor.............................................................118

383

11.6.5.1 Scenario Sequence........................................................................................................................119

384

11.6.6 <samlp:AuthnRequest> Generation Rules.........................................................................120 11.6.7 <samlp:Response> Processing Rules................................................................................120 11.6.8 Mapping Subject to User.....................................................................................................120 11.7 External Users.............................................................................................................................121 12 Native Language Support (NLS)........................................................................................................122 12.1 Terminology................................................................................................................................122 12.2 NLS and Registry Protcol Messages..........................................................................................122 12.3 NLS Support in RegistryObjects ................................................................................................122 12.3.1 Character Set of LocalizedString.........................................................................................124 12.3.2 Language of LocalizedString...............................................................................................124 12.4 NLS and Repository Items .........................................................................................................124 12.4.1 Character Set of Repository Items......................................................................................124 12.4.2 Language of Repository Items.............................................................................................124 13 Conformance......................................................................................................................................125

385 386 387 388 389 390 391 392 393 394 395 396 397

May 2, 2005 Page 10 of 133

398 399 400 401 402

13.1 Conformance Profiles..................................................................................................................125 13.2 Feature Matrix.............................................................................................................................125 14 References.........................................................................................................................................129 14.1 Normative References................................................................................................................129 14.2 Informative..................................................................................................................................130

403

May 2, 2005 Page 11 of 133

Illustration Index Figure 1: Simplified View of ebXML Registry Architecture.......................................................................17 Figure 2: Registry Protocol Request-Response Pattern...........................................................................19 Figure 3: Example Registry Package Hierarchy.......................................................................................32 Figure 4: Example of a Directory Listing...................................................................................................34 Figure 5: Submit Objects Protocol............................................................................................................36 Figure 6: Update Objects Protocol............................................................................................................38 Figure 7: Approve Objects Protocol..........................................................................................................40 Figure 8: Deprecate Objects Protocol.......................................................................................................41 Figure 9: Undeprecate Objects Protocol...................................................................................................43 Figure 10: Remove Objects Protocol........................................................................................................44 Figure 11: Ad Hoc Query Protocol............................................................................................................51 Figure 12: Filter Type Hierarchy...............................................................................................................61 Figure 13: Content Validation Service......................................................................................................75 Figure 14: Content Cataloging Service.....................................................................................................76 Figure 15: Content Management Service: Inline Invocation Model........................................................78 Figure 16: Content Management Service: Decoupled Invocation Model.................................................79 Figure 17: Cataloging Service Configuration............................................................................................82 Figure 18: Validate Content Protocol........................................................................................................84 Figure 19: Catalog Content Protocol.........................................................................................................86 Figure 20: Example of CPP cataloging using Canonical XML Cataloging Service..................................89 Figure 21: Inter-registry Object References..............................................................................................91 Figure 22: Registry Federations................................................................................................................92 Figure 23: Federation Metadata Example................................................................................................93 Figure 24: Object Replication...................................................................................................................96 Figure 25: Object Relocation....................................................................................................................99 Figure 26: Relocate Objects Protocol.....................................................................................................100 Figure 27: SAML SSO Typical Scenario.................................................................................................113 Figure 28: SSO Operation – Unauthenticated HTTP Requestor...........................................................115 Figure 29: SSO Operation - Unauthenticated SOAP Requestor............................................................117 Figure 30: SSO Operation - Authenticated SOAP Requestor................................................................119 404

May 2, 2005 Page 12 of 133

405

Introduction

406 407

An ebXML Registry is an information system that securely manages any content type and the standardized metadata that describes it.

408 409 410 411

The ebXML Registry provides a set of services that enable sharing of content and metadata between organizational entities in a federated environment. An ebXML Registry may be deployed within an application server, a web server or some other service container. The registry MAY be available to clients as a public, semi-public or private web site.

412 413

This document defines the services provided by an ebXML Registry and the protocols used by clients of the registry to interact with these services.

414 415

A separate document, ebXML Registry: Information Model [ebRIM], defines the types of metadata and content that can be stored in an ebXML Registry.

416

1.1

417

The target audience for this specification is the community of software developers who are:

418

•

419

•

420

1.2

421 422 423

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in IETF RFC 2119 [RFC2119].

424 425 426

The term “repository item” is used to refer to content (e.g., an XML document or a DTD) that resides in a repository for storage and safekeeping. Each repository item is described by a RegistryObject instance. The RegistryObject catalogs the RepositoryItem with metadata.

427

1.3

428 429

Throughout the document the following conventions are employed to define the data structures used. The following text formatting conventions are used to aide readability:

430

1.3.1

431 432

Unified Modeling Language [UML] diagrams are used as a way to concisely describe concepts. They are not intended to convey any specific Implementation or methodology requirements.

433

1.3.2

434 435 436 437 438

Listings may contain values that reference ebXML Registry objects by their id attribute. These id values uniquely identify the objects within the ebXML Registry. For convenience and better readability, these key values are replaced by meaningful textual variables to represent such id values. For example, the placeholder in the listing below refers to the unique id defined for an example Service object:

Audience

Implementers of ebXML Registry Services Implementers of ebXML Registry Clients

Terminology

Notational Conventions

UML Diagrams

Identifier Placeholders

439 440

<rim:Service id="${EXAMPLE_SERVICE_ID}">

441

1.3.3

Constants

442 443

Constant values are printed in the Courier New font always, regardless of whether they are defined by this document or a referenced document.

May 2, 2005 Page 13 of 133

444

1.3.4

Bold Text

445 446 447

Bold text is used in listings to highlight those aspects that are most relevant to the issue being discussed. In the listing below, an example value for the contentLocator slot is shown in italics if that is what the reader should focus on in the listing:

448 449 450 451 452

<rim:Slot name="urn:oasis:names:tc:ebxmlregrep:rim:RegistryObject:contentLocator"> ... </rim:Slot>

453 454

1.3.5

Example Values

455 456

These values are represented in italic font. In the listing below, an example value for the contentLocator slot is shown in italics:

457 458 459 460 461 462 463

<rim:Slot name="urn:oasis:names:tc:ebxmlregrep:rim:RegistryObject:contentLocator"> <rim:ValueList> <rim:Value>http://example.com/myschema.xsd</rim:Value> </rim:ValueList> </rim:Slot>

464 465

1.4

XML Schema Conventions

466 467 468 469 470

This specification uses schema documents conforming to W3C XML Schema [Schema1] and normative text to describe the syntax and semantics of XML-encoded objects and protocol messages. In cases of disagreement between the ebXML Registry schema documents and schema listings in this specification, the schema documents take precedence. Note that in some cases the normative text of this specification imposes constraints beyond those indicated by the schema documents.

471 472 473 474

Conventional XML namespace prefixes are used throughout this specification to stand for their respective namespaces as follows, whether or not a namespace declaration is present in the example. The use of these namespace prefixes in instance documents is non-normative. However, for consistency and understandability instance documents SHOULD use these namespace prefixes.

475

1.4.1

Schemas Defined by ebXML Registry

476

Prefix

XML Namespace

Comments

rim:

urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0

This is the Registry Information Model namespace [ebRIM]. The prefix is generally elided in mentions of Registry Information Model elements in text.

rs:

urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0

This is the ebXML Registry namespace that defines base types for registry service requests and responses [ebRS]. The prefix is generally elided in mentions of ebXML Registry protocol-related elements in text.

query:

urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0

This is the ebXML Registry query namespace that is used in the query protocols used between clients and the QueryManager service [ebRS].

May 2, 2005 Page 14 of 133

Prefix

XML Namespace

Comments

lcm:

urn:oasis:names:tc:ebxml-regrep:xsd:lcm:3.0

This is the ebXML Registry Life Cycle Management namespace that is used in the life cycle management protocols used between clients and the LifeCycleManager service [ebRS].

cms:

urn:oasis:names:tc:ebxml-regrep:xsd:cms:3.0

This is the ebXML Registry Content Management Services namespace that is used in the content management protocols used between registry and pluggable content managent services [ebRS].

1.4.2

Schemas Used By ebXML Registry

477 478 479

Prefix

XML Namespace

Comments

saml:

urn:oasis:names:tc:SAML:2.0:assertion

This is the SAML V2.0 assertion namespace [SAMLCore]. The prefix is generally elided in mentions of SAML assertion-related elements in text.

samlp:

urn:oasis:names:tc:SAML:2.0:protocol

This is the SAML V2.0 protocol namespace [SAMLCore]. The prefix is generally elided in mentions of XML protocol-related elements in text.

ecp:

urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp

This is the SAML V2.0 Enhanced Client Proxy profile namespace, specified in this document and in a schema [SAMLECPxsd].

ds:

http://www.w3.org/2000/09/xmldsig#

This is the XML Signature namespace [XMLSig].

xenc:

http://www.w3.org/2001/04/xmlenc#

This is the XML Encryption namespace [XMLEnc].

SOAPENV:

http://schemas.xmlsoap.org/soap/envelope

This is the SOAP V1.1 namespace [SOAP1.1].

paos:

urn:liberty:paos:2003-08

This is the Liberty Alliance PAOS (reverse SOAP) namespace.

xsi:

http://www.w3.org/2001/XMLSchema-instance

This namespace is defined in the W3C XML Schema specification [Schema1] for schema-related markup that appears in XML instances.

wsse:

http://docs.oasis-open.org/wss/2004/01/oasis200401-wss-wssecurity-secext-1.0.xsd

This namespace is defined by the Web Services Security: SOAP Message Security 1.0 specification [WSS-SMS]. It is used by registry to secure soap message communication.

May 2, 2005 Page 15 of 133

Prefix

XML Namespace

Comments

http://docs.oasis-open.org/wss/2004/01/oasis200401-wss-wssecurity-utility-1.0.xsd

wsu:

This namespace is defined by the Web Services Security: SOAP Message Security 1.0 specification [WSS-SMS]. It is used by registry to secure soap message communication.

480 481

1.5

Registry Actors

482

This section describes the various actors who interact with the registry. Actor

Description

Registry Operator

An organization that operates an ebXMl Registry and makes it's services available.

Registry Administrator

A privileged user of the registry that is responsible for performing administrative tasks necessary for the ongoing operation of the registry. Such a user is analogous to a “super user” that is authorized to perform any action.

Registry Guest

A user of the registry whose identity is not known to the registry. Such a user has limited privileges within the registry.

Registered User

A user of the registry whose identity is known to the registry as an authorized user of the registry.

Submitter

A user that submits content and or metadata to the registry. A Submitter MUST be a Registered User.

Registry Client

A software program that interacts with the registry using registry protocols.

483 484

1.6

Registry Use Cases

485 486 487

Once deployed, the ebXML Registry provides generic content and metadata management services and as such supports an open-ended and broad set of use cases. The following are some common use cases that are being addressed by ebXML Registry.

488 489

•

Web Services Registry: publish, management, discovery and reuse of web service discriptions in WSDL, ebXML CPPA and other forms.

490 491 492

•

Controlled Vocabulary Registry: Enables publish, management, discovery and reuse of controlled vocabularies including taxonomies, code lists, ebXML Core Components, XML Schema and UBL schema.

493 494

•

Business Process Registry: Enables publish, management, discovery and reuse of Business Process specifications such as ebXML BPSS, BPEL and other forms.

495

•

Electronic Medical Records Repository

496

•

Geological Information System (GIS) Repository that stores GIS data from sensors

497 498

1.7

Registry Architecture

499

The following figure provides a simplified view of the architecture of the ebXML Registry.

May 2, 2005 Page 16 of 133

500

Figure 1: Simplified View of ebXML Registry Architecture

502

1.7.1

Registry Clients

503 504 505

A Registry Client is a software program that interacts with the registry using registry protocols. The Registry Client MAY be a Graphical User Interface (GUI), software service or agent. The Registry Client typically accesses the registry using SOAP 1.1 with Attachments [SwA] protocol.

506 507 508

A Registry Client may run on a client machine or may be a web tier service running on a server and may accessed by a web browser. In either case the Registry Client interacts with the registry using registry protocols.

509

1.7.1.1

510 511 512

A Registry client MAY access a registry interface directly. Alternatively, it MAY use a registry client API such as the Java API for XML Registries [JAXR] to access the registry. Client APIs such as [JAXR] provide programming convenience and are typically specific to a programming language.

513

1.7.2

514

The ebXML Registry consists of the following service interfaces:

515 516 517

•

A LifecycleManager interface that provides a collection of operations for end-to-end lifecycle management of metadata and content within the registry. This includes publishing, update, approval and deletion of metadata and content.

518 519

•

A QueryManager interface that provides a collection of operations for the discovery and retrieval of metadata and content within the registry.

520 521

[RS-Interface-WSDL] provides an abstract (protocol neutral) definition of these Registry Service interfaces in WSDL format.

522

1.7.3

523 524

This specification defines the following concrete protocol binding for the abstract service interfaces of the ebXML Registry:

Client API

Registry Service Interfaces

Service Interface: Protocol Bindings

May 2, 2005 Page 17 of 133

525 526 527

•

SOAP Binding that allows a Registry Client to access the registry using SOAP 1.1 with Attachments [SwA]. [RS-Bindings-WSDL] defines the binding of the abstract Registry Service interfaces to the SOAP protocol in WSDL format.

528 529

•

HTTP Binding that allows a Web Browser client to access the registry using HTTP 1.1 protocol.

530

Additional bindings may be defined in the future as needed by the community.

531

1.7.4

532 533 534 535

A Registry Client SHOULD be authenticated by the registry to determine the identity associated with them. Typically, this is the identity of the user associated with the Registry Client. Once the registry determines the identity it MUST perform authorization and access control checks before permitting the Registry Client's request to be processed.

536

1.7.5

537 538 539 540

An ebXML Registry is both a registry of metadata and a repository of content. A typical ebXML Registry implementation uses some form of persistent store such as a database to store its metadata and content. Architecturally, registry is distinct from the repository. However, all access to the registry as well as repository is through the operations defined by the Registry Service interfaces.

Authentication and Authorization

Metadata Registry and Content Repository

May 2, 2005 Page 18 of 133

541

Registry Protocols

542 543

This chapter introduces the registry protocols supported by the registry service interfaces. Specifically it introduces the generic message exchange patterns that are common to all registry protocols.

544

2.1

545 546 547 548

Specific registry request and response messages derive from common types defined in XML Schema in [RR-RS-XSD]. The Registry Client sends an element derived from RegistryRequestType to a registry, and the registry generates an element adhering to or deriving from RegistryResponseType, as shown next.

Requests and Responses

Figure 2: Registry Protocol Request-Response Pattern 550 551 552

Throughout this section, text mentions of elements and types are indicated with a namespace prefix. The namespace prefix conventions are defined in the “Introduction” chapter.

553 554 555 556 557 558

Each registry request is atomic and either succeeds or fails in entirety. In the event of success, the registry sends a RegistryResponse with a status of “Success” back to the client. In the event of failure, the registry sends a RegistryResponse with a status of “Failure” back to the client. In the event of an immediate response for an asynchronous request, the registry sends a RegistryResponse with a status of “Unavailable” back to the client. Failure occurs when one or more Error conditions are raised in the processing of the submitted objects. Warning messages do not result in failure of the request.

559

2.1.1

560

The RegistryRequestType type is used as a common base type for all registry request messages.

561

2.1.1.1

562 563 564 565 566 567 568

RegistryRequestType Syntax:

May 2, 2005 Page 19 of 133

<attribute name="comment" type="string" use="optional"/> </complexType> <element name="RegistryRequest" type="tns:RegistryRequestType"/>

569 570 571 572 573 574

2.1.1.2

Parameters: comment: This parameter allows the requestor to specify a string value that describes the action being performed by the request. This parameter is used by the “Registry Managed Version Control” feature of the registry.

575 576 577

id: This parameter specifies a request identifier that is used by the corresponding response to correlate the response with its request. It MAY also be used to correlate a request with another related request. The value of the id parameter MUST abide by the same constraints as the value of the id attribute for the <rim:IdentifiableType> type.

578 579 580 581

RequestSlotList: This parameter specifies a collection of Slot instances. A RegistryReuqestType MAY include Slots as an extensibility mechanism that provides a means of adding additional attributes to the request in form of Slots. The use of registry implementation specific slots MUST be ignored silently by a registry that does not support such Slots and MAY not be interoperable across registry implementations.

582 583 584 585 586 587 588

2.1.1.3

Returns:

589

All RegistryRequests return a response derived from the common RegistryResponseType base type.

590

2.1.1.4

591

The following exceptions are common to all registry protocol requests:

Exceptions: AuthorizationException: Indicates that the requestor attempted to perform an operation for which he or she was not authorized.

592 593

InvalidRequestException: Indicates that the requestor attempted to perform an operation that was semantically invalid.

594 595

SignatureValidationException: Indicates that a Signature specified for the request failed to validate.

596 597

TimeoutException: Indicates that the processing time for the request exceeded a registry specific limit.

598 599

UnsupportedCapabilityException: Indicates that this registry did not support the capability required to service the request.

600 601 602 603 604

In addition to above exceptions there are additional exceptions defined by [WSS-SMS] that a registry protocol request MUST return when certain errors occur during the processing of the <wsse:Security> SOAP Header element.

605

2.1.2

606 607 608

RegistryRequest is an element whose base type is RegistryRequestType. It adds no additional elements or attributes beyond those described in RegistryRequestType. The RegistryRequest element MAY be used by a registry to support implementation specific registry requests.

609

2.1.3

610

The RegistryResponseType type is used as a common base type for all registry responses.

RegistryRequest

RegistryResponseType

May 2, 2005 Page 20 of 133

611

2.1.3.1

612 613 614 615 616 617 618 619 620 621 622 623 624

625

Syntax:

2.1.3.2

Parameters:

627 628 629 630 631

status: The status attribute is used to indicate the status of the request. The value of the status attribute MUST be a reference to a ClassificationNode within the canonical ResponseStatusType ClassificationScheme as described in [ebRIM]. A Registry MUST support the status types as defined by the canonical ResponseStatusType ClassificationScheme. The canonical ResponseStatusType ClassificationScheme may be extended by adding additional ClassificationNodes to it.

632 633

The following canonical values are defined for the ResponseStatusType ClassificationScheme:

634

•

Success - This status specifies that the request was successful.

635 636 637

•

Failure - This status specifies that the request encountered a failure. One or more errors MUST be included in the RegistryErrorList in this case or returned as a SOAP Fault.

638 639 640

•

Unavailable – This status specifies that the response is not yet available. This may be the case if this RegistryResponseType represents an immediate response to an asynchronous request where the actual response is not yet available.

641

requestId: This parameter specifies the id of the request for which this is a response. It matches value of the id attribute of the corresponding RegistryRequestType.

626

642

ResponseSlotList: This parameter specifies a collection of Slot instances. A RegistryResponseType MAY include Slots as an extensibility mechanism that provides a means of adding dynamic attributes in form of Slots. The use of registry implementation specific slots MUST be ignored silently by a Registry Client that does not support such Slots and MAY not be interoperable across registry implementations.

643 644 645 646 647

RegistryErrorList: This parameter specifies an optional collection of RegistryError elements in the event that there are one or more errors that were encountered while the registry processed the request for this response. This is described in more detail in 6.9.4.

648 649 650 651 652

2.1.4

RegistryResponse

653 654 655

RegistryResponse is an element whose base type is RegistryResponseType. It adds no additional elements or attributes beyond those described in RegistryResponseType. RegistryResponse is used by many registry protocols as their response.

656

2.1.5

657

A RegistryErrorList specifies an optional collection of RegistryError elements in the event that there are

RegistryErrorList

May 2, 2005 Page 21 of 133

658

one or more errors that were encountered while the registry processed a request.

659

2.1.5.1

660 661 662 663 664 665 666 667 668 669 670 671

672

Syntax:

2.1.5.2

Parameters: highestSeverity: This parameter specifies the ErrorType for the highest severity RegistryError in the RegistryErrorList. Values for highestSeverity are defined by ErrorType in .

673 674 675

RegistryError: A RegistryErrorList has one or more RegistryErrors. A RegistryError specifies an error or warning message that is encountered while the registry processes a request. RegistryError is defined in 2.1.6.

676 677 678 679 680

2.1.6

681 682

A RegistryError specifies an error or warning message that is encountered while the registry processes a request.

683

2.1.6.1

684 685 686 687 688 689 690 691 692 693 694 695 696 697

698 699 700 701 702

RegistryError

Syntax:

2.1.6.2

Parameters: codeContext: This attribute specifies a string that indicates contextual text that provides additional detail to the errorCode. For example, if the errorCode is InvalidRequestException the codeContext MAY provide the reason why the request was invalid.

May 2, 2005 Page 22 of 133

703 704 705

errorCode: This attribute specifies a string that indicates the error that was encountered. Implementations MUST set this attribute to the Exception or Error as defined by this specification (e.g. InvalidRequestException).

707 708 709 710 711

severity: This attribute indicates the severity of error that was encountered. The value of the severity attribute MUST be a reference to a ClassificationNode within the canonical ErrorSeverityType ClassificationScheme as described in [ebRIM]. A Registry MUST support the error severity types as defined by the canonical ErrorSeverityType ClassificationScheme. The canonical ErrorSeverityType ClassificationScheme may be extended by adding additional ClassificationNodes to it.

712 713

The following canonical values are defined for the ErrorSeverityType ClassificationScheme:

714 715 716

•

Error – An Error is a fatal error encountered by the registry while processing a request. A registry MUST return a status of Failure in the RegistryResponse for a request that encountered Errors during its processing.

717 718 719 720

•

Warning – A Warning is a non-fatal error encountered by the registry while processing a request. A registry MUST return a status of Success in the RegistryResponse for a request that only encountered Warnings during its processing and encountered no Errors.

721

location: This attribute specifies a string that indicated where in the code the error occured. Implementations SHOULD show the stack trace and/or, code module and line number information where the error was encountered in code.

706

722 723

May 2, 2005 Page 23 of 133

724

SOAP Binding

725 726 727

This chapter defines the SOAP protocol binding for the ebXML Registry service interfaces. The SOAP binding enables access to the registry over the SOAP 1.1 with Attachments [SwA] protocol. The complete SOAP Binding is described by the following WSDL description files:

728

•

ebXML Registry Service Interfaces: Abstract Definition [RR-INT-WSDL]

729

•

ebXML Registry Service Interfaces: SOAP Binding [RR-SOAPB-WSDL]

730

•

ebXML Registry Service Interfaces: SOAP Service [RR-SOAPS-WSDL]

731

3.1

732 733

In [RR-INT-WSDL], each registry Service Interface is mapped to an abstract WSDL portType as follows:

734

•

ebXML Registry Service Interfaces: Abstract Definition

A portType is defined for each Service Interface:

735

736 737 738 739 740 741 742 743

•

744 745 746 747 748 749

Within each portType an operation is defined for each protcol supported by the service interafce: <portType name="QueryManagerPortType"> <operation name="submitAdhocQuery"> ... </operation> </portType>

750 751 752 753 754 755 756 757 758

•

Within each operation the the request and response message for the corresponding protocol are defined as input and output for the operation: <portType name="QueryManagerPortType"> <operation name="submitAdhocQuery"> <input message="tns:msgAdhocQueryRequest"/> <output message="tns:msgAdhocQueryResponse"/> </operation> </portType>

759 760 761 762

•

For each message used in an operation a message element is defined that references the element corresponding to the registry protocol request or response message from the XML Schema for the registry service interface [RR-LCM-XSD], [RR-QM-XSD]:

763 764 765 766 767 768 769 770 771

May 2, 2005 Page 24 of 133

772

3.2

ebXML Registry Service Interfaces SOAP Binding

773

In [RR-SOAPB-WSDL], a SOAP Binding is defined for the registry service interfaces as follows:

774 775

•

For each portType corresponding to a registry service interface and defined in [RR-INT-WSDL] a <binding> element is defined which has name <ServiceInterfaceName>Binding

776

•

The <binding> element references the portType defined in [RR-INT-WSDL] via its type attribute

777

•

The <soap:binding> extension element uses the “document” style

778 779

•

An operation element is defined for each protocol defined for the service interface. The operation name relates to the protocol request message.

780 781

•

The <soap:operation> extension element has <input> and <output> elements that have <soap:body> elements with use="literal".

782

783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800

3.3

801 802

In [RR-SOAPS-WSDL], a non-normative template is provided for a WSDL Service that uses the SOAP Binding from the registry service interfaces as follows:

803 804

•

A single service element defines the concrete ebXML Registry SOAP Service. The template uses the name “ebXMLRegistrySOAPService”.

805 806 807 808 809

•

The service element includes a port definitions, where each port corresponds with one of the service interfaces defined for the registry. Each port includes an HTTP URL for accessing that port specified by the location attribute of the <soap:address> element. The HTTP URL to the SOAP Service MUST conform to the pattern <base URL>/soap where <base URL> MUST be the same as the value of the home attribute of the instance of the Registry class defined by [ebRIM] that represents this registry.

810

•

Each port definition also references a SOAP binding element described in the previous section.

811 812 813 814 815 816 817 818 819 820 821

ebXML Registry Service Interfaces SOAP Service Template

822

May 2, 2005 Page 25 of 133

823

3.4

Mapping of Exception to SOAP Fault

824 825 826 827 828

The registry protocols defined in this specification include the specification of Exceptions that a registry MUST return when certain exceptional conditions are encountered during the processing of the protocol request message. A registry MUST return Exceptions specified in registry protocol messages as SOAP Faults as described in this section. In addition a registry MUST conform to [WSI-BP] when generating the SOAP Fault. A registry MUST NOT sign a SOAP Fault message it returns.

829

The following table provides details on how a registry MUST map exceptions to SOAP Faults.

830

SOAP Fault Element faultcode

faultstring

detail

faultactor

Description The faultCode MUST be present and MUST be the name of the Exception qualified by the URN prefix: urn:oasis:names:tc:ebxmlregrep:rs:exception: The faultstring MUST be present and SHOULD provide some information explaining the nature of the exception. At least one detail element MUST be present. The detail element SHOULD include the stack trace and/or, code module and line number information where the Exception was encountered in code. If the Exception has nested Exceptions within it then the registry SHOULD include the nested exceptions as nested detail elements within the top level detail element. At least one faultactor MUST be present. The first faultactor MUST be the base URL of the registry.

Example urn:oasis:names:tc:ebxmlregrep:rs:exception:ObjectNot FoundException Object with id urn:freebxml:registry:demoDB:Extrinsic Object:zeusDescription not found in registry.

http://example.server.com:8080/oma r/registry

Table 1: Mapping a Registry Exception to SOAP Fault

May 2, 2005 Page 26 of 133

831

HTTP Binding

832 833

This chapter defines the HTTP protocol binding for the ebXML Registry abstract service interfaces. The HTTP binding enables access to the registry over the HTTP 1.1 protocol.

834 835

The HTTP interface provides multiple options for accessing RegistryObjects and RepositoryItems via the HTTP protocol. These options are:

836 837 838

•

RPC Encoding URL: Allows client access to objects via a URL that is based on encoding a Remote Procedure Call (RPC) to a registry interface as an HTTP protocol request.

839

•

Submitter Defined URL: Allows client access to objects via Submitter defined URLs.

840 841

•

File Path Based URL: Allows clients access to objects via a URL based upon a file path derived from membership of object in a RegistryPackage membership hierarchy.

842 843

Each of the above methods has its advantages and disadvantages and each method may be better suited for different use cases as illustrated by table below:

844

HTTP Acceess Method RPC Encoding URL

• •

Submitter Defined URL

• • •

File Path Based URL

• •

Advantages The URL is constant and deterministic Submitter need not explicitly assign URL Very human-friendly URL Submitter may assign any URL The URL is constant and deterministic Submitter need not explicitly assign URL Intuitive URL that is based upon a familiar file / folder metaphor

•

• • • •

Disadvantages The URL is long and not human-friendly to remember Submitter must explicitly assign URL Requires additional resources in the registry The URL is NOT constant and deterministic Requires placing objects as members in RegistryPackages

Table 2: Comparison of HTTP Access Methods 845

4.1

HTTP Interface URL Pattern

846 847 848 849 850

The HTTP URLs used by the HTTP Binding MUST conform to the pattern <base URL>/http/<url suffix> where <base URL> MUST be the same as the value of the home attribute of the instance of the Registry class defined by [ebRIM] that represents this registry. The <url suffix> depends upon the HTTP Access Method and various request specific parameters that will be described later in this chapter.

851

4.2

852 853 854 855

The RPC Encoding URL method of the HTTP interface maps the operations defined by the abstract registry interfaces to the HTTP protocol using an RPC style. It defines how URL parameters are used to specify the interface, method and invocation parameters needed to invoke an operation on a registry interface such as the QueryManager interface.

856 857

The RPC Encoding URL method also defines how an HTTP response is used to carry the response generated by the operation specified in the request.

858

4.2.1

859

The following table specifies the URL parameters supported by RPC Encoding URLs. A Registry MAY

RPC Encoding URL

Standard URL Parameters

May 2, 2005 Page 27 of 133

860 861 862

implement additional URL parameters in addition to these parameters. Note that the URL Parameter names MUST be processed by the registry in a case-insensitive manner while the parameter values MUST be processed in a case-sensitive manner. URL Parameter Required Description Example interface

YES

Defines the service interface QueryManager that is the target of the request.

method

YES

Defines the method getRegistryObject (operation)within the interface that is the target of the request.

param-<key>

Defines named parameters to be passed into a method call. Note that some methods require specific parameters.

param-id= urn:freebxml:registry:demoD B:ExtrinsicObject:zeusDescri ption

Table 3: Standard URL Parameters 863

4.2.2

QueryManager Binding

864 865 866 867

A registry MUST support a RPC Encoded URL HTTP binding to QueryManager service interface. To specify the QueryManager interface as its target, the interface parameter of the URL MUST be “QueryManager.” In addition the following URL parameters are defined by the QueryManager HTTP Interface.

868

Method

Parameter

Return Value

HTTP Request Type

getRegistryObject

The RegistryObject that GET matches the specified id.

getRepositoryItem

The RepositoryItem that GET matches the specified id. Note that a RepositoryItem may be arbitrary content (e.g. a GIF image).

Table 4: RPC Encoded URL: Query Manager Methods 869 870 871

Note that in the examples that follow, name space declarations are omitted to conserve space. Also note that some lines may be wrapped due to lack of space.

872

4.2.2.1

873

The following example shows a getRegistryObject request.

Sample getRegistryObject Request

874 875 876 877

GET /http?interface=QueryManager&method=getRegistryObject&paramid= urn:freebxml:registry:demoDB:ExtrinsicObject:zeusDescription HTTP/1.1

878 879

4.2.2.2

Sample getRegistryObject Response

880 881

The following example shows an ExtrinsicObject, which is a concrete sub-class of RegistryObject being returned as a response to the getRegistryObject method invocation.

May 2, 2005 Page 28 of 133

HTTP/1.1 200 OK Content-Type: text/xml Content-Length: 555

883 884 885 886 887 888 889 890 891 892 893

<?xml version="1.0"?> <ExtrinsicObject id = "urn:freebxml:registry:demoDB:ExtrinsicObject:zeusDescription" objectType="${OBJECT_TYPE}"> ... </ExtrinsicObject>

894 895

4.2.2.3

Sample getRepositoryItem Request

896

The following example shows a getRepositoryItem request.

897

GET /http?interface=QueryManager&method=getRepositoryItem&paramid= urn:freebxml:registry:demoDB:ExtrinsicObject:zeusDescription HTTP/1.1

898 899 900 901 902

4.2.2.4

Sample getRepositoryItem Response

903 904

The following example assumes that the repository item was a Collaboration Protocol Profile as defined by [ebCPP]. It could return any type of content (e.g. a GIF image).

905

HTTP/1.1 200 OK Content-Type: text/xml Content-Length: 555

906 907 908 909 910 911 912 913

<?xml version="1.0"?> <CollaborationProtocolProfile> ... </CollaborationProtocolProfile>

914 915

4.2.3

LifeCycleManager HTTP Interface

916 917 918

The RPC Encoded URL mechanism of the HTTP Binding does not support the LifeCycleManager interface. The reason is that the LifeCycleManager operations require HTTP POST which is already supported by the SOAP binding.

919

4.3

920 921 922 923 924 925 926

A Submitter MAY specify zero or more Submitter defined URLs for a RegistryObject or RepositoryItem. These URLs MAY then be used by clients to access the object using the GET request of the HTTP protocol. Submitter defined URLs serve as an alternative to the RPC Encoding URL defined by the HTTP binding for the QueryManager interface. The benefit of Submitter defined URLs is that objects are made accessible via a URL that is meaningful and memorable to the user. The cost of Submitter defined URLs is that the Submitter needs to specify the Submitter defined URL and that the Submitter defined URL takes additional storage resources within the registry.

Submitter Defined URL

May 2, 2005 Page 29 of 133

927 928

Consider the examples below to see how Submitter defined URLs compare with the URL defined by the HTTP binding for the QueryManager interface.

929 930 931 932 933 934 935 936 937

Following is a sample URL defined by the HTTP binding for the QueryManager interface to access a RegistryObject that is an ExtrinsicObject describing a GIF image:

938 939 940

The same RegistryObject (an ExtrinsicObject) may be accessed via the following Submitter defined URL:

http://localhost:8080/ebxmlrr/registry/http/?interface=QueryManager&met hod=getRegistryObject&paramid=urn:freebxml:registry:demoDB:ExtrinsicObject:zeusDescription

941 942 943 944

http://localhost:8080/ebxmlrr/registry/http/pictures/nikola/zeus.xml

945 946 947 948 949 950 951 952 953

Following is a sample URL defined by the HTTP binding for the QueryManager interface to access a repository item that is a GIF image:

954 955

The same repository item may be accessed via the following Submitter defined URL:

http://localhost:8080/ebxmlrr/registry/http/?interface=QueryManager&met hod=getRepositoryItem&paramid=urn:freebxml:registry:demoDB:ExtrinsicObject:zeusDescription

956 957 958 959

http://localhost:8080/ebxmlrr/registry/http/pictures/nikola/zeus.jpg

960

4.3.1

Submitter defined URL Syntax

961 962 963

A Submitter MUST specify a Submitter defined URL as a URL suffix that is relative to the base URL of the registry. The URL suffix for a Submitter defined URL MUST be unique across all Submitter defined URLs defined for all objects within a registry.

964

The use of relative URLs is illustrated as follows:

965

•

Base URL for Registry: http://localhost:8080/ebxml/registry

966

•

Implied Prefix URL for HTTP interface: http://localhost:8080/ebxml/registry/http

967

•

Submitter Defined URL suffix: /pictures/nikola/zeus

968

•

Complete URL: http://localhost:8080/ebxmlrr/registry/http/pictures/nikola/zeus

969

4.3.2

Assigning URL to a RegistryObject

970

A Submitter MAY assign one or more Submitter defined URLs to a RegistryObject.

May 2, 2005 Page 30 of 133

971 972

The Submitter defined URL(s) MAY be assigned by the Submitter using a canonical slot on the RegistryObject. The Slot is identified by the name:

973 974 975 976

urn:oasis:names:tc:ebxml-regrep:rim:RegistryObject:locator

977 978 979 980

Each value in the collection of values for this Slot specifies a Submitter defined URL suffix for that RegistryObject. The registry MUST return the RegistryObject when the HTTP client sends an HTTP GET request whose URL matches any of the URLs specified within the locator Slot (if any) for that RegistryObject.

981

4.3.3

982

A Submitter MAY assign one or more Submitter defined URLs to a Repository Item.

983 984

The Submitter defined URL(s) may be assigned by the Submitter using a canonical slot on the ExtrinsicObject for the repository item. The Slot is identified by the name:

Assigning URL to a Repository Item

985 986 987 988

urn:oasis:names:tc:ebxml-regrep:rim:RegistryObject:contentLocator

989 990 991 992

Each value in the collection of values for this Slot specifies a Submitter defined URL suffix for the RepositoryItem associated with the ExtrinsicObject. The registry MUST return the RepositoryItem when the HTTP client sends an HTTP GET request whose URL matches any of the URLs specified within the contentLocator slot (if any) for the ExtrinsicObject for that RepositoryItem.

993

4.4

994 995 996

The File Path Based URL mechanism enables HTTP clients to access RegistryObjects and RepositoryItems using a URL that is derived from the RegistryPackage membership hierarchy for the RegistryObject or RepositoryItem.

997

4.4.1

998 999 1000 1001 1002

The RegistryPackage class as defined by [ebRIM] enables objects to be structurally organized by a RegistryPackage membership hierarchy. As such, a RegistryPackage serves a role similar to that of a Folder within the File and Folder metaphor that is common within filesystems in most operating systems. Similarly, the members of a RegistryPackage serve a role similar to the files within a folder in the File and Folder metaphor.

1003 1004 1005 1006

In this file-folder metaphor, a Submitter creates a RegistryPackage to create the functional equivalent of a folder and creates a RegistryObject to create the functional equivalent of a file. The Submitter adds a RegistryObjects as a member of a RegistryPackage to create the functional equivalent of adding a file to a folder.

1007

4.4.2

1008 1009 1010 1011 1012 1013 1014

Each RegistryObject has an implicit file path. The file path of a RegistryObject is a path structure similar to the Unix file path structure. The file path is composed of file path segments. Analogous to the Unix file path, the last segment within the file path represents the RegistryObject, while preceding segments represent the RegistryPackage(s) within the membership hierarchy of the RegistryObject. Each segment consists of the name of the RegistryPackage or the RegistryObject. Because the name attribute is of type InternationalString the path segment matches the name of an object within a specific locale.

File Path Based URL

File Folder Metaphor

File Path of a RegistryObject

May 2, 2005 Page 31 of 133

1015

4.4.2.1

File Path Example

1016 1017

Consider the example where a registry has a RegistryPackage hierarchy as illustrated below using the name of the objects in locale “en_US”:

1018

1019

Figure 3: Example Registry Package Hierarchy 1020 1021 1022

Now let us assume that the RegistryPackage named “2004” has an ExtrinsicObject named “baby.gif” for a repository item that is a photograph in the GIF format. In this example the file paths for various objects in locale “en_US” are shown in table below:

1023

Object Name

File Path /userData /userData/Sally /userData/Sally/pictures /userData/Sally/pictures/2004 /userData/Sally/pictures/2004/baby.gif

userData Sally pictures 2004 baby.gif

Table 5: File Path Examples 1024 1025

Note that above example assumes that the RegistryPackage named userData is a root level package (not contained within another RegistryPackage).

1026

4.4.3

1027 1028 1029

A registry client MAY access RegistryObjects and RepositoryItems over the HTTP GET request using URL patterns that are based upon the File Path for the target objects. This section describes how a registry resolves File Path URLs specified by an HTTP client.

1030 1031 1032 1033 1034 1035 1036

The registry MUST process each path segment from the beginning of the path to the end and for each path segment match the segment to the value attribute of a LocalizedString in the name attribute of a RegistryObject. For all but the last path segment, the matched RegistryObject MUST be a RegistryPackage. The last path segment MAY match any RegistryObject including a RegistryPackage. If any path segment fails to be matched then the URL is not resolvable by the File Path based URL method. When matching any segment other than the first segment the registry MUST also ensure that the matched RegistryObject is a member of the RegistryPackage that matches the previous segment.

1037

4.4.4

1038

When a File Path based URL matches a single object the there are two possible responses.

Matching URL To Objects

URL Matches a Single Object

1039 1040 1041 1042 1043 1044 1045

•

If the URL pattern does not end in a '/' character or the last segment does not match a RegistryPackage then the Registry MUST send as response an XML document that is the XML representation of the RegistryObject that matches the last segment. If the last segment matches an ExtrinsicObject then if the URL specifies the HTTP GET parameter with name 'getRepositoryItem' and value of 'true' then the registry MUST return as response the repository item associated with the ExtrinsicObject.

May 2, 2005 Page 32 of 133

1046

•

1047 1048 1049

If the URL pattern ends in a '/' character and the last segment matches a RegistryPackage then the Registry MUST send as response an HTML document that is the directory listing (section 4.4.6) of all RegistryObjects that are members of the RegistryPackage that matches the last segment.

1050 1051

4.4.5

URL Matches Multiple Object

1052

A registry MUST show a partial Directory Listing of a Registry Package when a File Path

1053

based URL matches multiple objects.

1054

A File Path based URL may match multiple objects if:

1055 1056 1057 1058 1059

•

Multiple objects with the same name exist in the same RegistryPackage

•

The segment contains wildcard characters such as '%' or '?' to match the names of multiple objects within the same RegistryPackage. Note that wildcard characters must be URL encoded as defined by the HTTP protocol. For example the '%' character is encoded as '%25'.

1060 1061

4.4.6

Directory Listing

1062 1063

A registry MUST return a directory listing as a response under certain circumstances as describes earlier. The directory listing MUST show a list of objects within a specific RegistryPackage.

1064 1065 1066 1067 1068

A registry SHOULD structure a directory listing such that each item in the listing provides information about a RegistryObject within the RegistryPackage. A registry MAY format its directory listing page in a registry specific manner. However, it is suggested that a registry SHOULD format it as an HTML page that minimally includes the objectType, name and description attributes for each RegistryObject in the directory listing.

1069 1070

Figure 4 shows a non-normative example of a directory listing that matches all root level objects that have a name that begins with ‘Sun’ (path /Sun%25).

1071

May 2, 2005 Page 33 of 133

1072

Figure 4: Example of a Directory Listing 1073

4.4.7

Access Control In RegistryPackage Hierarchy

1074 1075

The ability to control who can add files and sub-folders to a folder is important in a file system. The same is true for the File Path Based URL mechanism.

1076 1077 1078 1079

A Submitter MAY assign a custom Access Control Policy to a Registry Package to create the functional equivalent of assigning access control to a folder in the file-folder metaphor. The custom Access Control Policy SHOULD use the “reference” action to control who can add RegistryObjects as members of the folder as described in [ebRIM].

1080

4.5

1081 1082

Since the HTTP Binding supports multiple mechanisms to resolve an HTTP URL a registry SHOULD implement an algorithm to determine the correct HTTP Binding mechanism to resolve a URL.

1083 1084

This section gives a non-normative URL resolution algorithm that a registry SHOULD use to determine which of the various HTTP Binding mechanisms to use to resolve an HTTP URL.

1085 1086 1087 1088 1089 1090 1091

Upon receiving an HTTP GET request a registry SHOULD first check if the URL is an RPC Encoded URL. This MAY be done by checking if the interface URL parameter is specified in the URL. If specified the registry SHOULD resolve the URL using the RPC Encoded URL method as defined by section 4.2. If the interface URL parameter is not specified then the registry SHOULD use the Submitter specified URL method to check if the URL is resolvable. If the URL is still unresolvable then the registry SHOULD check if the URL is resolvable using the File Path based URL method. If the URL is still unresolvable then the registry should return an HTTP 404 (NotFound) error as defined by the HTTP protocol.

1092

4.6

1093 1094 1095

A registry MUST enforce all Access Control Policies including restriction on the READ action when processing a request to the HTTP binding of a service interface. This implies that a Registry MUST not resolve a URL to a RegistryObject or RepositoryItem if the client is not authorized to read that object.

URL Resolution Algorithm

Security Consideration

May 2, 2005 Page 34 of 133

1096 1097 1098 1099 1100 1101 1102 1103

4.7

Exception Handling

If a service interface method generates an Exception it MUST be reported in a RegistryErrorList, and sent back to the client within the HTTP response for the HTTP request. When errors occur, the HTTP status code and message SHOULD correspond to the error(s) being reported in the RegistryErrorList. For example, if the RegistryErrorList reports that an object wasn't found, therefore cannot be returned, an appropriate error code SHOULD be 404, with a message of "ObjectNotFoundException". A detailed list of HTTP status codes can be found in [RFC2616]. The mapping between registry exceptions and HTTP status codes is currently unspecified.

May 2, 2005 Page 35 of 133

1104

Lifecycle Management Protocols

1105 1106 1107

This section defines the protocols supported by Lifecycle Management service interface of the Registry. The Lifecycle Management protocols provide the functionality required by RegistryClients to manage the lifecycle of RegistryObjects and RepositoryItems within the registry.

1108

The XML schema for the Lifecycle Management protocols is described in [RR-LCM-XSD].

1109

5.1

1110 1111

This SubmitObjects allows a RegistryClient to submit one or more RegistryObjects and/or repository items.

Submit Objects Protocol

Figure 5: Submit Objects Protocol 1113 1114

5.1.1

1115 1116

The SubmitObjectsRequest is used by a client to submit RegistryObjects and/or repository items to the registry.

1117

5.1.1.1

1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128

SubmitObjectsRequest

Syntax:

May 2, 2005 Page 36 of 133

1129

5.1.1.2

Parameters: RegistryObjectList: This parameter specifies a collection of RegistryObject instances that are being submitted to the registry. The RegistryObjects in the list may be brand new objects being submitted to the registry or they may be current objects already existing in the registry. In case of existing objects the registry MUST treat them in the same manner as UpdateObjectsRequest and simply update the existing objects.

1130 1131 1132 1133 1134 1135

5.1.1.3

Returns:

1136

This request returns a RegistryResponse. See section 2.1.4for details.

1137

5.1.1.4

1138 1139

In addition to the exceptions common to all requests defined in 2.1.1.4, the following exceptions MAY be returned:

Exceptions:

UnresolvedReferenceException: Indicates that the requestor referenced an object within the request that was not resolved during the processing of the request.

1140 1141

UnsignedRepositoryItemException: Indicates that the requestor attempted to submit a RepositoryItem that was not signed.

1142 1143

QuotaExceededException: Indicates that the requestor attempted to submit more content than the quota allowed for them by the registry.

1144 1145 1146

5.1.2

Unique ID Generation

1147 1148 1149

As specified by [ebRIM], all RegistryObjects MUST have a unique id contained within the value of the id attribute. The id MUST be a valid URN and MUST be unique across all other RegistryObjects in the home registry for the RegistryObject.

1150 1151 1152 1153 1154 1155 1156

A Submitter MAY optionally supply the id attribute for submitted objects. If the Submitter supplies the id and it is a valid URN and does not conflict with the id of an existing RegistryObject within the home registry then the registry MUST honor the Submitter-supplied id value and use it as the value of the id attribute of the object in the registry. If the id is not a valid URN then the registry MUST return an InvalidRequestException. If the id conflicts with the id of an existing RegistryObject within the home registry then the registry MUST return InvalidRequestException for an UpdateObjectsRequest and treat it as an Update action for a SubmitObjectsRequest.

1157 1158 1159

If the client does not supply an id for a submitted object then the registry MUST generate a universally unique id. A registry generated id value MUST conform to the format of a URN that specifies a DCE 128 bit UUID as specified in [UUID]: (e.g. urn:uuid:a2345678-1234-1234-123456789012).

1160 1161

5.1.3

ID Attribute And Object References

1162 1163 1164 1165 1166 1167 1168 1169 1170

The id attribute of an object MAY be used by other objects to reference that object. Within a SubmitObjectsRequest, the id attribute MAY be used to refer to an object within the same SubmitObjectsRequest as well as to refer to an object within the registry. An object in the SubmitObjectsRequest that needs to be referred to within the request document MAY be assigned an id by the submitter so that it can be referenced within the request. The submitter MAY give the object a valid URN, in which case the id is permanently assigned to the object within the registry. Alternatively, the submitter MAY assign an arbitrary id that is not a valid URN as long as the id is a unique anyURI value within the request document. In this case the id serves as a linkage mechanism within the request document but MUST be replaced with a registry generated id upon submission.

1171 1172 1173 1174

When an object in a SubmitObjectsRequest needs to reference an object that is already in the registry, the request MAY contain an ObjectRef whose id attribute is the id of the object in the registry. This id is by definition a valid URN. An ObjectRef MAY be viewed as a proxy within the request for an object that is in the registry. regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 37 of 133

1175

5.1.4

Audit Trail

1176 1177

The registry MUST create a single AuditableEvent object with eventType Created for all the RegistryObjects created by a SubmitObjectsRequest.

1178

5.1.5

1179 1180 1181

The following example shows a simple SubmitObjectsRequest that submits a single Organization object to the registry. It does not show the complete SOAP Message with the message header and additional payloads in the message for the repository items.

Sample SubmitObjectsRequest

1182

<lcm:SubmitObjectsRequest> <rim:RegistryObjectList> <rim:Organization lid="${LOGICAL_ID}" id="${ID}" primaryContact="${CONTACT_USER_ID}"> <rim:Name> <rim:LocalizedString value="Sun Microsystems Inc." xml:lang="en-US"/> </rim:Name> <rim:Address city="Burlington" country="USA" postalCode="01867" stateOrProvince="MA" street="Network Dr." streetNumber="1"/> <rim:TelephoneNumber areaCode="781" countryCode="1" number="123456" phoneType="office"/> </rim:Organization> </rim:RegistryObjectList> </SubmitObjectsRequest>

1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199

5.2

The Update Objects Protocol

1200 1201

The UpdateObjectsRequest protocol allows a Registry Client to update one or more existing RegistryObjects and/or repository items in the registry.

Figure 6: Update Objects Protocol 1203

May 2, 2005 Page 38 of 133

1204

5.2.1

1205 1206

The UpdateObjectsRequest is used by a client to update RegistryObjects and/or repository items that already exist within the registry.

1207

5.2.1.1

Syntax: <element name="UpdateObjectsRequest"> <complexType> <complexContent> <extension base="rs:RegistryRequestType"> <sequence> <element ref="rim:RegistryObjectList"/> </sequence> </extension> </complexContent> </complexType> </element>

1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218

1219

UpdateObjectsRequest

5.2.1.2

Parameters: RegistryObjectList: This parameter specifies a collection of RegistryObject instances that are being updated within the registry. All immediate RegistryObject children of the RegistryObjectList MUST be current RegistryObjects already in the registry. RegistryObjects MUST include all required attributes, even those the user does not intend to change. A missing attribute MUST be interpreted as a request to set that attribute to NULL or in case it has a default value, the default value will be assumed. If this collection contains an immediate child RegistryObject that does not already exists in the registry, then the registry MUST return an InvalidRequestException. If the user wishes to submit a mix of new and updated objects then he or she SHOULD use a SubmitObjectsRequest. If an ExtrinsicObject is being updated and no RepositoryItem is provided in the UpdateObjectsRequest then the registry MUST maintain any previously existing RepositoryItem associated with the original ExtrinsicObject with the updated ExtrinsicObject. If the client wishes to remove the RepositoryItem from an existing ExtrinsicObject they MUST use a RemoveObjectsRequest with deletionScope=DeleteRepositoryItemOnly.

1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237

5.2.1.3

1238

This request returns a RegistryResponse. See section 2.1.4 for details.

1239

5.2.1.4

1240 1241

In addition to the exceptions common to all requests defined in 2.1.1.4, the following exceptions MAY be returned:

1242 1243 1244 1245 1246 1247

Returns: Exceptions:

UnresolvedReferenceException: Indicates that the requestor referenced an object within the request that was not resolved during the processing of the request. UnsignedRepositoryItemException: Indicates that the requestor attempted to submit a RepositoryItem that was not signed. QuotaExceededException: Indicates that the requestor attempted to submit more content than the quota allowed for them by the registry.

May 2, 2005 Page 39 of 133

1248

5.2.2

Audit Trail

1249 1250

The registry MUST create a single AuditableEvent object with eventType Updated for all RegistryObjects updated via an UpdateObjectsRequest.

1251

5.3

1252 1253

The Approve Objects protocol allows a client to approve one or more previously submitted RegistryObject objects using the LifeCycleManager service interface.

The Approve Objects Protocol

Figure 7: Approve Objects Protocol 1255

5.3.1

1256 1257

The ApproveObjectsRequest is used by a client to approve one or more existing RegistryObject instances in the registry.

1258

5.3.1.1

1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272

1273 1274 1275

ApproveObjectsRequest

Syntax: <element name="ApproveObjectsRequest"> <complexType> <complexContent> <extension base="rs:RegistryRequestType"> <sequence> <element ref="rim:AdhocQuery" minOccurs="0" maxOccurs="1"

/> <element ref="rim:ObjectRefList" minOccurs="0" maxOccurs="1" /> </sequence> </extension> </complexContent> </complexType> </element>

5.3.1.2

Parameters: AdhocQuery: This parameter specifies a query. A registry MUST approve all objects that match the specified query in addition to any other objects identified by other

May 2, 2005 Page 40 of 133

1276

parameters.

1277

ObjectRefList: This parameter specifies a collection of references to existing RegistryObject instances in the registry. A registry MUST approve all objects that are referenced by this parameter in addition to any other objects identified by other parameters.

1278 1279 1280 1281

5.3.1.3

1282

This request returns a RegistryResponse. See section 2.1.4 for details.

1283

5.3.1.4

1284 1285

In addition to the exceptions common to all requests defined in 2.1.1.4, the following exceptions MAY be returned:

1286

ObjectNotFoundException: Indicates that the requestor requested an object within the request that was not found.

1287

Returns: Exceptions:

1288 1289

5.3.2

Audit Trail

1290 1291

The registry MUST create a single AuditableEvent object with eventType Approved for all RegistryObject instance approved via an ApproveObjectsRequest.

1292

5.4

1293 1294 1295 1296

The Deprecate Object protocol allows a client to deprecate one or more previously submitted RegistryObject instances using the LifeCycleManager service interface. Once a RegistryObject is deprecated, no new references (e.g. new Associations, Classifications and ExternalLinks) to that object can be submitted. However, existing references to a deprecated object continue to function normally.

The Deprecate Objects Protocol

1297

Figure 8: Deprecate Objects Protocol 1298

5.4.1

DeprecateObjectsRequest

1299 1300

The DeprecateObjectsRequest is used by a client to deprecate one or more existing RegistryObject instances in the registry.

May 2, 2005 Page 41 of 133

1301

5.4.1.1

<element name="DeprecateObjectsRequest"> <complexType> <complexContent> <extension base="rs:RegistryRequestType"> <sequence> <element ref="rim:AdhocQuery" minOccurs="0" maxOccurs="1"

1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315

1316

Syntax:

/> <element ref="rim:ObjectRefList" minOccurs="0" maxOccurs="1" /> </sequence> </extension> </complexContent> </complexType> </element>

5.4.1.2

Parameters: AdhocQuery: This parameter specifies a query. A registry MUST deprecate all objects that match the specified query in addition to any other objects identified by other parameters.

1317 1318 1319

ObjectRefList: This parameter specifies a collection of references to existing RegistryObject instances in the registry. A registry MUST deprecate all objects that are referenced by this parameter in addition to any other objects identified by other parameters.

1320 1321 1322 1323 1324

5.4.1.3

Returns:

1325

This request returns a RegistryResponse. See section 2.1.4 for details.

1326

5.4.1.4

1327 1328

In addition to the exceptions common to all requests defined in 2.1.1.4, the following exceptions MAY be returned:

Exceptions:

UnresolvedReferenceException: Indicates that the requestor referenced an object within the request that was not resolved during the processing of the request.

1329 1330 1331

5.4.2

Audit Trail

1332 1333

The registry MUST create a single AuditableEvent object with eventType Deprecated for all RegistryObject deprecated via a DeprecateObjectsRequest.

1334

5.5

1335 1336 1337 1338

The Undeprecate Objects protocol of the LifeCycleManager service interface allows a client to undo the deprecation of one or more previously deprecated RegistryObject instances. When a RegistryObject is undeprecated, it goes back to the Submitted status and new references (e.g. new Associations, Classifications and ExternalLinks) to that object can now again be submitted.

The Undeprecate Objects Protocol

1339

May 2, 2005 Page 42 of 133

Figure 9: Undeprecate Objects Protocol 1340

5.5.1

1341 1342 1343

The UndeprecateObjectsRequest is used by a client to undeprecate one or more existing RegistryObject instances in the registry. The registry MUST silently ignore any attempts to undeprecate a RegistryObject that is not deprecated.

1344

5.5.1.1

1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359

1360 1361 1362 1363 1364 1365 1366 1367

UndeprecateObjectsRequest

Syntax: <element name="UndeprecateObjectsRequest"> <complexType> <complexContent> <extension base="rs:RegistryRequestType"> <sequence> <element ref="rim:AdhocQuery" minOccurs="0" maxOccurs="1"

/> <element ref="rim:ObjectRefList" minOccurs="0" maxOccurs="1" /> </sequence> </extension> </complexContent> </complexType> </element> </element>

5.5.1.2

Parameters: AdhocQuery: This parameter specifies a query. A registry MUST undeprecate all objects that match the specified query in addition to any other objects identified by other parameters. ObjectRefList: This parameter specifies a collection of references to existing RegistryObject instances in the registry. A registry MUST undeprecate all objects that are referenced by this parameter in addition to any other objects identified by other parameters.

May 2, 2005 Page 43 of 133

1368

5.5.1.3

Returns:

1369

This request returns a RegistryResponse. See section 2.1.4 for details.

1370

5.5.1.4

1371 1372

In addition to the exceptions common to all requests defined in 2.1.1.4, the following exceptions MAY be returned:

Exceptions:

UnresolvedReferenceException: Indicates that the requestor referenced an object within the request that was not resolved during the processing of the request.

1373 1374 1375

5.5.2

Audit Trail

1376 1377

The Registry Service MUST create a single AuditableEvent object with eventType Undeprecated for all RegistryObjects undeprecated via an UndeprecateObjectsRequest.

1378

5.6

1379 1380

The Remove Objects protocol allows a client to remove one or more RegistryObject instances and/or repository items using the LifeCycleManager service interface.

The Remove Objects Protocol

Figure 10: Remove Objects Protocol 1382

For details on the schema for the business documents shown in this process refer to .

1383

5.6.1

1384 1385

The RemoveObjectsRequest is used by a client to remove one or more existing RegistryObject and/or repository items from the registry.

1386

5.6.1.1

1387 1388 1389 1390 1391 1392 1393

RemoveObjectsRequest

Syntax: <element name="RemoveObjectsRequest"> <complexType> <complexContent> <extension base="rs:RegistryRequestType"> <sequence> <element ref="rim:AdhocQuery" minOccurs="0" maxOccurs="1"

May 2, 2005 Page 44 of 133

1394 1395 1396 1397 1398 1399 1400 1401 1402 1403

1404

5.6.1.2

Parameters:

1406 1407 1408 1409 1410 1411

deletionScope: This parameter indicates the scope of impact of the RemoveObjectsRequest. The value of the deletionScope attribute MUST be a reference to a ClassificationNode within the canonical DeletionScopeType ClassificationScheme as described in appendix A of [ebRIM]. A Registry MUST support the deletionScope types as defined by the canonical DeletionScopeType ClassificationScheme. The canonical DeletionScopeType ClassificationScheme may easily be extended by adding additional ClassificationNodes to it.

1412 1413

The following canonical ClassificationNodes are defined for the DeletionScopeType ClassificationScheme:

1405

1414 1415 1416 1417 1418

DeleteRepositoryItemOnly: This deletionScope specifies that the registry MUST delete the RepositoryItem for the specified ExtrinsicObjects but MUST NOT delete the specified ExtrinsicObjects. This is useful in keeping references to the ExtrinsicObjects valid. A registry MUST set the status of the ExtrinsicObject instance to Withdrawn in this case.

1419 1420 1421 1422 1423

DeleteAll: This deletionScope specifies that the request MUST delete both the RegistryObject and the RepositoryItem (if any) for the specified objects. A RegistryObject can be removed using a RemoveObjectsRequest with deletionScope DeleteAll only if all references (e.g. Associations, Classifications, ExternalLinks) to that RegistryObject have been removed. AdhocQuery: This parameter specifies a query. A registry MUST remove all objects that match the specified query in addition to any other objects identified by other parameters.

1424 1425 1426

ObjectRefList: This parameter specifies a collection of references to existing RegistryObject instances in the registry. A registry MUST remove all objects that are referenced by this parameter in addition to any other objects identified by other parameters.

1427 1428 1429 1430 1431

5.6.1.3

1432

This request returns a RegistryResponse. See section 2.1.4 for details.

1433

5.6.1.4

1434 1435

In addition to the exceptions common to all requests defined in 2.1.1.4, the following exceptions MAY be returned:

1436 1437 1438 1439 1440 1441

Returns: Exceptions:

UnresolvedReferenceException: Indicates that the requestor referenced an object within the request that was not resolved during the processing of the request. ReferencesExistException: Indicates that the requestor attempted to remove a RegistryObject while references to it still exist. Note that it is valid to remove a RegistryObject and all RegistryObjects that refer to it within the same request. In such cases the ReferencesExistException MUST not be thrown. regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 45 of 133

1442

5.7

Registry Managed Version Control

1443 1444 1445

This section describes the version control features of the ebXML Registry. This feature is based upon [DeltaV]. The ebXML Registry provides a simplified façade that provides a small subset of [DeltaV] functionality.

1446

5.7.1

1447 1448

All repository items in an ebXML Registry are implicitly version-controlled resources as defined by section 2.2.1 of [DeltaV]. No explicit action is required to make them a version-controlled resource.

1449 1450 1451

In addition RegistryObject instances are also implicitly version-controlled resources. However, a registry may limit version-controlled resources to a sub-set of RegistryObject classes based upon registry specific policies.

1452 1453

Minimally, a registry implementing the version control feature SHOULD make the following types as version-controlled resources:

Version Controlled Resources

1454

ClassificationNode

1455

ClassificationScheme

1456

Organization

1457

ExtrinsicObject

1458

RegistryPackage

1459

Service

1460 1461

The above list is chosen to exclude all composed types and include most of remaining RegistryObject types for which there are known use cases requiring versioning.

1462

5.7.2

1463 1464

Each version of a RegistryObject is a unique object and as such has its own unique value for its id attribute as defined by [ebRIM].

1465

5.7.3

Versioning and Object Identification

Logical ID

1467 1468

All versions of a RegistryObject are logically the same object and are referred to as the logical RegistryObject. A logical RegistryObject is a tree structure where nodes are specific versions of the RegistryObject.

1469

A specific version of a logical RegistryObject is referred to as a RegistryObject instance.

1470 1471

A RegistryObject instance MUST have a Logical ID (LID) to identify its membership in a particular logical RegistryObject. Note that this is in contrast with the id attribute that MUST be unique for each version of the same logical RegistryObject. A client may refer to the logical RegistryObject in a version independent manner using its LID.

1466

1472 1473 1475 1476 1477 1478

A RegistryObject is assigned a LID using the lid attribute of the RegistryObject class. If the submitter assigns the lid attribute, she must guarantee that it is a globally unique URN. A registry MUST honor a valid submitter-supplied LID. If the submitter does not specify a LID then the registry MUST assign a LID and the value of the LID attribute MUST be identical to the value of the id attribute of the first (originally created) version of the logical RegistryObject.

1479

5.7.4

1480 1481 1482

An ebXML Registry supports independent versioning of both RegistryObject metadata as well as repository item content. It is therefore necessary to keep distinct version information for a RegistryObject instance and its repository item if it happens to be an ExtrinsicObject instance.

1474

Version Identification

May 2, 2005 Page 46 of 133

1483

5.7.4.1

Version Identification for a RegistryObject

1484 1485 1486 1487

A RegistryObject MUST have a versionInfo attribute whose type is the VersionInfo class defined by ebRIM. The versionInfo attributes identifies the version information for that RegistryObject instance. A registry MUST not allow two versions of the same RegistryObject to have the same versionInfo.versionName attribute value.

1488

5.7.4.2

1489 1490

When a RegistryObject is an ExtrinsicObject with an associated repository item, the version identification for the repository item is distinct from the version identification for the ExtrinsicObject.

1491 1492 1493

An ExtrinsicObject that has an associated repository item MUST have a contentVersionInfo attribute whose type is the VersionInfo class defined by ebRIM. The contentVersionInfo attributes identifies the version information for that repository item instance.

1494 1495

An ExtrinsicObject that does not have an associated repository item MUST NOT have a contentVersionInfo attribute defined.

1496 1497 1498

A registry MUST allow two versions of the same ExtrinsicObject to have the same contentVersionInfo.versionName attribute value because multiple ExtrinsicObject versions MAY share the same RepositoryItem version.

1499

5.7.5

1500 1501

An ExtrinsicObject and its associated repository item may be updated independently and therefore versioned independently.

1502 1503

A registry MUST maintain separate version trees for an ExtrinsicObject and its associated repository item as described earlier.

1504 1505 1506 1507 1508

Table 6 shows all the combinations for versioning an ExtrinsicObject and its repository item. After eliminating invalid or impossible combinations as well as those combinations where no action is needed, the only combinations that require versioning are showed in gray background rows. Of these there are only two unique cases (referred to as case A and B). Note that it is not possible to version a repository item without versioning its ExtrinsicObject.

Version Identification for a RepositoryItem

Versioning of ExtrinsicObject and Repository Items

1509

ExtrinsicObject Exists No No Yes

RepositoryItem Exists No Yes No

ExtrinsicObject Updated

RepositoryItem Updated

Comment Do nothing Not possible

No No Yes

No Yes No

Yes

Do nothing Not possible Version ExtrinsicObject (case A) Not possible

May 2, 2005 Page 47 of 133

Yes

No No Yes

No Yes No

Yes

Do nothing Not possible Version ExtrinsicObject (case A) Version ExtrinsicObject and RepositoryItem (case B)

Table 6: Versioning of ExtrinsicObject and Repository Item 1510 1511

5.7.5.1

1512 1513 1514 1515

Because an ExtrinsicObject and its repository item are versioned independently (case B) it is possible for multiple versions of the ExtrinsicObject to share the same version of the repository item. In such cases the contentVersionInfo attributes MUST be the same across multiple version of the ExtrinsicObject.

1516

5.7.6

1517 1518 1519 1520 1521

When a registry creates a new version of a RegistryObject it MUST create copies of all composed1 objects as new objects that are composed within the new version. This is because each version is a unique object and composed objects by definition are not shareable across multiple objects. Specifically, each new copy of a composed object MUST have a new id since it is a different object than the original composed object in the previous version.

1522

A registry MUST not version composed objects.

1523

5.7.7

1524 1525 1526 1527 1528 1529

An object reference from a RegistryObject references a specific version of the referenced RegistryObject. When a registry creates a new version of a referenced RegistryObject it MUST NOT move refrences from other objects from the previous version to the new version of the referenced object. Clients that wish to always reference the latest versions of an object MAY use the Event Notification feature to update references when new versions are created and thus always reference the latest version.

1530 1531 1532 1533 1534

A special case is when a SubmitObjectsRequest or an UpdateObjectRequest contains an object that is being versioned by the registry and the request contains other objects that reference the object being versioned. In such case, the registry MUST update all references within the submitted objects to the object being versioned such that those objects now reference the new version of the object being created by the request.

1535

5.7.8

1536 1537 1538 1539

The canonical EventType ClassificationScheme used by the Audit Trail feature defines an Updated event type and then defines a Versioned event type as a child of the Updated event type ClassificationNode. The semantic are that a Versioned event type is specialization of the Updated event type.

1540

A registry MUST use the Updated event type in the AuditableEvent when it updates a RegistryObject 1

ExtrinsicObject and Shared RepositoryItem

Versioning and Composed Objects

Versioning and References

Versioning and Audit Trail

Composed object types are identified in figure 1 in [ebRIM] figure 1 as classes with composition or “solid diamond” relationship with RegistryObject type.

May 2, 2005 Page 48 of 133

1541

without creating a new version.

1542 1543

A registry MUST use the Versioned event type in the AuditableEvent when it creates a new version of a logical RegistryObject.

1544 1545

A registry MUST NOT use the Created event type in the AuditableEvent when it creates a new version of a logical RegistryObject.

1546

5.7.9

1547 1548 1549 1550

Within any single branch within the version tree for an object any given version implicitly supersedes the version immediately prior to it. Sometimes it may be necessary to explicitly indicate which version supersedes another version for the same object. This is especially true when two versions are siblings branch roots of the version tree for the same object.

1551 1552 1553

A client MAY specify an Association between any two versions of an object within the objects version tree using the canonical associationType “Supersedes” to indicate that the sourceObject supersedes the target targetObject within the Association.

1554 1555 1556 1557

A client MUST NOT specify an Association between two version of an object using the canonical associationType “Supersedes” if the sourceObject is an earlier version within the same branch in the version tree than the targetObject as this violates the implicit “Supersedes” association between the two version.

1558 1559

Note that this section is functionally equivalent to the predecessor-set successor-set elements of the Version Properties as defined by [DeltaV].

1560

5.7.10

1561 1562 1563 1564

An ebXML Registry MAY allow clients to remove specified versions of a RegistryObject. A client MAY delete older version of an object using the RemoveObjectsRequest by specifying the version by its unique id. Removing an ExtrinsicObject instance MUST remove its repository item if no other version references that repository item.

1565

5.7.11

1566 1567

The registry MAY prune older versions based upon registry specific administrative policies in order to manage storage resources.

1568

5.7.12

1569 1570 1571

This specification does not define a workspace feature with explicit checkin and checkout capabilities as defined by [DeltaV]. An ebXML Registry MAY support such features in an implementation specific manner.

1572 1573 1574 1575

This specification does not prescribe a locking or branching model. An implementation may choose to support an optimistic (non-locking) model. Alternatively or in addition, an implementation may support a locking model that supports explicit checkout and checkin capability. A future technical note or specification may address some of these capabilities.

1576

5.7.13

1577 1578 1579 1580

The registry manages creation of new version of a RegistryObject or a repository item automatically. A registry that supports versioning MUST implicitly create a new version for a repository item if the repository item is updated via a SubmitObjectsRequest or UpdateObjectsRequest. In such cases it MUST also create a new version of its ExtrinsicObject.

1581 1582 1583

If the client only wishes to update and version the ExtrisnicObject it may do so using an UpdateObjectsRequest without providing a repository item. In such cases the registry MUST assign the repository item version associated with the previous version of the ExtrinsicObject.

Inter-versions Association

Client Initiated Version Removal

Registry Initiated Version Removal

Locking and Concurrent Modifications

Version Creation

May 2, 2005 Page 49 of 133

1584

5.7.14

Versioning Override

1585 1586 1587 1588

A client MAY specify a dontVersion hint on a per RegistryObject basis when doing a submit or update of a RegistryObject. A registry SHOULD not create a new version for that RegistryObject when the dontVersion hint has value of “true”. The dontVersion hint MAY be specified as a canonical Slot with the following name:

1589 1590

urn:oasis:names:tc:ebxml-regrep:rim:RegistryObject:dontVersion

1592

The value of the dontVersion Slot, if specified, MUST be either “true” or “false”.

1593 1594 1595 1596

A client MAY specify a dontVersionContent hint on a per ExtrinsicObject basis when doing a submit or update of an ExtrinsicObject with a repository item. A registry SHOULD not create a new version for that repository item when the dontVersionContent hint has value of “true”. The dontVersionContent hint MAY be specified as a canonical Slot with the following name:

1597 1598

urn:oasis:names:tc:ebxml-regrep:rim:RegistryObject:dontVersionContent

1600

The value of the dontVersionContent Slot, if specified, MUST be either “true” or “false”.

1601 1602 1603 1604 1605

A client MAY also specify the dontVersion and dontVersionContent Slots on the RegistryRequest using the <rs:RequstSlotList> element. A registry MUST treat these Slots when specified on the request as equivalent to being specified on every RegistryObject within the request. The value of these Slots as specified on the request take precedence over value of these Slots as specified on RegistryObjects within the request.

May 2, 2005 Page 50 of 133

1606

Query Management Protocols

1607 1608 1609

This section defines the protocols supported by QueryManager service interface of the Registry. The Query Management protocols provide the functionality required by RegistryClients to query the registry and discover RegistryObjects and RepositoryItems.

1610

The XML schema for the Query Management protocols is described in [RR-QUERY-XSD].

1611

6.1

1612 1613

The Ad hoc Query protocol of the QueryManager service interface allows a client to query the registry and retrieve RegistryObjects and/or RepositoryItems that match the specified query.

1614 1615 1616

A client submits an ad hoc query to the QueryManager by sending an AdhocQueryRequest. The AdhocQueryRequest contains a sub-element that specifies a query in one of the query syntaxes supported by the registry.

1617 1618 1619

The QueryManager sends an AdhocQueryResponse back to the client as response. The AdhocQueryResponse returns a collection of objects that match the query. The collection is potentially heterogeneous depending upon the query expression and request options.

Ad Hoc Query Protocol

Figure 11: Ad Hoc Query Protocol 1620

6.1.1

1621

The AdhocQueryRequest is used to submit a query to the registry.

1622

6.1.1.1

1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633

AdhocQueryRequest Syntax: <element name="AdhocQueryRequest"> <complexType> <complexContent> <extension base="rs:RegistryRequestType"> <sequence> <element maxOccurs="1" minOccurs="1" ref="tns:ResponseOption"/> <element ref="rim:AdhocQuery" /> </sequence> <attribute default="false" name="federated" type="boolean" use="optional"/>

May 2, 2005 Page 51 of 133

1634 1635 1636 1637 1638 1639 1640

1641

6.1.1.2

Parameters: AdhocQuery: This parameter specifies the actual query. It is decsribed in detail in section 6.1.3.

1642 1643

federated: This optional parameter specifies that the registry must process this query as a federated query. By default its value is false. This value MUST be false when a registry routes a federated query to another registry in order to avoid an infinite loop in federated query processing.

1644 1645 1646 1647

federation: This optional parameter specifies the id of the target Federation for a federated query in case the registry is a member of multiple federations. In the absence of this parameter a registry must route the federated query to all federations of which it is a member. This value MUST be unspecified when a registry routes a federated query to another registry in order to avoid an infinite loop in federated query processing.

1648 1649 1650 1651 1652 1653

maxResults: This optional parameter specifies a limit on the maximum number of results the client wishes the query to return. If unspecified, the registry SHOULD return either all the results, or in case the result set size exceeds a registry specific limit, the registry SHOULD return a sub-set of results that are within the bounds of the registry specific limit. See section 6.2.1 for an illustrative example.

1654 1655 1656 1657 1658

ResponseOption: This required parameter allows the client to control the format and content of the AdhocQueryResponse generated by the registry in response to this request. See section 6.1.4 for details.

1659 1660 1661

startIndex: This optional integer value is used to indicate which result must be returned as the first result when iterating over a large result set. The default value is 0, which returns the result set starting with index 0 (first result). See section 6.2.1 for an illustrative example.

1662 1663 1664 1665 1666

6.1.1.3

1667

This request returns an AdhocQueryResponse. See section 6.1.2 for details.

1668

6.1.1.4

1669 1670

In addition to the exceptions common to all requests defined in 2.1.1.4, the following exceptions MAY be returned:

1671

InvalidQueryException: signifies that the query syntax or semantics was invalid. Client must fix the query syntax or semantic error and re-submit the query.

1672

Returns: Exceptions:

1673

6.1.2

1674

The AdhocQueryResponse is sent by the registry as a response to an AdhocQueryRequest.

1675

6.1.2.1

1676 1677

AdhocQueryResponse Syntax: <element name="AdhocQueryResponse"> <complexType>

May 2, 2005 Page 52 of 133

1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689

1690

6.1.2.2

Parameters: RegistryObjectList: This is the element that contains the RegistryObject instances that matched the specified query.

1691 1692

startIndex: This optional integer value is used to indicate the index for the first result in the result set returned by the query, within the complete result set matching the query. By default, this value is 0. See section 6.2.1 for an illustrative example.

1693 1694 1695

totalResultCount: This optional parameter specifies the size of the complete result set matching the query within the registry. When this value is unspecified, the client should assume it is the size of the result set contained within the result. See section 6.2.1 for an illustrative example.

1696 1697 1698 1699 1700

6.1.3

AdhocQuery

1701 1702

A client specifies a <rim:AdhocQuery> element within an AdhocQueryRequest to specify the actual query being submitted.

1703

6.1.3.1

Syntax: <complexType abstract="true" name="AdhocQueryType"> <complexContent> <extension base="tns:RegistryObjectType"> <sequence> <element ref="tns:QueryExpression" minOccurs="0" maxOccurs="1" /> </sequence> </extension> </complexContent> </complexType> <element name="AdhocQuery" type="tns:AdhocQueryType" substitutionGroup="tns:RegistryObject" />

1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717

6.1.3.2

Parameters: queryExpression: This element contains the actual query expression. The schema for queryExpression is extensible and can support any query syntax supported by the registry.

1718 1719 1720 1721

6.1.4

ReponseOption

1722 1723

A client specifies a ResponseOption structure within an AdhocQueryRequest to indicate the format of the results within the corresponding AdhocQueryResponse.

May 2, 2005 Page 53 of 133

1724 1725

6.1.4.1

Syntax:

1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742

6.1.4.2

Parameters: returnComposedObjects: This optional parameter specifies whether the RegistryObjects returned should include composed objects as defined by Figure 1 in [ebRIM]. The default is to return all composed objects.

1743 1744 1745

returnType: This optional enumeration parameter specifies the type of RegistryObject to return within the response. Values for returnType are as follows:

1746 1747 1748 1749 1750

•

ObjectRef - This option specifies that the AdhocQueryResponse MUST contain a collection of <rim:ObjectRef> elements. The purpose of this option is to return references to registry objects rather than the actual objects.

1751 1752

•

RegistryObject - This option specifies that the AdhocQueryResponse MUST contain a collection of <rim:RegistryObject> elements.

1753 1754 1755

•

LeafClass - This option specifies that the AdhocQueryResponse MUST contain a collection of elements that correspond to leaf classes as defined in [RR-RIM-XSD].

1756 1757 1758 1759

•

LeafClassWithRepositoryItem - This option is same as LeafClass option with the additional requirement that the response include the RepositoryItems, if any, for every <rim:ExtrinsicObject> element in the response.

1760 1761 1762

If “returnType” specified does not match a result returned by the query, then the registry must use the closest matching semantically valid returnType that matches the result.

1763 1764 1765

To illustrate, consider a case where OrganizationQuery is asked to return LeafClassWithRepositoryItem. As this is not possible, QueryManager will assume LeafClass option instead.

1766 1767

6.2

Iterative Query Support

1768 1769 1770 1771 1772

The AdhocQueryRequest and AdhocQueryResponse support the ability to iterate over a large result set matching a logical query by allowing multiple AdhocQueryRequest requests to be submitted such that each query requests a different subset of results within the result set. This feature enables the registry to handle queries that match a very large result set, in a scalable manner. The iterative query feature is accessed via the startIndex and maxResults parameters of the AdhocQueryRequest and the regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 54 of 133

1773

startIndex and totalResultCount parameters of the AdhocQueryResponse as described earlier.

1774 1775 1776 1777 1778

The iterative queries feature is not a true Cursor capability as found in databases. The registry is not required to maintain transactional consistency or state between iterations of a query. Thus it is possible for new objects to be added or existing objects to be removed from the complete result set in between iterations. As a consequence it is possible to have a result set element be skipped or duplicated between iterations.

1779 1780

Note that while it is not required, an implementations MAY implement a transactionally consistent iterative query feature.

1781

6.2.1

1782 1783 1784 1785

Consider the case where there are 1007 Organizations in a registry. The user wishes to submit a query that matches all 1007 Organizations. The user wishes to do the query iteratively such that Organizations are retrieved in chunks of 100. The following table illustrates the parameters of the AdhocQueryRequest and those of the AdhocQueryResponses for each iterative query in this example.

Query Iteration Example

1786

AdhocQueryRequest Parameters startIndex 0 100 200 300 400 500 600 700 800 900 1000

maxResults 100 100 100 100 100 100 100 100 100 100 100

AdhocQueryResponse Parameters startIndex 0 100 200 300 400 500 600 700 800 900 1000

totalResultCount 1007 1007 1007 1007 1007 1007 1007 1007 1007 1007 1007

# of Results 100 100 100 100 100 100 100 100 100 100 7

1787 1788

6.3

Stored Query Support

1789 1790 1791 1792 1793

The AdhocQuery protocol allow clients to submit queries that may be as general or as specific as the use case demands. As the queries get more specific they also get more complex. In these situations it is desirable to hide the complexity of the query from the client using parameterized queries stored in the registry. When using parameterized stored queries the client is only required to specify the identity of the query and the parameters for the query rather than the query expression itself.

1794 1795

Parameterized stored queries are useful to Registry Administrators because they provide a system wide mechanism for the users of the registry to share a set of commonly used queries.

1796 1797

Parameterized stored queries are useful to vertical standards because the standard can define domain specific parameterized queries and require that they be stored within the registry.

1798

An ebXML Registry MUST support parameterized stored queries as defined by this section.

1799

6.3.1

1800 1801

A stored query is submitted using the standard SubmitObjectsRequest protocol where the object submitted is an AdhocQueryType instance.

1802

6.3.1.1

1803 1804

When submitting a stored query, the submitter MAY declare zero or more parameters for that query. A parameter MUST be declared using a parameter name that begins with the ‘$’ character followed

Submitting a Stored Query

Declaring Query Parameters

May 2, 2005 Page 55 of 133

1805 1806

immediately by a letter and then followed by any combination of letters and numbers. The following BNF defines how a parameter name MUST be declared.

1807

QueryParameter := '$' [a-zA-Z] ( [a-zA-Z] | [0-9] )*

1808 1809 1810

A query parameter MAY be used as a placeholder for any part of the stored query.

1811

The following example illustrates how a parameterized stored query may be submitted:

1812

<SubmitObjectsRequest> <rim:RegistryObjectList> <rim:AdhocQuery id="${QUERY_ID}"> <rim:QueryExpression queryLanguage="${SQL_QUERY_LANG_ID}"> SELECT * from $tableName ro, Name_ nm, Description d WHERE objectType = ''$objectType'' AND (nm.parent = ro.id AND UPPER ( nm.value ) LIKE UPPER ( ''$name'' ) ) AND (d.parent = ro.id AND UPPER ( d.value ) LIKE UPPER ( ''$description'' ) ) AND (ro.id IN ( SELECT classifiedObject FROM Classification WHERE classificationNode IN ( SELECT id FROM ClassificationNode WHERE path LIKE ''$classificationPath1%'' ) )) </rim:QueryExpression> </rim:AdhocQuery> </rim:RegistryObjectList> </SubmitObjectsRequest>

1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831

Listing 1: Example of Stored Query Submission

1832 1833 1834 1835

The above query takes parameters $objectType, $name, $description and $classificationPath1 and find all objects for that match specified objectType, name, description and classification.

1836

6.3.1.2

1837 1838 1839 1840

A query MAY contain one or more context parameters as defined in this section. Context parameters are special query parameters whose value does not need to be supplied by the client. Instead the value for a context parameter is supplied by the registry based upon the context within which the client request is being processed.

1841 1842 1843

When processing a query, a registry MUST replace all context parameters present in the query with the context sensitive value for the parameter. A registry MUST ignore any context parameter values supplied by the client.

Canonical Context Parameters

1844

Context Parameter $currentUser $currentTime

Replacement Value Must be replaced with the id attribute of the user associated with the query. Must be replaced with the currentTime. The time format is same as the format defined for the timestamp attribute of AuditableEvent class.

1845 1846

6.3.2

Invoking a Stored Query

1847

A stored query is invoked using the AdhocQueryRequest with the following constraints:

1848

•

The <rim:AdhocQuery> element MUST not contain a <rim:queryExpression> element.

May 2, 2005 Page 56 of 133

1849 1850

•

The <rim:AdhocQuery> element's id attribute value MUST match the id attribute value of the stored query.

1851 1852

•

The <rim:AdhocQuery> element MAY have a Slot for each non-context parameter defined for the stored query being invoked. These Slots provide the value for the query parameters.

1853

6.3.2.1

1854 1855 1856 1857 1858

A stored query MAY be defined with zero or more parameters. A client may specify zero or more of the parameters defined for the stored query when submitting the AdhocQueryRequest for the stored query. It is important to note that the client MAY specify fewer parameters than those declared for the stored query. A registry MUST prune any predicates of the stored query that contain parameters that were not supplied by the client during invocation of the stored query.

1859 1860

In essence, the client may narrow or widen the specificity of the search by supplying more or less parameters.

1861 1862

A client specifies a query invocation parameter by using a Slot whose name matches the parameter name and whose value MUST be a single value that matches the specified value for the parameter.

1863 1864

A registry MUST ignore any parameters specified by the client for a stored query that do not match the parameters defined by the stored query.

1865

The following listing shows an example of how the stored query shown earlier is invoked. It shows:

1866

•

The stored query being identified by the value of the id attribute of the <rim:AdhocQuery> element.

1867

•

The value for the $name parameter being supplied

1868 1869

•

The value of other parameters defined by the query not being supplied. This indicates that the client does not wish to use those parameters as serach criterea.

Specifying Query Invocation Parameters

1870

1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882

<rim:AdhocQuery id="${STORED_QUERY_ID}"> <rim:Slot name="$name"> <rim:ValueList> <rim:Value>%ebXML%</rim:Value> </rim:ValueList> </rim:Slot> </rim:AdhocQuery> </AdhocQueryRequest>

Listing 2: Example of Stored Query Invocation 1883

6.3.3

Response to Stored Query Invocation

1884 1885

A registry MUST send a standard AdhocQueryResponse when a client invokes a stored query using an AdhocQueryRequest.

1886

6.3.4

1887 1888 1889 1890 1891 1892 1893

A stored query is a RegistryObject. Like all RegistryObjects, access to the stored query is governed by the Access Control Policy defined the stored query. By default a stored query is assigned the default Access Control Policy that allows any client to read and invoke that query and only the owner of the query and the Registry Administrator role to update or delete the query. The owner of the query may define a custom Access Control Policy for the query that restricts the visibility of the query, and ability to invoke it, to specific users, roles or groups. Thus the owner of the query or the Registry Administrator may control who gets to invoke which stored queries.

Access Control on a Stored Query

May 2, 2005 Page 57 of 133

1894

6.3.5

Canonical Query: Get Client’s User Object

1896

A registry MUST support a canonical stored query with id="urn:oasis:names:tc:ebxml-regrep:query:GetCallersUser".

1897 1898 1899

This query MUST return the User object associated with the client invoking the stored query. The client MUST not provide any parameters for this query. The stored query SHOULD use the canonical context parameter $currentUser.

1900 1901

The following is a non-normative example of a stored SQL query that MAY be used by a registry for this canonical stored query:

1895

1902 1903 1904 1905 1906 1907 1908 1909 1910

<rim:AdhocQuery id="urn:oasis:names:tc:ebxmlregrep:query:GetCallersUser"> <rim:QueryExpression queryLanguage="urn:oasis:names:tc:ebxml-regrep:QueryLanguage:SQL92"> SELECT u.* FROM User u WHERE u.id = $currentUser; </rim:QueryExpression> </rim:AdhocQuery>

1911

Note that a registry MAY use an equivalent stored filter query instead of a stored SQL query.

1912

6.4

1913 1914 1915 1916

An ebXML Registry MAY support SQL as a supported query syntax within the <rim:queryExpression> element of AdhocQueryRequest. This section normatively defines the SQL syntax that an ebXML Registry MAY support. Note that the support for SQL syntax within a registry does not imply a requirement that the registry must use a relational database in its implementation.

1917 1918

The registry SQL syntax is a proper subset of the “SELECT” statement of Intermediate level SQL as defined by ISO/IEC 9075:1992, Database Language SQL [SQL].

1919 1920

The terms below enclosed in angle brackets are defined in [SQL] or in [SQL/PSM]. The SQL query syntax conforms to the <query specification> with the following additional restrictions:

1921

1. A <derived column> MAY NOT have an <as clause>.

1922 1923

2. A <table expression> does not contain the optional <group by clause> and <having clause> clauses.

1924

3. A <table reference> can only consist of <table name> and <correlation name>.

1925 1926

4. A <table reference> does not have the optional AS between <table name> and <correlation name>.

1927 1928 1929

5. Restricted use of sub-queries is allowed by the syntax as follows. The <in predicate> allows for the right hand side of the <in predicate> to be limited to a restricted <query specification> as defined above.

1930 1931

As defined by [SQL], a registry MUST process table names and attribute names in a case insensitive manner.

1932

6.4.1

1933 1934

The normative Relational Schema definition that is the target of registry SQL queries can be found at the following location on the web:

1935

http://www.oasis-open.org/committees/regrep/documents/3.0/sql/database.sql

1936

6.4.2

1937 1938

The result of an SQL query resolves to a collection of objects within the registry. It never resolves to partial attributes. The objects related to the result set may be returned as an ObjectRef, RegistryObject

SQL Query Syntax

Relational Schema for SQL Queries

SQL Query Results

May 2, 2005 Page 58 of 133

1939 1940

or leaf class depending upon the returnType attribute of the responseOption parameter specified by the client on the AdHocQueryRequest. The entire result set is returned as an <rim:RegistryObjectList>.

1941

6.5

1942 1943 1944

This section normatively defines an XML syntax for querying an ebXML Registry called Filter Query syntax. An ebXML Registry MUST support the Filter Query syntax as a supported query syntax within the <rim:queryExpression> element of AdhocQueryRequest.

1945 1946

The Filter Query syntax is defined in [RR-QUERY-XSD] and is derived from a mapping from [ebRIM] to XML Schema following certain mapping patterns.

1947 1948 1949 1950

The Filter Query operational model views the network of RegistryObjects in the registry as a virtual XML document and a query traverses a specified part of the tree and prunes or filters objects from the virtual document using filter expressions and ultimately returns a collection of objects that are left after filtering out all objects that do not match the filters specified in the query.

1951 1952

Unlike SQL query syntax, the filter query syntax does not support joins across classes. This constrains the expressive capabilities of the query and may also be somehat less efficient in processing.

1953

6.5.1

1954 1955

The <rim:queryExpression> element of AdhocQueryRequest MUST contain a Query element derived from the <query:RegistryObjectQueryType> type.

1956 1957 1958

A Query element MAY contain a <query:PrimaryFilter> element and MAY contain additional Filter, Branch and Query elements within it as shown in the asbtract example below. The normative schema is defined by [RR-QUERY-XSD].

1959 1960 1961 1962 1963 1964 1965

Filter Query Syntax

Filter Query Structure

<${QueryElement}> <PrimaryFilter ... /> <${OtherFilterElement} ... /> <${BranchElement} .../> <${QueryElement} ... /> </${QueryElement}>

1966 1967

The role of Query, Filter and Branch elements will be defined next.

1968

6.5.2

1969 1970 1971

A Query element is the top level element in the Filter Query syntax to query the registry. The [RRQUERY-XSD] XML Schema defines a Query element for the RegistryObject class and all its descendant classes as defined by [ebRIM] using the following pattern:

1972 1973 1974

•

For each class in model descendant from RegistryObject class define a complexType with name <class>QueryType. For example there is an OrganizationQueryType complexType defined for the Organization class in [ebRIM].

1975 1976

•

The QueryType of a descendant of RegistryObject class MUST extend the QueryType for its super class. For example the OrganizationQueryType extends the RegistryObjectQueryType.

1977 1978 1979

•

For RegistryObject class and each of its descendants define an element with name <class>Query and with type <class>QueryType. For example the OrganizationQuery element is defined with type OrganizationQueryType.

1980

The class associated with a Query element is referred to as the Query domain class.

1981 1982

The following example shows the Query syntax where the Query domain class is the Organization class defined by [ebRIM]:

1983 1984 1985

Query Elements

May 2, 2005 Page 59 of 133

1986 1987 1988 1989 1990 1991

<extension base="tns:RegistryObjectQueryType"> ...Relevant Filters, Queries and Branches are defined here... </extension> </complexContent> </complexType> <element name="OrganizationQuery" type="tns:OrganizationQueryType"/>

1992 1993 1994

A Query element MAY have Filter, Branch or nested Query Elements. These are described in subsequent sections.

1995

6.5.3

1996 1997 1998 1999

A Query element MAY contain one or more Filter sub-elements. A Filter element is used to filter or select a subset of instances of a specific [ebRIM] class. The class that a Filter filters is referred to as the Filter domain class. A Filter element specifies a restricted predicate clause over the attributes of the Filter domain class.

2000 2001

[RR-QUERY-XSD] XML Schema defines zero or more Filter elements within a Query element definition using the following pattern:

2002 2003 2004 2005

•

PrimaryFilter: A Filter element is defined within the RegistryObjectQueryType with name PrimaryFilter. This Filter is used to filter the instances of the Query domain class based upon the value of its primitive attributes. The cardinality of the Filter element is zero or one. The PrimaryFilter element is inherited by all descendant QueryTypes of RegistryObjectQueryType.

2006 2007 2008 2009 2010

•

Additional Filters: Additional Filters in a Query element used to filter the instances of the Query domain class based upon whether the candidate domain class instance has a referenced object that satisfies the additional filter. Additional filter elements are defined for those attributes of the Query domain class that satisfy all of the following criterea:

Filter Elements

2011

•

The attribute's domain is not a primitive type (e.g. string, float, dateTime, int etc.).

2012

•

The attribute's domain class is not RegistryObject or its descendant.

2013 2014

•

The attribute's domain class does not have any reference attributes (use Branch or sub-Query if attribute's domain class has reference attributes). The attribute for which the Filter is defined is referred to as the Filter domain attribute. The domain class of the Filter domain attribute is the Filter domain class for such Filters. This type of Filter is used to filter the instances of the Query domain class based upon the attribute values within the Filter domain class.

2015 2016 2017 2018 2019

•

The name of the Filter element is <Filter Domain Attribute Name>Filter.

2020

•

The type of the Filter element is the FilterType complex type that is decsribed in 6.5.3.1.

2021 2022

•

The cardinality of the Filter element matches the cardinality of the Filter domain attribute in the Query domain class.

2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038

The following example shows the how [RR-QUERY-XSD] XML Schema uses the above pattern to define Filters for the OrganizationQueryType for the Organization class defined by [ebRIM]. <complexType name="OrganizationQueryType"> <complexContent> <extension base="tns:RegistryObjectQueryType"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="AddressFilter" type="tns:FilterType"/> <element maxOccurs="unbounded" minOccurs="0" name="TelephoneNumberFilter" type="tns:FilterType"/> <element maxOccurs="unbounded" minOccurs="0" name="EmailAddresseFilter" type="tns:FilterType"/> ...Branches and sub-Queries go here... </sequence> regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 60 of 133

2039 2040 2041

</extension> </complexContent> </complexType>

2042 2043 2044 2045

The following UML class diagram describing the Filter class structure as defined in [RR-QUERY-XSD] XML Schema. Note that the classes whose name ends in “Type” map to complexTypes and other Filter classes map to elements in the [RR-QUERY-XSD] XML Schema.

2046 2047

Figure 12: Filter Type Hierarchy

2048 2049 2050

6.5.3.1

FilterType

2051 2052

The FilterType is an abstract complexType that is the root type in the inheritence hierarchy for all Filter types.

2053

6.5.3.1.1

Parameters: negate: This parameter specifies that the boolean value that the Filter evaluates to MUST be negated to complete the evaluation of the filter. It is functionally equivalent to the NOT operator in SQL syntax.

2054 2055 2056 2057

6.5.3.2

SimpleFilterType

2058 2059

The SimpleFilter is the abstract base type for several concrete Filter types defined for primitive type such as boolean, float, integer and string.

May 2, 2005 Page 61 of 133

2060

6.5.3.2.1

Parameters: domainAttribute: This parameter specifies the attribute name of a primitive attribute within the Filter domain class. A registry MUST return an InvalidQueryException if this parameter's value does not match the name of primitive attribute within the Filter domain class. A registry MUST perform the attribute name match in a case insensitive manner.

2061 2062 2063 2064 2065

comparator: This parameter specifies the comparison operator for comparing the value of the attribute with the value supplied by the filter. The following comparators are defined:

2066 2067 2068 2069

•

LE: abbreviation for LessThanOrEqual

2070

•

LT: abbreviation for LessThan

2071

•

GE: abbreviation for GreaterThanOrEqual

2072

•

GT: abbreviation for GreaterThan

2073

•

EQ: abbreviation for Equal

2074

•

NE: abbreviation for NotEqual

2075

•

Like: Same as LIKE operator in SQL-92. MUST only be used in StringFilter.

2076 2077

•

NotLike: Same as NOT LIKE operator in SQL-92. MUST only be used in StringFilter.

2078 2079

6.5.3.3

BooleanFilter

2080 2081

The BooleanFilter MUST only be used for matching primitive attributes whose domain is of type boolean.

2082

6.5.3.3.1

Parameters: value: This parameter specifies the value that MUST be compared with the attribute value being tested by the Filter. It MUST be a boolean value.

2083 2084 2085 2086

The following example shows the use of a BooleanFilter to match the isInternal attribute of the ClassificationScheme class defined by [ebRIM]:

2087 2088

2089 2090

6.5.3.4

2091

The FloatFilter MUST only be used for matching primitive attributes whose domain is of type float.

2092

6.5.3.4.1

2093 2094 2095 2096 2097 2098

FloatFilter Parameters: value: This parameter specifies the value that MUST be compared with the attribute value being tested by the Filter. It MUST be a float value.

The following example shows the use of a FloatFilter to match fictitious amount float attribute since [ebRIM] currently has no float attributes defined: <FloatFilter domainAtribute="amount" comparator="GT" value="9.99"/>

2099

May 2, 2005 Page 62 of 133

2100

6.5.3.5

2101

The IntegerFilter MUST only be used for matching primitive attributes whose domain is of type integer.

2102

6.5.3.5.1

2104

2107 2108

Parameters: value: This parameter specifies the value that MUST be compared with the attribute value being tested by the Filter. It MUST be an integer value.

2103 2105 2106

IntegerFilter

The following example shows the use of a BooleanFilter to match a fictitious count integer attribute since [ebRIM] currently has no integer attributes defined: <IntegerFilter domainAtribute="amount" comparator="LT" value="100"/>

2109 2110

6.5.3.6

2111 2112

The DateTimeFilter MUST only be used for matching primitive attributes whose domain is of type datetime.

2113

6.5.3.6.1

2115

2119 2120 2121

Parameters: value: This parameter specifies the value that MUST be compared with the attribute value being tested by the Filter. It MUST be a datetime value.

2114 2116 2117 2118

DateTimeFilter

The following example shows the use of a DateTimeFilter to match a the timestamp attribute of the Auditable class defined by [ebRIM] where the timestamp value is greater than (later than) the specified datetime value: <DateTimeFilter domainAtribute="timestamp" comparator="GT" value="1997-07-16T19:20+01:00"/>

2122 2123

6.5.3.7

StringFilter

2124

The StringFilter MUST only be used for matching primitive attributes whose domain is of type string.

2125

6.5.3.7.1

Parameters:

2127

value: This parameter specifies the value that MUST be compared with the attribute value being tested by the Filter. It MUST be a string value.

2128 2129

The following example shows the use of a StringFilter to match a the firstName attribute of the Person class defined by [ebRIM] where the firstName value matches the pattern specified by the value:

2126

2130 2131 2132

2133 2134

6.5.3.8

CompoundFilter

2135 2136

The CompoundFilter MAY be used to specify a boolean conjunction (AND) or disjunction (OR) between two Filters. It allows a query to express a combination of predicate clauses within a Filter Query.

2137

6.5.3.8.1

Parameters:

2138

LeftFilter: This parameter specifies the first of two Filters for the CompoundFilter.

2139

May 2, 2005 Page 63 of 133

logicalOperator: This parameter specifies the logical operator. The value of this parameter MUST be “AND” or “OR”

2140 2141 2142 2143

The following example shows the use of a BooleanFilter to match the isInternal attribute of the ClassificationScheme class defined by [ebRIM]: <CompoundFilter logicalOperator="AND"> <LeftFilter domainAttribute="targetObject" comparator="EQ" value="${REGISTRY_OBJECT_ID}" type="StringFilter"/> <RightFilter domainAttribute="associationType" comparator="EQ" value="${HAS_MEMBER_ASSOC_TYPE_NODE_ID}" type="StringFilter"/> </CompoundFilter>

2144 2145 2146 2147 2148 2149 2150

6.5.4

Nested Query Elements

2151 2152 2153 2154

A Query element MAY contain one or more nested Query sub-elements. The purpose of the nested Query element is to allow traversal of the branches within the network of relationships defined by the information model and prune or filter those branches that do not meet the predicates specified in the corresponding Branch element.

2155 2156

The [RR-QUERY-XSD] XML Schema defines zero or more nested Query elements within a Query element definition using the following pattern:

2157 2158

•

A nested Query element is defined for each attribute of the Query domain class that satisfy all of the following criterea:

2159

•

The attribute's domain class is a descendant type of the RegistryObjectType.

2160 2161

•

The attribute's domain class contains reference attributes that link the domain class to some third class via the reference. The attribute for which the nested Query is defined is referred to as the Nested Query domain attribute. The domain class of the nested Query domain attribute is the Query domain class for the nested Query element.

2162 2163 2164 2165

•

The name of the nested Query element is <Nested Query Domain Attribute Name>Query.

2166 2167

•

The type of the nested Query element matches the QueryType for the domain class for the Query domain attribute.

2168 2169

•

The cardinality of the nested Query element matches the cardinality of the nested Query domain attribute in the Query domain class.

2170 2171 2172

The following example shows the how [RR-QUERY-XSD] XML Schema uses the above pattern to define nested Query elements for the OrganizationQueryType for the Organization class defined by [ebRIM].

2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188

<complexType name="OrganizationQueryType"> <complexContent> <extension base="tns:RegistryObjectQueryType"> <sequence> ...Filters and Branches go here ... <element maxOccurs="1" minOccurs="0" name="ParentQuery" type="tns:OrganizationQueryType"/> <element maxOccurs="unbounded" minOccurs="0" name="ChildOrganizationQuery" type="tns:OrganizationQueryType"/> <element maxOccurs="1" minOccurs="0" name="PrimaryContactQuery" type="tns:PersonQueryType"/> </sequence> </extension> </complexContent> </complexType>

2189

6.5.5

Branch Elements

2190 2191

A Query element MAY contain one or more Branch sub-elements. A Branch element is similar to the nested Query element as it too can have sub-elements that are Filter, Branch and subQuery elements. regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 64 of 133

2192 2193 2194 2195

However, it is different from Query elements because its type is not a descendant type of RegistryObjectQueryType. The purpose of the branch element is to allow traversal of the branches within the network of relationships defined by the information model and prune or filter those branches that do not meet the predicates specified in the corresponding Branch element.

2196 2197

The [RR-QUERY-XSD] XML Schema defines zero or more Branch elements within a Query element definition using the following pattern:

2198 2199

•

A Branch element is defined for each attribute of the Query domain class that satisfies all of the following criterea:

2200

•

The attribute's domain is not a primitive type (e.g. String, float, dateTime, int etc.).

2201 2202

•

The attribute's domain class contains reference attributes that link the domain class to some third class via the reference. The attribute for which the Branch is defined is referred to as the Branch domain attribute. The domain class of the Branch domain attribute is the Branch domain class for the Branch element.

2203 2204 2205

•

The name of the Branch element is <Branch Domain Attribute Name>Branch.

2206 2207

•

The cardinality of the Branch element matches the cardinality of the Branch domain attribute in the Query domain class.

2208 2209

The following example shows how the [RR-QUERY-XSD] XML Schema uses the above pattern to define Branches for the RegistryObjectQueryType for the RegistryObject class defined by [ebRIM].

2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225

<complexType name="RegistryObjectQueryType"> <complexContent> <extension base="tns:FilterQueryType"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="SlotBranch" type="tns:SlotBranchType"/> <element maxOccurs="1" minOccurs="0" name="NameBranch" type="tns:InternationalStringBranchType"/> <element maxOccurs="1" minOccurs="0" name="DescriptionBranch" type="tns:InternationalStringBranchType"/> ... Relevant Filters, queries go here... </sequence> </extension> </complexContent> </complexType>

2226 2227

6.6

Query Examples

2228 2229 2230

This section provides examples in both SQL and Filter Query syntax for some common query use cases. Each example gives the SQL syntax for the query followed by blank line followed by the equivalent Filter Query syntax for it.

2231

6.6.1

2232 2233

The following queries matches all RegistryObject instances whose name contains the word ‘Acme’ and whose description contains the word “bicycle”.

Name and Description Queries

2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244

SELECT ro.* from RegistryObject ro, Name nm, Description d WHERE nm.value LIKE '%Acme%' AND d.value LIKE '%bicycle%' AND (ro.id = nm.parent AND ro.id = d.parent); <RegistryObjectQuery> <NameBranch> <LocalizedStringFilter comparator="Like" domainAttribute="value" value="%Acme%" xsi:type="StringFilterType"/> </NameBranch> regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 65 of 133

2245 2246 2247 2248 2249 2250 2251 2252

6.6.2

Classification Queries

2253

This section describes various classification related queries.

2254

6.6.2.1

2255 2256

The following query retrieves the collection of all ClassificationSchemes. Note that the above query may also specify additional Filters, Querys and Branches as search criterea if desired.

Retrieving ClassificationSchemes

2257 2258 2259 2260

SELECT scheme.* FROM ClassificationScheme scheme; <ClassificationSchemeQuery/>

2261 2262

6.6.2.2

Retrieving Children of Specified ClassificationNode

2263 2264

The following query retrieves the children of a ClassificationNode given the “id” attribute of the parent ClassificationNode:

2265 2266 2267 2268 2269 2270 2271

SELECT cn.* FROM ClassificationNode cn WHERE parent = ${PARENT_ID}; <ClassificationNodeQuery> <PrimaryFilter comparator="Like" domainAttribute="parent" value="${PARENT_ID}" xsi:type="StringFilterType"/> </ClassificationNodeQuery>

2272 2273

6.6.2.3

Retrieving Objects Classified By a ClassificationNode

2274 2275 2276 2277

The following query retrieves the collection of ExtrinsicObjects that are classified by the Automotive Industry and the Japan Geography. Note that the query does not match ExtrinsicObjects classified by descendant ClassificationNodes of the Automotive Industry and the Japan Geography. That would require a slightly more complex query.

2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293

SELECT eo.* FROM ExtrinsicObject eo WHERE id IN (SELECT classifiedObject FROM Classification WHERE classificationNode IN (SELECT id FROM ClassificationNode WHERE path = ‘/${GEOGRAPHY_SCHEME_ID}/Asia/Japan’)) AND id IN (SELECT classifiedObject FROM Classification WHERE classificationNode IN (SELECT id FROM ClassificationNode WHERE path = ‘/${INDUSTRY_SCHEME_ID}/Automotive’)) <ExtrinsicObjectQuery> <ClassificationQuery> <ClassificationNodeQuery> <PrimaryFilter comparator="EQ" domainAttribute="path"

May 2, 2005 Page 66 of 133

value="/${GEOGRAPHY_SCHEME_ID}/Asia/Japan" xsi:type="StringFilterType"/> </ClassificationNodeQuery> </ClassificationQuery> <ClassificationQuery> <ClassificationNodeQuery> <PrimaryFilter comparator="EQ" domainAttribute="path" value="/${INDUSTRY_SCHEME_ID}/Automotive" xsi:type="StringFilterType"/> </ClassificationNodeQuery> </ClassificationQuery> </ExtrinsicObjectQuery>

2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307

6.6.2.4

Retrieving Classifications that Classify an Object

2308 2309

The following query retrieves the collection of Classifications that classify a object with id matching ${ID}:

2310

SELECT c.* FROM Classification c WHERE c.classifiedObject = ${ID};

2311 2312 2313 2314 2315 2316 2317

2318 2319

6.6.3

Association Queries

2320

This section describes various Association related queries.

2321

6.6.3.1

2322 2323

The following query retrieves the collection of Associations that have the object with id matching ${SOURCE_ID} as their source:

Retrieving All Associations With Specified Object As Source

2324 2325 2326 2327 2328 2329 2330

SELECT a.* FROM Association a WHERE sourceObject = ${SOURCE_ID} <AssociationQuery> <PrimaryFilter comparator="EQ" domainAttribute="sourceObject" value="${SOURCE_ID}" xsi:type="StringFilterType"/> </AssociationQuery>

2331 2332

6.6.3.2

Retrieving All Associations With Specified Object As Target

2333 2334

The following query retrieves the collection of Associations that have the object with id matching ${TARGET_ID} as their target:

2335 2336 2337 2338 2339 2340 2341

SELECT a.* FROM Association a WHERE targetObject = ${TARGET_ID} <AssociationQuery> <PrimaryFilter comparator="EQ" domainAttribute="targetObject" value="${TARGET_ID}" xsi:type="StringFilterType"/> </AssociationQuery>

2342

May 2, 2005 Page 67 of 133

2343

6.6.3.3

Retrieving Associated Objects Based On Association Type

2344 2345 2346 2347

Select Associations whose associationType attribute value matches the value specified by the ${ASSOC_TYPE_ID}. The ${ASSOC_TYPE_ID} value MUST reference a ClassificationNode that is a descendant of the canonical AssociationType ClassificationScheme.

2348

SELECT a.* FROM Association a WHERE associationType = ${ASSOC_TYPE_ID}

2349 2350 2351 2352 2353 2354 2355

2356 2357 2358

6.6.3.4

Complex Association Query

2359 2360 2361

The various forms of Association queries may be combined into complex predicates. The following query selects Associations that match specified specific sourceObject, targetObject and associationType:

2362

SELECT a.* FROM Association a WHERE sourceObject = ${SOURCE_ID} AND targetObject = ${TARGET_ID} AND associationType = ${ASSOC_TYPE_ID};

2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379

2380 2381

6.6.4

Package Queries

2382 2383

The following query retrieves all Packages that have as member the RegistryObject specified by ${REGISTRY_OBJECT_ID}:

2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395

SELECT p.* FROM Package p, Association a WHERE a.sourceObject = p.id AND a.targetObject = ${REGISTRY_OBJECT_ID} AND a.associationType = ${HAS_MEMBER_ASSOC_TYPE_NODE_ID}; <RegistryPackageQuery> <SourceAssociationQuery> <PrimaryFilter logicalOperator="AND" xsi:type="CompoundFilterType"> <LeftFilter comparator="EQ" domainAttribute="targetObject" value="${REGISTRY_OBJECT_ID}" xsi:type="StringFilterType"/> regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 68 of 133

2396 2397 2398 2399 2400 2401 2402 2403 2404

Note that the ${HAS_MEMBER_ASSOC_TYPE_NODE_ID} is a placeholder for the value of the id attribute of the canonical HasMember AssociationType ClassificationNode.

2405

6.6.5

2406 2407

The following query retrieves all ExternalLinks that serve as ExternalLink for the RegistryObject specified by ${REGISTRY_OBJECT_ID}:

ExternalLink Queries

2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425

SELECT el.* From ExternalLink el, Association a WHERE a.sourceObject = el.id AND a.targetObject = ${REGISTRY_OBJECT_ID} AND a.associationType = ${EXTERNALLY_LINKS_ASSOC_TYPE_NODE_ID}; <ExternalLinkQuery> <SourceAssociationQuery> <PrimaryFilter logicalOperator="AND" xsi:type="CompoundFilterType"> <LeftFilter comparator="EQ" domainAttribute="targetObject" value="${REGISTRY_OBJECT_ID}" xsi:type="StringFilterType"/> <RightFilter comparator="EQ" domainAttribute="associationType" value="${EXTERNALLY_LINKS_ASSOC_TYPE_NODE_ID}" xsi:type="StringFilterType"/> </PrimaryFilter> </SourceAssociationQuery> </ExternalLinkQuery>

2426 2427 2428

Note that the ${EXTERNALLY_LINKS_ASSOC_TYPE_NODE_ID} is a placeholder for the value of the id attribute of the canonical ExternallyLinks AssociationType ClassificationNode.

2429 2430

The following query retrieves all ExtrinsicObjects that are linked to an ExternalLink specified by ${EXTERNAL_LINK_ID}:

2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448

SELECT eo.* From ExtrinsicObject eo, Association a WHERE a.sourceObject = ${EXTERNAL_LINK_ID} AND a.targetObject = eo.id AND a.associationType = ${EXTERNALLY_LINKS_ASSOC_TYPE_NODE_ID}; <ExtrinsicObjectQuery> <TargetAssociationQuery> <PrimaryFilter logicalOperator="AND" xsi:type="CompoundFilterType"> <LeftFilter comparator="EQ" domainAttribute="sourceObject" value="${EXTERNAL_LINK_ID}" xsi:type="StringFilterType"/> <RightFilter comparator="EQ" domainAttribute="associationType" value="${EXTERNALLY_LINKS_ASSOC_TYPE_NODE_ID}" xsi:type="StringFilterType"/> </PrimaryFilter> </TargetAssociationQuery> </ExtrinsicObjectQuery>

2449

May 2, 2005 Page 69 of 133

2450

6.6.6

Audit Trail Queries

2451 2452

The following query retrieves all the AuditableEvents for the RegistryObject specified by ${REGISTRY_OBJECT_ID}:

2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463

SELECT ae.* FROM AuditableEvent ae, AffectedObject ao WHERE ao.eventId = ae.id AND ao.id = ${REGISTRY_OBJECT_ID} <AuditableEventQuery> <AffectedObjectQuery> <PrimaryFilter comparator="EQ" domainAttribute="id" value="${REGISTRY_OBJECT_ID}" xsi:type="StringFilterType"/> </AffectedObjectQuery> </AuditableEventQuery>

2464

May 2, 2005 Page 70 of 133

2465

Event Notification Protocols

2466

This chapter defines the Event Notification feature of the OASIS ebXML Registry.

2467 2468 2469 2470

Event Notification feature allows OASIS ebXML Registries to notify its users and / or other registries about events of interest. It allows users to stay informed about registry events without being forced to periodically poll the registry. It also allows a registry to propagate internal changes to other registries whose content might be affected by those changes.

2471 2472 2473 2474

ebXML registries support content-based Notification where interested parties express their interest in form of a query. This is different from subject–based (sometimes referred to as topic-based) notification, where information is categorized by subjects and interested parties express their interests in those predefined subjects.

2475

7.1

2476 2477

The following use cases illustrate different ways in which ebXML registries notify users or other registries.

2478

7.1.1

2479 2480

A user wishes to know when the CPP [ebCPP] of a partner is updated or superseded by another CPP. When that happens he may wish to create a CPA [ebCPP] based upon the new CPP.

2481

7.1.2

2482 2483 2484

A user wishes to know when a new plumbing service is offered in her town and be notified every 10 days. When that happens, she might try to learn more about that service and compare it with her current plumbing service provider’s offering.

2485

7.1.3

2486 2487 2488

User wishes to know whenever his CPP [ebCPP] is downloaded in order to evaluate on an ongoing basis the success of his recent advertising campaign. He might also want to analyze who the interested parties are.

2489

7.1.4

2490 2491

User wishes to know when the price of a product that she is interested in buying drops below a certain amount. If she buys it she would also like to be notified when the product has been shipped to her.

2492

7.1.5

2493 2494 2495 2496

In order to improve performance and availability of accessing some registry objects, a local registry MAY make replicas of certain objects that are hosted by another registry. The registry would like to be notified when the source object for a replica is updated so that it can synchronize the replica with the latest state of the source object.

2497

7.2

2498 2499 2500 2501 2502

Activities within a registry result in meaningful events. Typically, registry events are generated when a registry processes client requests. In addition, certain registry events may be caused by administrative actions performed by a registry operator. [ebRIM] defines the AuditableEvent class, instances of which represent registry events. When such an event occurs, an AuditableEvent instance is generated by the registry.

Use Cases

CPP Has Changed

New Service is Offered

Monitor Download of Content

Monitor Price Changes

Keep Replicas Consistent With Source Object

Registry Events

May 2, 2005 Page 71 of 133

2503

7.3

Subscribing to Events

2504 2505 2506 2507

A user MAY create a subscription with a registry if he or she wishes to receive notification for a specific type of event. A user creates a subscription by submitting a Subscription instance to a registry using the SubmitObjectsRequest. If a Subscription is submitted to a registry that does not support event notification then the registry MUST return an UnsupportedCapabilityException.

2508 2509 2510

The listing below shows a sample Subscription using a pre-defined SQL query as its selector that will result in an email notification to the user whenever a Service is created that is classified as a “Plumbing” service and located in “A Little Town.”

2511 2512

The SQL query within the selector in plain English says the following:

2513 2514 2515

Find all Services that are Created AND classified by ClassificationNode where ClassificationNode's Path ends with string "Plumbing", AND classified by ClassificationNode where ClassificationNode's Code contains string "A Little Town.”

2516

<rim:Subscription id="${SUBSCRIPTION_ID}" selector="${QUERY_ID}"> <!-The selector is a reference to a query object that has the following query defined SELECT * FROM Service s, AuditableEvent e, AffectectedObject ao, Classification c1, Classification c2 ClassificationNode cn1, ClassificationNode cn2 WHERE e.eventType = 'Created' AND ao.id = s.id AND ao.parent=e.id AND c1.classifiedObject = s.id AND c1.classificationNode = cn1.id AND cn1.path LIKE '%Plumbing' AND c2.classifiedObject = s.id AND c2.classificationNode = cn2.id AND cn2.path LIKE '%A Little Town%' -->  <rim:NotifyAction notificationOption="urn:oasis:names:tc:ebxmlregrep:NotificationOptionType:Objects" endPoint="mailto:[email protected]"/>  <rim:NotifyAction notificationOption="urn:oasis:names:tc:ebxmlregrep:NotificationOptionType:ObjectRefs" endPoint="urn:freebxml:registry:demoDB:serviceBinding:EpidemicAlertList enerServiceBinding"/> </rim:Subscription>

2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544

7.3.1

Event Selection

2545 2546 2547

In order to only be notified of specific events of interest, the user MUST specify a reference to a stored AdHocQuery object via the selector attribute within the Subscription instance. The query determines whether an event qualifies for that Subscription or not. For details on query syntax see chapter 6.

2548

7.3.2

2549 2550

When creating a Subscription, a user MAY also specify Actions within the subscription that specify what the registry must do when an event matching the Subscription (subscription event) transpires.

2551 2552

A user MAY omit specifying an Action within a Subscription if he does not wish to be notified by the registry. A user MAY periodically poll the registry and pull the pending Notifications.

2553

[ebRIM] defines two standard ways that a NotifyAction may be used:

Notification Action

May 2, 2005 Page 72 of 133

2554 2555

•

Email NotifyAction that allows delivery of event notifications via email to a human user or to an email end point for a software component or agent.

2556 2557

•

Service NotifyAction that allows delivery of event notifications via a programmatic interface by invoking a specified listener web service.

2558 2559 2560 2561 2562

If the registry supports event notification, at some time after the successful processing of each request, it MUST check all registered and active Subscriptions and see if any Subscriptions match the event. If a match is found then the registry performs the Notification Actions required for the Subscription. A registry MAY periodically perform such checks and corresponding notification actions in a batch mode based upon registry specific policies.

2563

7.3.3

2564 2565 2566 2567 2568 2569

A registry operator or content owner MAY use custom Access Control Policies to decide which users are authorized to create a subscription and to what events. A Registry MUST return an AuthorizationException in the event that an unauthorized user submits a Subscription to a registry. It is up to registry implementations whether to honour the existing subscription if an access control policy governing subscriptions becomes more restrictive after subscription have already been created based on the older policy.

2570

7.3.4

2571 2572 2573

A registry MAY use registry specific policies to decide an upper limit on the number of Subscriptions a user is allowed to create. A Registry MUST return a QuotaExceededException in the event that an authorized user submits more Subscriptions than allowed by their registry specific quota.

2574

7.3.5

2575 2576 2577 2578 2579

Each subscription defines a startTime and and endTime attribute which determines the period within which a Subscription is active. Outside the bounds of the active period, a Subsription MAY exist in an expired state within the registry. A registry MAY remove an expired Subscription at any time. In such cases the identity of a RegistryOperator user MUST be used for the request in order to have sufficient authorization to remove a user’s Subscription.

2580 2581

A Registry MUST NOT consider expired Subscriptions when delivering notifications for an event to its Subscriptions. An expired Subscription MAY be renewed by submitting a new Subscription.

2582

7.3.6

2583 2584 2585 2586

A Registry MAY reject a Subscription if it is too costly to support. For instance a Subscription that wishes to be notified of any change in any object may be too costly for most registries. A Registry MUST return a SubscriptionTooCostlyException in the event that an Authorized User submits a Subscription that is too costly for the registry to process.

2587

7.4

2588 2589 2590

A user MAY terminate a Subscription with a registry if he or she no longer wishes to be notified of events related to that Subscription. A user terminates a Subscription by deleting the corresponding Subscription object using the RemoveObjectsRequest to the registry.

2591

Removal of a Subscription object follows the same rules as removal of any other object.

2592

7.5

2593 2594 2595 2596 2597

A registry performs the Actions for a Subscription in order to actually deliver the events information to the subscriber. However, regardless of the specific delivery Action, the registry MUST communicate the Subscription events. The Subscription events are delivered within a Notification instance as described by [ebRIM]. In case of Service NotifyAction, the Notification is delivered to a handler service conformant to the RegistryClient interface. In case of an Email NotifyAction the notification is delivered

Subscription Authorization

Subscription Quotas

Subscription Expiration

Subscription Rejection

Unsubscribing from Events

Notification of Events

May 2, 2005 Page 73 of 133

2598

an email address.

2599

The listing below shows a sample Notification matching the subscription example in section 7.3:

2600

<rim:Notification subscription="${SUBSCRIPTION_ID}"> <rim:RegistryObjectList> <rim:Service id="f3373a7b-4958-4e55-8820-d03a191fb76a"> <rim:Name> <rim:LocalizedString value="A Little Town Plumbing"/> </rim:Name> <rim:Classification id="a3373a7b-4958-4e55-8820-d03a191fb76a" classifiedObject="f3373a7b-4958-4e55-8820-d03a191fb76a"/> <rim:Classification id="b3373a7b-4958-4e55-8820-d03a191fb76a" classifiedObject="f3373a7b-4958-4e55-8820-d03a191fb76a"/> </rim:Service> </rim:RegistryObjectList> </rim:Notification>

2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619

A Notification MAY contain actual RegistryObjects or ObjectRefs to RegistryObjects within the <rim:RegistryObjectList>. A client MAY specify the whether they wish to receive RegistryObjects or ObjectRefs to RegistryObjects using the notificationOption attribute of the Action within the Subscription. The registry MAY override this notificationOption based upon registry specific operational policies.

2620

7.6

2621 2622 2623 2624 2625 2626

The registry provides asynchronous PUSH style delivery of Notifications via notify Actions as described earlier. However, a client MAY also use a PULL style to retrieve any pending events for their Subscriptions. Pulling of events is done using the AdHocQuery protocol and querying the Notification class. A registry SHOULD buffer undelivered notifications for some period to allow clients to PULL those notifications. The period that a registry SHOULD buffer undelivered notifications MAY be defined using registry specific policies.

2627

7.7

2628 2629 2630 2631 2632

A registry MAY periodically prune AuditableEvents in order to manage its resources. It is up to the registry when such pruning occurs. It is up to the registry to determine when undelivered events are purged. A registry SHOULD perform such pruning by removing the older information in its Audit Trail content. However, it MUST not remove the original Create Event at the beginning of the audit trail since the Create Event establishes the owner of the RegistryObject.

Retrieval of Events

Pruning of Events

May 2, 2005 Page 74 of 133

2633

Content Management Services

2634 2635 2636 2637

This chapter describes the Content Management services of the ebXML Registry. Examples of Content Management Services include, but are not limited to, content validation and content cataloging. Content Management Services result in improved quality and integrity of registry content and metadata as well as improved ability for clients to discover that content and metadata.

2638 2639 2640 2641

The Content Management Services facility of the registry is based upon a pluggable architecture that allows clients to publish and discover new Content Management Services as Service objects that conform to a normative web service interface specified in this chapter. Clients MAY configure a Content Management Service that is specialized for managing a specific type of content.

2642

8.1

2643 2644

The Content Validation feature provides the ability to enforce domain specific validation rules upon submitted content and metadata in a content specific manner.

Content Validation

Invocation Control File Original Content

Content Validation Service

Content + Metadata 2645 2646



Success | Failure

Figure 13: Content Validation Service

2647 2648 2649 2650

A registry uses one or more Content Validation Services to automatically validate the RegistryObjects and repository items when they are submitted to the registry. A registry MUST reject a submission request in its entirety if it contains invalid data. In such cases a ValidationException MUST be returned to the client.

2651

Content Validation feature improves the quality of data in the registry.

2652

8.1.1

2653

The following use cases illustrate the Content Validation feature:

2654

8.1.1.1

2655 2656 2657

The Healthcare Standards organization HL7 uses content validation to enforce consistency rules and semantic checks whenever an HL7 member submits an HL7 Conformance Profile. HL7 is also planning to use the feature to improve the quality of other types of HL7 artifacts.

2658

8.1.1.2

2659 2660 2661

Content validation may be used to enforce consistency rules and semantic checks whenever a Business Process is submitted to the registry. This feature may be used by organizations such as UN/CEFACT, OAGi, and RosettaNet.

2662

8.1.1.3

2663 2664

Content validation may be used by the UBL technical committee to enforce consistency rules and semantic checks whenever a UBL business document is submitted to the registry.

Content Validation: Use Cases Validation of HL7 Conformance Profiles

Validation of Business Processes

Validation of UBL Business Documents

May 2, 2005 Page 75 of 133

2665

8.2

Content Cataloging

2666 2667

The Content Cataloging feature provides the ability to selectively convert submitted RegistryObject and repository items into metadata defined by [ebRIM], in a content specific manner.

Invocation Control File Original Content

Content Cataloging Service

Content + Metadata 2668 2669



Cataloged Content Content + Metadata

Figure 14: Content Cataloging Service

2670 2671 2672 2673 2674

A registry uses one or more Content Cataloging Services to automatically catalog RegistryObjects and repository items. Cataloging creates and/or updates RegistryObject metadata such as ExtrinsicObject or Classification instances. The cataloged metadata enables clients to discover the repository item based upon content from the repository item, using standard query capabilities of the registry. This is referred to as Content-based Discovery.

2675

The main benefit of the Content Cataloging feature is to enable Content-based Discovery.

2676

8.2.1

2677

There are many scenarios where content-based discovery is necessary.

2678

8.2.1.1

2679 2680

A company that sells a product using the RosettaNet PIP3A4 Purchase Order process wants to find CPPs for other companies where the Role element of the CPP is that of “Buyer”.

2681

8.2.1.2

2682 2683

A client may wish to discover all XML Schema documents in the registry that use an XML namespace containing the word “oasis”.

2684

8.2.1.3

2685 2686 2687

An ebXML registry client is attempting to discover all repository items that are WSDL descriptions that have a SOAP binding defined. Note that SOAP binding related information is content within the WSDL document and not metadata.

2688

8.3

2689 2690 2691 2692 2693

This section describes in abstract terms how the registry supports pluggable, user-defined Content Management Services. A Content Management Service is invoked in response to content being submitted to the registry via the standard Submit/UpdateObjectsRequest method. The Service invocation is on a per request basis where one request may result in many invocations, one for each RegistryObject for which a Content Management Service is configured within the registry.

2694

The registry may perform such invocation in one of two ways.

Content-based Discovery: Use Cases Find All CPPs Where Role is “Buyer”

Find All XML Schema’s That Use Specified Namespace

Find All WSDL Descriptions with a SOAP Binding

Abstract Content Management Service

2695

May 2, 2005 Page 76 of 133

2696 2697 2698

•

Inline Invocation Model: Content Management Service may be invoked inline with the processing of the Submit/UpdateObjectsRequest and prior to committing the content. This is referred to as Inline Invocation Model.

2699 2700 2701

•

Decoupled Invocation Model: Content Management Service may be invoked decoupled from the processing of the Submit/UpdateObjectsRequest and some time after committing the content. This is referred to as Decoupled Invocation Model.

2702 2703

8.3.1

Inline Invocation Model

2704 2705 2706 2707

In an inline invocation model a registry MUST invoke a Content Management Service inline with Submit/UpdateObjectsRequest processing and prior to committing the Submit/UpdateObjectsRequest. All metadata and content from the original Submit/UpdateObjectsRequest request or from the Content Management Service invocation MUST be committed as an atomic transaction.

2708 2709

Figure 15 shows an abstract Content Management Service and how it is used by an ebXML Registry using an inline invocation model. The steps are as follows:

2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728

1. A client submits a Content Management Service S1 to an ebXML Registry. The client typically belongs to an organization responsible for defining a specific type of content. For example the client may belong to RosettaNet.org and submit a Content Validation Service for validating RosettaNet PIPs. The client uses the standard Submit/UpdateObjectsRequest interface to submit the Service. This is a one-time step to configure this Content Management Service in the registry. 2. Once the Content Management Service has been submitted, a potentially different client may submit content to the registry that is of the same object type for which the Content Management Service has been submitted. The client uses the standard Submit/UpdateObjectsRequest interface to submit the content. 3. The registry determines there is a Content Management Service S1 configured for the object type for the content submitted. It invokes S1 using a ContentManagementServiceRequest and passes it the content. 4. The Content Management Service S1 processes the content and sends back a ContentManagementServiceResponse. 5. The registry then commits the content to the registry if there are no errors encountered. 6. The registry returns a RegistryResponse to the client for the Submit/UpdateObjectsRequest in step 2.

2729 2730 2731

May 2, 2005 Page 77 of 133

2732 2733



Figure 15: Content Management Service: Inline Invocation Model

2734

8.3.2

Decoupled Invocation Model

2735 2736 2737 2738

In a decoupled invocation model a registry MUST invoke a Content Management Service independent of or decoupled from the Submit/UpdateObjectsRequest processing. Any errors encountered during Content Management Service invocation MUST NOT have any impact on the original Submit/UpdateObjectsRequest processing.

2739 2740 2741

All metadata and content from the original Submit/UpdateObjectsRequest request MUST be committed as an atomic transaction that is decoupled from the metadata and content that may be generated by the Content Management Service invocation.

2742 2743

Figure 16 shows an abstract Content Management Service and how it is used by an ebXML Registry using a decoupled invocation model. The steps are as follows:

2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756

1. Same as in inline invocation model (Content Management Service is submitted). 2. Same as in inline invocation model (client submits content using Submit/UpdateObjectsRequest). 3. The registry processes the Submit/UpdateObjectsRequest and commits it to persistent store. 4. The registry returns a RegistryResponse to the client for the Submit/UpdateObjectsRequest in step 2. 5. The registry determines there is a Content Management Service S1 configured for the object type for the content submitted. It invokes S1 using a ContentManagementServiceRequest and passes it the content. 6. The Content Management Service S1 processes the content and sends back a ContentManagementServiceResponse.

May 2, 2005 Page 78 of 133

2757 2758 2759 2760 2761

7. If the ContentManagementServiceResponse includes any generated or modified content it is committed to the persistent store as separate transaction. If there are any errors encountered during decoupled invocation of a Content Management Service then these errors are logged by the registry in a registry specific manner and MUST NOT be reported back to the client.

2762

2763 2764



Figure 16: Content Management Service: Decoupled Invocation Model

2765

8.4

2766 2767 2768

This section describe the abstract Content Management Service protocol that is the base- protocol for other concrete protocols such as Validate Content protocol and Catalog Content protocol. The concrete protocols will be defined later in this document.

2769

8.4.1

2770 2771

The ContentManagementServiceRequestType MUST be the abstract base type for all requests sent from a registry to a Content Management Service.

2772

8.4.1.1

2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784

Content Management Service Protocol

ContentManagementServiceRequestType

Syntax:

<complexType name="ContentManagementServiceRequestType"> <complexContent> <extension base="rs:RegistryRequestType"> <sequence> <element name="OriginalContent" type="rim:RegistryObjectListType"/> <element name="InvocationControlFile" type="rim:ExtrinsicObjectType" maxOccurs="unbounded" minOccurs="0"/> </sequence> </extension> </complexContent> </complexType> regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 79 of 133

2785



2786

8.4.1.2

2787 2788

The following parameters are parameters that are either newly defined for this type or are inherited and have additional semantics beyond those defined in the base type description.

2789

InvocationControlFile: This parameter specifies the ExtrinsicObject for a repository item that the caller wishes to specify as the Invocation Control File. This specification does not specify the format of this file. There MUST be a corresponding repository item as an attachment to this request. The corresponding repository item SHOULD follow the same rules as attachments in Submit/UpdateObjectsRequest.

2790 2791 2792 2793

Parameters:

OriginalContent: This parameter specifies the RegistryObjects that will be processed by the content management service. In case of ExtrinsicObject instances within the OriginalContent there MAY be repository items present as attachments to the ContentManagementServiceRequest. This specification does not specify the format of such repository items. The repository items SHOULD follow the same rules as attachments in Submit/UpdateObjectsRequest.

2794 2795 2796 2797 2798 2799 2800 2801

8.4.1.3

Returns:

2802

This request returns a ContentManagementServiceResponse. See section 8.4.2 for details.

2803

8.4.1.4

2804 2805

In addition to the exceptions returned by base request types, the following exceptions MAY be returned:

Exceptions:

MissingRepositoryItemException: signifies that the caller did not provide a repository item as an attachment to this request when the Service requires it.

2806 2807

InvocationControlFileException: signifies that the InvocationControlFile(s) provided by the caller do not match the InvocationControlFile(s) expected by the Service.

2808 2809

UnsupportedContentException: signifies that this Service does not support the content provided by the caller.

2810 2811 2812 2813

8.4.2

ContentManagementServiceResponseType

2814 2815 2816 2817 2818

The ContentManagementServiceResponseType is sent by a Content Management Service as a response to a ContentManagementServiceRequestType. The ContentManagementServiceResponseType is the abstract base type for all responses sent to a registry from a Content Management Service. It extends the RegistryResponseType and does not define any new parameters.

2819 2820

8.4.2.1

2821 2822 2823 2824 2825 2826 2827 2828 2829

Syntax:

May 2, 2005 Page 80 of 133

2830

8.4.2.2

Parameters:

No new parameters are defined other than those inherited from RegistryResponseType.

2831 2832 2833

8.5

2834 2835

Any Submitter MAY submit an arbitrary Content Management Service to an ebXML Registry. The Content Management Service MUST be published using the standard LifeCycleManager interface.

2836

The Submitter MUST use the standard Submit/UpdateObjectsRequest to publish:

2837

A Service instance for the Content Management Service. In Figure 17 this is exemplified by the defaultXMLCatalogingService in the upper-left corner. The Service instance MUST have an Association with a ClassificationNode in the canonical ObjectType ClassificationScheme as defined by [ebRIM]. The Service MUST be the sourceObject while a ClassificationNode MUST be the targetObject. This association binds the Service to that specific ObjectType. The associationType for this Association instance MUST be “ContentManagementServiceFor.” The Service MUST be classified by the canonical ContentManagementService ClassificationScheme as defined by [ebRIM]. For example it may be classified as a “ContentValidationService” or a “ContentCatalogingService.”

The Service instance MAY be classified by a ClassificationNode under the canonical InvocationModel ClassificationScheme as defined by [ebRIM], to determine whether it uses the Inline Invocation model or the Decoupled Invocation model.

The Service instance MAY be classified by a ClassificationNode under the canonical ErrorHandlingModel ClassificationScheme as defined by [ebRIM], to determine whether the Service should fail on first error or simply log the error as a warning and continue. See section 8.6.4 for details.

A ServiceBinding instance contained within the Service instance that MUST provide the accessURI to the Cataloging Service.

An optional ExternalLink instance on the ServiceBinding that is resolvable to a web page describing:

2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855

Publishing / Configuration of a Content Management Service

2856 2857

The format of the supported content to be Cataloged

2858

The format of the supported Invocation Control File Note that no SpecificationLink is required since this specification [ebRS] is implicit for Content Cataloging Services.

2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869

One or more Invocation Control File(s) consisting of an ExtrinsicObject and a repository item pair. The ExtrinsicObject for the Invocation Control File MUST have a required Association with associationType value that references a descendant ClassificationNode of the canonical ClassificationNode “InvocationControlFileFor.” This is exemplified by the cppCatalogingServiceXSLT and the oagBODCatalogingServiceXSLT objects in Figure 17 (left side of picture). The Invocation Control File MUST be the sourceObject while a ClassificationNode in the canonical ObjectType ClassificationScheme MUST be the targetObject. o

May 2, 2005 Page 81 of 133

2870 2871



Figure 17: Cataloging Service Configuration

2872 2873 2874 2875

Figure 17 shows an example of the configuration of the Canonical XML Cataloging Service associated with the objectType for XML content. This Cataloging Service may be used with any XML content that has its objectType attribute hold a reference to the xmlObjectType ClassificationNode or one of its descendants.

2876 2877 2878

The figure also shows two different Invocation Control Files, cppCatalogingServiceXSLT and oagBODCatalogingServiceXSLT that may be used to catalog ebXML CPP and OAG Business Object Documents (BOD) respectively.

2880

8.5.1 Multiple Content Management Services and Invocation Control Files

2881 2882 2883 2884

This specification allows clients to submit multiple Content Management Services of the same type (e.g. validation, cataloging) and multiple Invocation Control Files for the same objectType. Content Management Services of the same type of service for the same ObjectType are referred to as peer Content Management Services.

2879

2885 2886 2887 2888 2889 2890 2891

When there are multiple Content Management Services and Invocation Control Files for the same ObjectType there MUST be an unambiguous association between a Content Management Service and its Invocation Control File(s). This MUST be defined by an Association instance with associationType value that references a ClassificationNode that is a descendant of the canonical ClassificationNode “InvocationControlFileFor” where the ExtrinsicObject for each Invocation Control File is the sourceObject and the Service is the targetObject. regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 82 of 133

2892 2893

The order of invocation of peer Content Management Services is undefined and MAY be determined in a registry specific manner.

2894

8.6

2895

This section describes how a registry invokes a Content Management Service.

2896

8.6.1

2897 2898 2899

When a registry receives a submission of a RegistryObject, it MUST use the following algorithm to determine or resolve the Content Management Services and Invocation Control Files to be used for dynamic content management for the RegistryObject:

Invocation of a Content Management Service Resolution Algorithm For Service and Invocation Control File

2900 2901

Get the objectType attribute of the RegistryObject.

2902 2903 2904 2905 2906

2. Query to see if the ClassificationNode referenced by the objectType is the targetObject of an Association with associationType of ContentManagementServiceFor. If the desired Association is not found for this ClassificationNode then repeat this step with its parent ClassificationNode. Repeat until the desired Association is found or until the parent is the ClassificationScheme. If desired Association(s) is found then repeat following steps for each such Association instance.

2907 2908 2909

2910 2911 2912 2913 2914

4. Query to see if the objectType ClassificationNode is the targetObject of one or more Associations whose associationType value references a ClassificationNode that is a descendant of the canonical ClassificationNode InvocationControlFileFor. If desired Association is not found for this ClassificationNode then repeat this step with its parent ClassificationNode. Repeat until the desired Association is found or until the parent is the ClassificationScheme.

2915 2916 2917 2918

Check if the sourceObject of the desired Association is a Service instance. If not, log an InvalidConfigurationException. If it is a Service instance, then use this Service as the Content Management service for the RegistryObject.

If desired Association(s) is found then check if the sourceObject of the desired Association is an ExtrinsicObject instance. If not, log an InvalidConfigurationException. If sourceObject is an ExtrinsicObject instance, then use its repository item as an Invocation Control File. If there are multiple InvocationControlFiles then all of them MUST be provided when invoking the Service.

2919 2920 2921

The above algorithm allows for objectType hierarchy to be used to configure Content Management Services and Invocation Control Files with varying degrees of specificity or specialization with respect to the type of content.

2922

8.6.2

2923 2924 2925 2926 2927 2928

The Cataloged Content generated as a result of the invocation of a Content Management Service has an audit trail consistent with RegistryObject instances that are submitted by Registry Clients. However, since a Registry Client does not submit Cataloged Content, the user attribute of the AuditableEvent instances for such Cataloged Content references the Service object for the Content Management Service that generated the Cataloged Content. This allows an efficient way to distinguish Cataloged Content from content submitted by Registry Clients.

2929

8.6.3

2930 2931

A registry MUST maintain referential integrity between the RegistryObjects and repository items invocation of a Content Management Service.

2932

8.6.4

2933 2934 2935 2936

If the Content Management Service is classified by the “FailOnError” ClassificationNode under canonical ErrorHandlingModel ClassificationScheme as defined by [ebRIM], then the registry MUST stop further processing of the Submit/UpdateObjectsRequest and return status of “Failure” upon first error returned by a Content Management Service Invocation.

Audit Trail and Cataloged Content

Referential Integrity

Error Handling

May 2, 2005 Page 83 of 133

2937 2938 2939 2940 2941 2942 2943 2944

If the Content Management Service is classified by the “LogErrorAndContinue” ClassificationNode under ErrorHandlingModel then the registry MUST continue to process the Submit/UpdateObjectsRequest and not let any Content Management Service invocation error affect the storing of the RegistryObjects and repository items that were submitted. Such errors SHOULD be logged as Warnings within the RegistryResponse returned to the client. In this case a registry MUST return a normal response with status of “Success” if the submitted content and metadata is stored successfully even when there are errors encountered during dynamic invocation of one or more Content Management Services.

2945

8.7

2946 2947 2948

The interface of a Content Validation Service MUST implement a single method called validateContent. The validateContent method accepts a ValidateContentRequest as parameter and returns a ValidateContentResponse as its response if there are no errors.

2949 2950 2951

The OriginalContent element within a ValidateContentRequest MUST contain exactly one RegistryObject that needs to be cataloged. The resulting ValidateContentResponse contains the status attribute that communicates whether the RegistryObject (and its content) are valid or not.

2952 2953

The Validate Content protocol does not specify the implementation details of any specific Content Validation Service.

Validate Content Protocol

2954 2955



Figure 18: Validate Content Protocol

2956

8.7.1

2957 2958 2959 2960

The ValidateContentRequest is used to pass content to a Content Validation Service so that it can validate the specified RegistryObject and any associated content. The RegistryObject typically is an ExternalLink (in the case of external content) or an ExtrinsicObject. The ValidateContentRequest extends the base type ContentManagementServiceRequestType.

2961

8.7.1.1

2962 2963 2964 2965 2966 2967 2968

ValidateContentRequest

Syntax:

May 2, 2005 Page 84 of 133

</complexContent> </complexType> </element>

2969 2970 2971 2972



2973

8.7.1.2

2974 2975

The following parameters are parameters that are either newly defined for this type or are inherited and have additional semantics beyond those defined in the base type description.

Parameters:

InvocationControlFile: Inherited from base type. This parameter may not be present. If present its format is defined by the Content Validation Service.

2976 2977

OriginalContent: Inherited from base type. This parameter MUST contain exactly one RegistryObject (e.g. ExternalLink, ExtrinsicObject) and potentially an associated content. This specification does not specify the format of the content. If it is an ExtrinsicObject then there MAY be a corresponding repository item as an attachment to this request that is the content. The corresponding repository item SHOULD follow the same rules as attachments in Submit/UpdateObjectsRequest.

2978 2979 2980 2981 2982 2983 2984 2985

8.7.1.3

Returns:

2986

This request returns a ValidateContentResponse. See section 8.7.2 for details.

2987

8.7.1.4

2988 2989

In addition to the exceptions returned by base request types, the following exceptions MAY be returned:

Exceptions:

InvalidContentException: signifies that the specified content was found to be invalid. The exception SHOULD include enough detail for the client to be able to determine how to make the content valid.

2990 2991 2992 2993 2994

8.7.2

ValidateContentResponse

2995 2996

The ValidateContentResponse is sent by the Content Validation Service as a response to a ValidateContentRequest.

2997 2998

8.7.2.1

Syntax:

2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009



3010

8.7.2.2

3011 3012

The following parameters are parameters that are either newly defined for this type or are inherited and have additional semantics beyond those defined in the base type description.

Parameters:

May 2, 2005 Page 85 of 133

status: Inherited attribute. This enumerated value is used to indicate the status of the request. Values for status are as follows:

3013 3014 3015

•

3016 3017

•

3018 3019 3020 3021 3022

Success - This status specifies that the content specified in the ValidateContentRequest was valid. Failure - This status specifies that the request failed. If the error returned is an InvalidContentException then the content specified in the ValidateContentRequest was invalid. If there was some other failure encountered during the processing of the request then a different error MAY be returned.

3023 3024

8.8

Catalog Content Protocol

3025 3026 3027

The interface of the Content Cataloging Service MUST implement a single method called catalogContent. The catalogContent method accepts a CatalogContentRequest as parameter and returns a CatalogContentResponse as its response if there are no errors.

3028 3029 3030

The CatalogContentRequest MAY contain repository items that need to be cataloged. The resulting CatalogContentResponse contains the metadata and possibly content that gets generated or updated by the Content Cataloging Service as a result of cataloging the specified repository items.

3031 3032

The Catalog Content protocol does not specify the implementation details of any specific Content Cataloging Service.

3033 3034



Figure 19: Catalog Content Protocol

3035

8.8.1

3036 3037 3038 3039

The CatalogContentRequest is used to pass content to a Content Cataloging Service so that it can create catalog metadata for the specified RegistryObject and any associated content. The RegistryObject typically is an ExternalLink (in case of external content) or an ExtrinsicObject. The CatalogContentRequest extends the base type ContentManagementServiceRequestType.

3040

8.8.1.1

3041

CatalogContentRequest

Syntax:

May 2, 2005 Page 86 of 133

3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052



3053

8.8.1.2

3054 3055

The following parameters are parameters that are either newly defined for this type or are inherited and have additional semantics beyond those defined in the base type description.

Parameters:

InvocationControlFile: Inherited from base type. If present its format is defined by the Content Cataloging Service.

3056 3057

3058 3059 3060 3061 3062 3063 3064 3065

8.8.1.3

Returns:

3066

This request returns a CatalogContentResponse. See section 8.8.2 for details.

3067

8.8.1.4

3068 3069

In addition to the exceptions returned by base request types, the following exceptions MAY be returned:

Exceptions:

CatalogingException: signifies that an exception was encountered in the Cataloging algorithm for the service.

3070 3071 3072 3073

8.8.2

CatalogContentResponse

3074 3075

The CatalogContentResponse is sent by the Content Cataloging Service as a response to a CatalogContentRequest.

3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087

8.8.2.1

Syntax:

May 2, 2005 Page 87 of 133

</complexType> </element>

3088 3089 3090



3091

8.8.2.2

3092 3093

The following parameters are parameters that are either newly defined for this type or are inherited and have additional semantics beyond those defined in the base type description.

Parameters:

CatalogedContent: This parameter specifies a collection of RegistryObject instances that were created or updated as a result of dynamic content cataloging by a content cataloging service. The Content Cataloging Service may add metadata such as Classifications, ExternalIdentifiers, name, description etc. to the CatalogedContent element. There MAY be an accompanying repository item as an attachment to this response message if the original repository item was modified by the request.

3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109

8.9

Figure 20 shows a UML instance diagram to illustrate how a Content Cataloging Service is used. This Content Cataloging Service is the normative Canonical XML Cataloging Service described in section 8.10. o In the center we see a Content Cataloging Service name defaultXMLCataloger Service. o On the left we see a CPP repository item and its ExtrinsicObject inputExtObjForCPP being input as Original Content to the defaultXMLCataloging Service. o

On top we see an XSLT style sheet repository item and its ExtrinsicObject that is configured as an Invocation Control File for the defaultXMLCataloger Service.

On the right we see the outputExtObjForCPP, which is the modified ExtrinsicObject for the CPP. We also see a Classification roleClassification, which classifies the CPP by the Role element within the CPP. These are the Cataloged Content generated as a result of the Cataloging Service cataloging the CPP.

3110 3111 3112 3113 3114

Illustrative Example: Canonical XML Cataloging Service

May 2, 2005 Page 88 of 133

Invocation Control File OriginalContent

3115 3116



CatalogedContent

Figure 20: Example of CPP cataloging using Canonical XML Cataloging Service

3117 3118

8.10

Canonical XML Content Cataloging Service

3119 3120

An ebXML Registry MUST provide the canonical XML Content Cataloging Service natively as a built-in service with the following constraints:

3121

•

There is exactly one Service instance for the Canonical XML Content Cataloging Service

3122

•

The Service is an XSLT engine

3123

•

The Service may be invoked with exactly one Invocation Control File

3124

•

The Original Content for the Service MUST be XML document(s)

3125

•

The Cataloged Content for the Service MUST be XML document(s)

3126

•

The Invocation Control File MUST be an XSLT style sheet

3127 3128 3129 3130

•

Each invocation of the Service MAY be with different Invocation Control File (XSLT style sheet) depending upon the objectType of the RegistryObject being cataloged. Each objectType SHOULD have its own unique XSLT style sheet. For example, ebXML CPP documents SHOULD have a specialized ebXML CPP Invocation Control XSLT style sheet.

3131 3132

•

The Service MUST have at least one input XML document that is a RegistryObject. Typically this is an ExtrinsicObject or an ExternalLink.

3133 3134 3135 3136 3137 3138

•

The Service MAY have at most one additional input XML document that is the content represented by the RegistryObject (e.g. a CPP document or an HL7 Conformance Profile). The optional second input MUST be referenced within the XSLT Style sheet by a using the “document” function with the document name specified by variable “repositoryItem” as in “document($repositoryItem).” A registry MUST define the variable “repositoryItem” when invoking the Canonical XML Cataloging Service.

3139 3140

•

The canonical XML Content Cataloging Service MUST apply the XSLT style sheet to the input XML instance document(s) in an XSLT transformation to generate the Cataloged Output.

May 2, 2005 Page 89 of 133

3141

The Canonical XML Content Cataloging Service is a required normative feature of an ebXML Registry.

3142

8.10.1

3143 3144 3145

An ebXML Registry MUST provide the canonical XML Content Cataloging Service natively as a built-in service. This built-in service MUST be published to the registry as part of the intrinsic bootstrapping of required canonical data within the registry.

Publishing of Canonical XML Content Cataloging Service

May 2, 2005 Page 90 of 133

3146

3147 3148

This chapter describes the capabilities and protocols that enable multiple ebXML registries to cooperate with each other to meet advanced use cases.

3149

9.1

3150 3151

The following is a list of use cases that illustrate different ways that ebXML registries cooperate with each other.

3152

9.1.1

3153 3154

A Submitting Organization wishes to submit a RegistryObject to a registry such that the submitted object references a RegistryObject in another registry.

3155 3156

An example might be where a RegistryObject in one registry is associated with a RegistryObject in another registry.

3157 3158

Cooperating Registries Support Cooperating Registries Use Cases

Inter-registry Object References



Figure 21: Inter-registry Object References

3159 3160

9.1.2

Federated Queries

3161 3162 3163 3164

A client wishes to issue a single query against multiple registries and get back a single response that contains results based on all the data contained in all the registries. From the client’s perspective it is issuing its query against a single logical registry that has the union of all data within all the physical registries.

3165

9.1.3

3166 3167 3168

A destination registry wishes to cache some or all the data of another source registry that is willing to share its data. The shared dataset is copied from the source registry to the destination registry and is visible to queries on the destination registry even when the source registry is not available.

3169 3170

Local caching of data may be desirable in order to improve performance and availability of accessing that object.

3171 3172

An example might be where a RegistryObject in one registry is associated with a RegistryObject in another registry, and the first registry caches the second RegistryObject locally.

3173

9.1.4

3174 3175

A Submitting Organization wishes to relocate its RegistryObjects and/or repository items from the registry where it was submitted to another registry.

Local Caching of Data from Another Registry

Object Relocation

May 2, 2005 Page 91 of 133

3176

9.2

3177 3178 3179

A registry federation is a group of registries that have voluntarily agreed to form a loosely coupled union. Such a federation may be based on common business interests and specialties that the registries may share. Registry federations appear as a single logical registry to registry clients.

3180 3181

Registry Federations



Figure 22: Registry Federations

3182 3183 3184

Registry federations are based on a peer-to-peer (P2P) model where all participating registries are equal. Each participating registry is called a registry peer. There is no distinction between the registry operator that created a federation and those registry operators that joined that Federation later.

3185 3186 3187

Any registry operator MAY form a registry federation at any time. When a federation is created it MUST have exactly one registry peer which is the registry operated by the registry operator that created the federation.

3188

Any registry MAY choose to voluntarily join or leave a federation at any time.

3189

9.2.1

3190 3191 3192 3193

The Registry Information model defines the Registry and Federation classes. Instances of these classes and the associations between these instances describe a federation and its members. Such instance data is referred to as Federation Metadata. The Registry and Federation classes are described in detail in [ebRIM].

3194

The Federation information model is summarized here as follows:

Federation Metadata

3195

A Federation instance represents a registry federation.

3196

A Registry instance represents a registry that is a member of the Federation.

3197

An Association instance with associationType of HasFederationMember represents membership of the registry in the federation. This Association links the Registry instance and the Federation instance.

3198 3199 3200

May 2, 2005 Page 92 of 133

3201 3202



Figure 23: Federation Metadata Example

3203

9.2.2

Local Vs. Federated Queries

3204 3205 3206

A federation appears to registry clients as a single unified logical registry. An AdhocQueryRequest sent by a client to a federation member MAY be local or federated. A new boolean attribute named federated is added to AdhocQueryRequest to indicate whether the query is federated or not.

3207

9.2.2.1

3208 3209

When the federated attribute of AdhocQueryRequest has the value of false then the query is a local query. In the absence of a federated attribute the default value of federated attribute is false.

3210 3211

A local AdhocQueryRequest is only processed by the registry that receives the request. A local AdhocQueryRequest does not operate on data that belongs to other registries.

3212

9.2.2.2

3213 3214

When the federated attribute of AdhocQueryRequest has the value of true then the query is a federated query.

3215 3216

A federation member MUST route a federated query received by it to all other federation member registries on a best attempt basis. If a member is not reachable for any reason then it MAY be skipped.

3217 3218

When a registry routes a federated query to other federation members it MUST set the federated attribute value to false and the federation attribute value to null to avoid infinite loops.

3219

A federated query operates on data that belongs to all members of the federation.

3220 3221

When a client submits a federated query to a registry such that the query specifies no federation and no federations exist in the registry, then the registry MUST treat it as a local query.

3222 3223 3224 3225

When a client submits a federated query that invokes a parameterized stored query, the registry MUST resolve the parameterized stored query into its non-stored formed and MUST replace all variables with user-supplied parameters on registry supplied contextual parameters before routing it to a federation member.

3226 3227 3228

When a client submits a federated iterative query, the registry MUST use the startIndex attribute value of the original request as the startIndex attribute value of the routed request sent to each federation member. The response to the original request MUST be the union of the results from each routed

Local Queries

Federated Queries

May 2, 2005 Page 93 of 133

3229 3230 3231

query. In such cases the registry MUST return a totalResultCount attribute value on the federated query response to be equal to the maximum of all totalResultCount attribute values returned by each federation member.

3232

9.2.2.3

3233 3234 3235

A registry MAY be a member of multiple federations. In such cases if the federated attribute of AdhocQueryRequest has the value of true then the registry MUST route the federated query to all federations that it is a member of.

3236 3237 3238

Alternatively, the client MAY specify the id of a specific federation that the registry is a member of, as the value of the federation parameter. The type of the federation parameter is anyURI and identifies the “id” attribute of the desired Federation.

3239

In such cases the registry MUST route the federated query to the specified federation only.

3240

9.2.3

3241 3242

Details on how to create and delete federations and how to join and leave a federation are described in 9.2.8.

3243 3244 3245

All lifecycle operations SHOULD be performed on a RegistryObject within its home registry using the operations defined by the LifeCycleManager interface. Unlike query requests, lifecycle management requests do not support any federated capabilities.

3246

9.2.4

3247 3248

A federation member is not required to maintain a local cache of replicas of RegistryObjects and repository items that belong to other members of the federation.

3249 3250 3251

A registry MAY choose to locally cache some or all data from any other registry whether that registry is a federation member or not. Data caching is orthogonal to registry federation and is described in section 9.3.

3252 3253

Since by default there is minimal replication in the members of a federation, the federation architecture scales well with respect to memory and disk utilization at each registry.

3254

Data replication is often necessary for performance, scalability and fault-tolerance reasons.

3255

9.2.5

3256 3257 3258 3259 3260

A special case for local caching is the caching of the Federation and Registry instances and related Associations that define a federation and its members. Such data is referred to as federation metadata. A federation member is required to locally cache the federation metadata, from the federation home for each federation that it is a member of. The reason for this requirement is consistent with a Peer-toPeer (P2P) model and ensures fault-tolerance in case the Federation home registry is unavailable.

3261 3262 3263 3264

The federation member MUST keep the cached federation metadata synchronized with the master copy in the Federation home, within the time period specified by the replicationSyncLatency attribute of the Federation. Synchronization of cached Federation metadata may be done via synchronous polling or asynchronous event notification using the event notification feature of the registry.

3265

9.2.6

3266 3267 3268

Federation members are not required to synchronize their system clocks with each other. However, each Federation member SHOULD keep its clock synchronized with an atomic clock server within the latency described by the replicationSyncLatency attribute of the Federation.

3269

9.2.7

3270 3271

Federated operations abide by the same security rules as standard operations against a single registry. However, federation operations often require registry-to-registry communication. Such communication

Membership in Multiple Federations

Federated Lifecycle Management Operations

Federations and Local Caching of Remote Data

Caching of Federation Metadata

Time Synchronization Between Registry Peers

Federations and Security

May 2, 2005 Page 94 of 133

3272 3273 3274 3275 3276

is governed by the same security rules as a Registry Client to registry communication. The only difference is that the requesting registry plays the role of Registry Client. Such registry-to-registry communication SHOULD be conducted over a secure channel such as HTTP/S. Federation members SHOULD be part of the same SAML Federation if member registries implement the Registry SAML Profile described in chapter 11.

3277

9.2.8

3278 3279 3280 3281 3282

This section describes the various operations that manage the lifecycle of a federation and its membership. Federation lifecycle operations are done using standard LifeCycleManager interface of the registry in a stylized manner. Federation lifecycle operations are privileged operations. A registry SHOULD restrict Federation lifecycle operations to registry User’s that have the RegistryAdministrator role.

3283

9.2.8.1

3284

The following rules govern how a registry joins a federation:

Federation Lifecycle Management Protocols

Joining a Federation

3285 3286 3287 3288

•

Each registry SHOULD have exactly one Registry instance within that registry for which it is a home. The Registry instance is owned by the RegistryOperator and may be placed in the registry using any operator specific means. The Registry instance SHOULD never change its home registry.

3289 3290 3291 3292

•

A registry MAY request to join an existing federation by submitting an instance of an Extramural Association that associates the Federation instance as sourceObject, to its Registry instance as targetObject, using an associationType of HasFederationMember. The home registry for the Association and the Federation objects MUST be the same.

3293 3294

9.2.8.2

Creating a Federation

3295

The following rules govern how a federation is created:

3296 3297

•

A Federation is created by submitting a Federation instance to a registry using SubmitObjectsRequest.

3298

•

The registry where the Federation is submitted is referred to as the federation home.

3299

•

The federation home may or may not be a member of that Federation.

3300

•

A federation home MAY contain multiple Federation instances.

3301

9.2.8.3

3302

The following rules govern how a registry leaves a federation:

3303 3304 3305

A registry MAY leave a federation at any time by removing its HasFederationMember Association instance that links it with the Federation instance. This is done using the standard RemoveObjectsRequest.

3306

9.2.8.4

3307

The following rules govern how a federation is dissolved:

Leaving a Federation

Dissolving a Federation

3308 3309

•

A federation is dissolved by sending a RemoveObjectsRequest to its home registry and removing its Federation instance.

3310 3311

•

The removal of a Federation instance is controlled by the same Access Control Policies that govern any RegistryObject.

3312 3313 3314

•

The removal of a Federation instance is controlled by the same lifecycle management rules that govern any RegistryObject. Typically, this means that a federation MUST NOT be dissolved while it has federation members. It MAY however be deprecated at any time. Once a

May 2, 2005 Page 95 of 133

Federation is deprecated no new members can join it.

3315 3316 3317

9.3

Object Replication

3318 3319 3320 3321

RegistryObjects within a registry MAY be replicated in another registry. A replicated copy of a remote object is referred to as its replica. The remote object MAY be an original object or it MAY be a replica. A replica from an original is referred to as a first-generation replica. A replica of a replica is referred to as a second-generation replica (and so on).

3322 3323 3324

The registry that replicates a remote object locally is referred to as the destination registry for the replication. The registry that contains the remote object being replicated is referred to as the source registry for the replication.

3325

3326 3327



Figure 24: Object Replication

3328 3329

9.3.1

3330 3331

A registry MAY create a local replica of a remote object for a variety of reasons. A few sample use cases follow:

3332

Improve access time and fault tolerance by locally caching remote objects. For example, a registry MAY automatically create a local replica when a remote ObjectRef is submitted to the registry.

Improve scalability by distributing access to hotly contested objects, such as NAICS scheme, across multiple replicas.

Enable cooperating registry features such as hierarchical registry topology and local caching of federation metadata.

3333 3334 3335 3336 3337

Use Cases for Object Replication

3338 3339

9.3.2

Queries And Replicas

3340 3341 3342

A registry MUST support client queries to consider a local replica of remote object as if it were a local object. Local replicas are considered within the extent of the data set of a registry as far as local queries are concerned.

3343 3344

When a client submits a local query that retrieves a remote object by its id attribute, if the registry contains a local replica of that object then the registry SHOULD return the state defined by the local regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 96 of 133

3345

replica.

3346

9.3.3

3347 3348

LifeCycle operations on an original object MUST be performed at the home registry for that object. LifeCycle operations on replicas of an original object should result in an InvalidRequestException.

3349

9.3.4

3350 3351 3352

Object replication capability is orthogonal to the registry federation capability. Objects MAY be replicated from any registry to any other registry without any requirement that the registries belong to the same federation.

3353

9.3.5

3354 3355 3356 3357 3358

Any Submitting Organization can create a replica by using the standard SubmitObjectsRequest. If a registry receives a SubmitObjectsRequest that has a RegistryObjectList containing a remote ObjectRef, then it MUST create a replica for that remote ObjectRef. In such cases the User that submitted the ObjectRef (via a SubmitObjectsRequest) owns the replica while the original RegistryObject is owned by its original owner.

3359 3360

In addition to Submitting Organizations, a registry itself MAY create a replica under specific situations in a registry specific manner.

3361 3362

Creating a local replica requires the destination registry to read the state of the remote object from the source registry and then create a local replica of the remote object.

3363 3364 3365 3366

A registry SHOULD use standard QueryManager interface to read the state of a remote object (whether it is an original or a replica). No new APIs are needed to read the state of a remote object. Since query functionality does not need prior registration, no prior registration or contract is needed for a registry to read the state of a remote object.

3367 3368 3369

Once the state of the remote object has been read, a registry MAY use registry specific means to create a local replica of the remote object. Such registry specific means MAY include the use of the LifeCycleManager interface.

3370 3371

A replica of a RegistryObject may be distinguished from an original since a replica MUST have its home attribute point to the remote registry where the original for the replica resides.

3372

9.3.6

3373 3374

Transactional replication enables a registry to replicate events in another registry in a transactionally consistent manner. This is typically the case when entire registries are replicated to another registry.

3375 3376

This specification defines a more loosely coupled replication model as an alternative to transactional replication for the following reasons:

•

Lifecycle Operations And Replicas

Object Replication and Federated Registries

Creating a Local Replica

Transactional Replication

3379

•

Transactional replication requires a tight coupling between registries participating in the replication Transactional replication is not a typical use case for registries

3380

•

Loosely coupled replication as defined by this specification typically suffices for most use cases

3381

•

Transaction replication is very complex and error prone

3377 3378

3382 3383

Registry implementations are not required to implement transactional replication.

3384

9.3.7

3385 3386

A registry MUST keep its replicas current within the latency specified by the value of the replicationSyncLatency attribute defined by the registry. This includes removal of the replica when its

Keeping Replicas Current

May 2, 2005 Page 97 of 133

3387

original is removed from its home registry.

3388

Replicas MAY be kept current using the event notification feature of the registry or via periodic polling.

3389

9.3.8

3390 3391 3392 3393

Local Replicas are read-only objects. Lifecycle management actions are not permitted on local replicas with the exception of the Delete action which is used to remove the replica. All other lifecycle management actions MUST be performed on the original RegistryObject in the home registry for the object.

3394

9.3.9

3395 3396 3397 3398 3399

A local replica of a remote RegistryObject instance MUST have exactly one ObjectRef instance within the local registry. The home attribute of the ObjectRef associated with the replica tracks its home location. A RegistryObject MUST have exactly one home. The home for a RegistryObject MAY change via Object Relocation as described in section 9.4. It is optional for a registry to track location changes for replicas within it.

3400

9.3.10

3401 3402 3403

It is possible to have a remote ObjectRef to a RegistryObject that is a replica of another RegistryObject. In such cases the home attribute of the ObjectRef contains the base URI to the home registry for the replica.

3404

9.3.11

3405 3406 3407 3408

A client can remove a replica by using the RemoveObjectsRequest. If a registry receives a RemoveObjectsRequest that has an ObjectRefList containing a remote ObjectRef, then it MUST remove the local replica for that remote ObjectRef assuming that the client was authorized to remove the replica.

3409

9.4

3410 3411 3412

Every RegistryObject has a home registry and a User within the home registry that is the Submitter or owner of that object. Initially, the home registry is the where the object is originally submitted. Initially, the owner is the User that submitted the object.

3413 3414

A RegistryObject MAY be relocated from one home registry to another home registry using the Object Relocation protocol.

3415 3416

Within the Object Relocation protocol, the new home registry is referred to as the destination registry while the previous home registry is called the source registry.

Lifecycle Management of Local Replicas

Tracking Location of a Replica

Remote Object References to a Replica

Removing a Local Replica

Object Relocation Protocol

May 2, 2005 Page 98 of 133

3417 3418



Figure 25: Object Relocation

3419 3420 3421 3422

The User at the source registry who owns the objects being relocated is referred to as the ownerAtSource. The User at the destination registry, who is the new owner of the objects, is referred to as the ownerAtDestination. While the ownerAtSource and the ownerAtDestination may often be the same, the Object Relocation protocol treats them as two distinct identities.

3423 3424 3425

A special case usage of the Object Relocation protocol is to transfer ownership of RegistryObjects from one User to another within the same registry. In such cases the protocol is the same except for the fact that the source and destination registries are the same.

3426

Following are some notable points regarding object relocation:

3427 3428

•

Object relocation does not require that the source and destination registries be in the same federation or that either registry have a prior contract with the other.

3429 3430

•

Object relocation MUST preserve object id. While the home registry for a RegistryObject MAY change due to object relocation, its id never changes.

3431 3432 3433 3434 3435

•

ObjectRelocation MUST preserve referential integrity of RegistryObjects. Relocated objects that have references to an object that did not get relocated MUST preserve their reference. Similarly objects that have references to a relocated object MUST also preserve their reference. Thus, relocating an object may result in making the value of a reference attribute go from being a local reference to being a remote reference or vice versa.

3436 3437

•

AcceptObjectsRequest does not include ObjectRefList. It only includes an opaque transactonId identifying the relocateObjects transaction.

3438 3439

•

The requests defined by the Relocate Objects protocol MUST be sent to the source or destination registry only.

3440 3441 3442

•

When an object is relocated an AuditableEvent of type “Relocated” MUST be recorded by the sourceRegistry. Relocated events MUST have the source and destination registry’s base URIs recorded as two Slots on the Relocated event. The names of these Slots are: o urn:oasis:names:tc:ebxml-regrep:rs:events:sourceRegistry

3443 3444

urn:oasis:names:tc:ebxml-regrep:rs:events:destinationRegistry

3445

May 2, 2005 Page 99 of 133

3446 3447



Figure 26: Relocate Objects Protocol

3448 3449 3450

Figure 26 illustrates the Relocate Objects Protocol. The participants in the protocol are the ownerAtSource and ownerAtDestination User instances as well as the LifeCycleManager interfaces of the sourceRegistry and destinationRegistry.

3451

The steps in the protocol are described next:

3452 3453 3454 3455 3456 3457

1. The protocol is initiated by the ownerAtSource sending a RelocateObjectsRequest message to the LifeCycleManager interface of the sourceRegistry. The sourceRegistry MUST make sure that the ownerAtSource is authorized to perform this request. The id of this RelocateObjectsRequest is used as the transaction identifier for this instance of the protocol. This RelocateObjectsRequest message MUST contain an ad hoc query that specifies the objects that are to be relocated.

3458 3459 3460 3461 3462

2. Next, the sourceRegistry MUST relay the same RelocateObjectsRequest message to the LifeCycleManager interface of the destinationRegistry. This message enlists the detsinationRegistry to participate in relocation protocol. The destinationRegistry MUST store the request information until the protocol is completed or until a registry specific period after which the protocol times out.

3463 3464 3465 3466 3467

3. The destinationRegistry MUST relay the RelocateObjectsRequest message to the ownerAtDestination. This notification MAY be done using the event notification feature of the registry as described in chapter 7. The notification MAY be done by invoking a listener Service for the ownerAtDestination or by sending an email to the ownerAtDestination. This concludes the first phase of the Object Relocation protocol.

3468 3469 3470 3471

4. The ownerAtDestination at a later time MAY send an AcceptObjectsRequest message to the destinationRegistry. This request MUST identify the object relocation transaction via the correlationId. The value of this attribute MUST be the id of the original RelocateObjectsRequest.

3472 3473 3474 3475

5. The destinationRegistry sends an AdhocQueryRequest message to the sourceRegistry. The source registry returns the objects being relocated as an AdhocQueryResponse. In the event of a large number of objects this may involve multiple AdhocQueryRequest/responses as described by the iterative query feature described in section 6.2.

3476 3477 3478 3479

6. The destinationRegistry submits the relocated data to itself assigning the identity of the ownerAtDestination as the owner. The relocated data MAY be submitted to the destination registry using any registry specific means or a SubmitObjectsRequest. However, the effect SHOULD be the same as if a SubmitObjectsRequest was used. regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 100 of 133

3480 3481

7. The destinationRegistry notifies the sourceRegistry that the relocated objects have been safely committed using the Event Notification feature of the registry as described in chapter 7.

3482 3483 3484

8. The sourceRegistry removes the relocated objects using any registry specific means and logging an AuditableEvent of type Relocated. This concludes the Object Relocation transaction.

3485

9.4.1

RelocateObjectsRequest <element name="RelocateObjectsRequest"> <complexType> <complexContent> <extension base="rs:RegistryRequestType"> <sequence> <element name="Query" type="rim:AdhocQueryType"/> <element name="SourceRegistry" type="rim:ObjectRefType"/> <element name="DestinationRegistry" type="rim:ObjectRefType"/> <element name="OwnerAtSource" type="rim:ObjectRefType"/> <element name="OwnerAtDestination" type="rim:ObjectRefType"/> </sequence> </extension> </complexContent> </complexType> </element>

3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503



3504

9.4.1.1

Parameters: id: the attribute id provides the transaction identifier for this instance of the protocol. AdhocQuery: This element specifies an ad hoc query that selects the RegistryObjects that are being relocated. sourceRegistry: This element specifies the ObjectRef to the sourceRegistry Registry instance. The value of this attribute MUST be a local reference when the message is sent by the ownerAtSource to the sourceRegistry. destinationRegistry: This element specifies the ObjectRef to the destinationRegistry Registry instance. ownerAtSource: This element specifies the ObjectRef to the ownerAtSource User instance. ownerAtDestination: This element specifies the ObjectRef to the ownerAtDestination User instance.

3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517

9.4.1.2

Returns:

3518

This request returns a RegistryResponse. See section 2.1.4 for details.

3519

9.4.1.3

3520

In addition to the exceptions common to all requests, the following exceptions MAY be returned:

Exceptions: ObjectNotFoundException: signifies that the specified Registry or User was not found in the registry.

3521 3522 3523 3524 3525

9.4.2

AcceptObjectsRequest <element name="AcceptObjectsRequest">

May 2, 2005 Page 101 of 133

3526 3527 3528 3529 3530 3531 3532 3533 3534 3535



3536

9.4.2.1

Parameters: correlationId: Provides the transaction identifier for this instance of the protocol.

3537 3538 3539

9.4.2.2

Returns:

3540

This request returns a RegistryResponse. See section 2.1.4 for details.

3541

9.4.2.3

3542

In addition to the exceptions common to all requests, the following exceptions MAY be returned:

Exceptions: InvalidRequestException: signifies that the specified correlationId was not found to match an ongoing RelocateObjectsRequest in the registry.

3543 3544 3545 3546

9.4.3

Object Relocation and Remote ObjectRefs

3547

The following scenario describes what typically happens when a person moves:

3548 3549

1. When a person moves from one house to another, other persons may have their old postal addresses.

3550 3551

2. When a person moves, they leave their new address as the forwarding address with the post office.

3552

3. The post office forwards their mail for some time to their new address.

3553 3554

4. Eventually the forwarding request expires and the post office no longer forwards mail for that person.

3555

5. During this forwarding interval the person notifies interested parties of their change of address.

3556 3557

The Object Relocation feature supports a similar model for relocation of RegistryObjects. The following steps describe the expected behavior when an object is relocated.

3558 3559

1. When a RegistryObject O1 is relocated from one registry R1 to another registry R2, other RegistryObjects may have remote ObjectRefs to O1.

3560 3561

2. The registry R1 MUST create an AuditableEvent of type Relocated that includes the home URI for the new registry R2.

3562 3563 3564 3565 3566

3. As long as the AuditableEvent exists in R1, if R1 gets a request to retrieve O1 by id, it MUST forward the request to R2 and transparently retrieve O1 from R2 and deliver it to the client. The object O1 MUST include the home URI to R2 within the optional home attribute of RegistryObject. Clients are advised to check the home attribute and update the home attribute of their local ObjectRef to match the new home URI value for the object.

3567 3568 3569

4. Eventually the AuditableEvent is cleaned up after a registry specific interval. R1 is no longer required to relay requests for O1 to R2 transparent to the client. Instead R1 MUST return an ObjectNotFoundException.

May 2, 2005 Page 102 of 133

3570 3571 3572 3573

5. Clients that are interested in the relocation of O1 and being notified of its new address may choose to be notified by having a prior subscription using the event notification facility of the registry. For example a Registry that has a remote ObjectRefs to O1 may create a subscription on relocation events for O1. This however, is not required behavior.

3574

9.4.4

Notification of Object Relocation To ownerAtDestination

3575 3576

This section describes how the destinationRegistry uses the event notification feature of the registry to notify the ownerAtDestination of a Relocated event.

3577

The destinationRegistry MUST send a Notification with the following required characteristics:

3578

•

The notification MUST be an instance of a Notification element.

3579

•

The Notification instance MUST have at least one Slot as follows:

3580 3581

The Slot MUST have the name: urn:oasis:names:tc:ebxml-regrep:rs:events:correlationId

3582

The Slot MUST have the correlationId for the Object Relocation transaction as the value of the Slot.

3583 3584 3585

9.4.5

Notification of Object Commit To sourceRegistry

3586 3587

This section describes how the destinationRegistry uses the event notification feature of the registry to notify the sourceRegistry that it has completed committing the relocated objects.

3588

The destinationRegistry MUST send a Notification with the following required characteristics:

3589

•

The notification MUST be an instance of a Notification element.

3590

•

The Notification instance MUST have at least one Slot as follows:

3591 3592

The Slot MUST have the name urn:oasis:names:tc:ebxml-regrep:rs:events:objectsCommitted

3593

The Slot MUST have the value of true.

3594 3595

9.4.6

Object Ownership and Owner Reassignment

3596 3597 3598

A registry MUST determine the ownership of a RegistryObject based upon the most recent AuditableEvent that has the eventType matching the canonical EventType ClassificationNode for Create or Relocate events.

3599 3600 3601

A special case of Object Relocation is when an ObjectRelocationRequest to a registry specifies the same registry as sourceRegistry and destinationRegistry. In such cases the request is effectively to change the owner of the specified objects from current owner to a new owner.

3602 3603

In such case if the client does not have the RegistryAdministrator role then the protocol requires the ownerAtDestination to issue an AcceptObjectsRequest as described earlier.

3604 3605 3606

However, if the client does have the RegistryAdministrator role then the registry MUST change the owner of the object to the user specified as ownerAtDestination without the ownerAtDestination to issue an AcceptObjectsRequest.

3607

9.4.7

3608 3609 3610

No timeouts are specified for the Object Relocation protocol. Registry implementations MAY cleanup incomplete Object Relocation transactions in a registry specific manner as an administrative task using registry specific policies.

Object Relocation and Timeouts

3611

May 2, 2005 Page 103 of 133

3612

Registry Security

3613 3614 3615

This chapter describes the security features of ebXML Registry. A glossary of security terms can be referenced from [RFC 2828]. The registry security specification incorporates by reference the following specifications:

3616

•

[WSI-BSP] WS-I Basic Security Profile 1.0

3617

•

[WSS-SMS] Web Services Security: SOAP Message Security 1.0

3618

•

[WSS-SWA] Web Services Security: SOAP Messages with Attachments (SwA) Profile 1.0

3619

This chapter provides registry specific details not present in above specifications.

3620

10.1

3621 3622

This section describes various use cases that require security features from the registry. Subsequent sections describe specific registry mechanisms that enable each of these use cases.

3623

10.1.1

3624 3625 3626 3627

An organization deploys an ebXML Registry and needs to define the set of users and services that are authorized to use the services offered by the registry. They require that the registry provide some mechanism for registering and subsequently managing the identity and credentials associated with such authorized users and services.

3628

10.1.2

3629 3630 3631 3632

A Registered User sends a request message to the registry and receives a response back from the registry. The user requires that the message integrity be protected during transmission from tampering (man-in-the-middle attack). The user may also require that the message communication is not available to unauthorized parties (confidentiality).

3633

10.1.3

3634 3635 3636 3637

A Registered User submits a repository item to the registry. The user requires that the registry provide mechanisms to protect the integrity of the repository item during transmission on the wire and as long as it is stored in the registry. The user may also require that the content of the RepositoryItem is not available to unauthorized parties (confidentiality).

3638

10.1.4

3639 3640 3641

An organization that deploys an ebXML Registry requires that when a Registered User sends a request to the registry, the registry checks the credentials provided by the user to ensure that the user is a Registered User and to unambiguously determine the user’s identity.

3642

10.1.5

3643 3644 3645 3646

An organization that deploys an ebXML Registry requires that the registry provide a mechanism that protect its resources from unauthorized access. Specifically, when a Registry Requestor sends a request to the registry, the registry restricts the actions of the requestor to specific actions on specific resources for which the requestor is authorized.

3647

10.1.6

3648 3649 3650 3651

An organization that deploys an ebXML Registry requires that the registry keep a journal or Audit Trail of all significant actions performed by Registry Requestors on registry resources. This provides a basic form of non-repudiation where a Registry Requestor cannot repudiate that that they performed actions that are logged in the Audit Trail.

Security Use Cases

Identity Management

Message Security

Repository Item Security

Authentication

Authorization and Access Control

Audit Trail

May 2, 2005 Page 104 of 133

3652

10.2

Identity Management

3653 3654

An ebXML Registry MUST provide an Identity Management mechnism that allows identities and credentials to be registered for authorized users of the registry and subsequently managed.

3655 3656 3657

If a registry implements the Registry SAML Profile as described in chapter 11 then the Identity Management capability MUST be provided by an Identity Provider service that integrates with the registry using the SAML 2.0 protocols as defined by [SAMLCore].

3658 3659

If a registry does not implement the Registry SAML Profile then it MUST provide User Registration and Identity Management functionality in an implementation specific manner.

3660

10.3

3661 3662

A registry MUST provide mechanisms to securely exchange messages between a Registry Requestor and the registry to ensure data and source integrity as described in this section.

3663

10.3.1

3664 3665 3666

A registry MUST support HTTP/S communication between an HTTP Requestor and its HTTP interface binding. A registry MUST also support HTTP/S communication between a SOAP Requestor and its SOAP interface binding when the underlying transport protocol is HTTP.

3667

HTTP/S support SHOULD allow for both SSL and TLS as transport protocols.

3668

10.3.2

3669 3670 3671 3672

A registry MUST support signing and verification of all registry protocol messages (requests and responses) between a SOAP Requestor and its SOAP binding. Such mechanisms MUST conform to [WSI-BSP], [WSS-SMS], [WSS-SWA] and [XMLDSIG]. The reader should refer to these specifications for details on these message security mechanisms.

3673

10.3.2.1

3674 3675 3676 3677 3678 3679 3680

When a Registered User sends a request message to the registry, the requestor SHOULD sign the request message with a Message Signature. This ensures the integrity of the message and also enables the registry to perform authentication and authorization for the request. If the registry receives a request that does not include a Message signature then it MUST implicitly treat the request as coming from a Registry Guest. A Registered User need not sign a request message with a Message Signature when the SOAP communication is conducted over HTTP/S as the message security is handled by the transport layer security provided by HTTP/S in this case.

3681 3682 3683

When a Registered User sends a request message to the registry that contains a RepositoryItem as a SOAP Attachment, the requestor MUST also reference and sign the RepositoryItem from the message signature. This MUST conform to [RFC2392] and [WSS-SWA].

3684 3685

If the registry receives a request containing an unsigned RepositoryItem then it MUST return an UnsignedRepositoryItemException.

3686

10.3.2.2

3687 3688 3689 3690 3691 3692 3693

When a Registered User sends a request message to the registry, the registry MAY use a preestablished preference policy or a default policy to determine whether the response message SHOULD be signed with a Message Signature. When a Registry Guest sends a request, the Registration Authority MAY use a default policy to determine whether the response contains a header signature. A registry need not sign a response message with a Message Signature when the SOAP communication is conducted over HTTP/S as the message security is handled by the transport layer security provided by HTTP/S in this case.

3694 3695 3696

When a registry sends a signed response message to a Registry Client that contains a RepositoryItem as a SOAP Attachement, the registry MUST also reference and sign the RepositoryItem from the message signature. This MUST conform to [RFC2392] and [WSS-SWA].

Message Security

Transport Layer Security

SOAP Message Security

Request Message Signature

Response Message Signature

May 2, 2005 Page 105 of 133

3697 3698 3699

If the Registry Client receives a signed response with a RepositoryItem that does not include a RepositoryItem Signature then it SHOULD not trust the integrity of the response and treat it as an error condition.

3700

10.3.2.3

3701 3702 3703 3704 3705 3706

The sender of a registry protocol message (Registry Requestor and Registry) SHOULD provide their public key under the <wsse:Security> element. If provided, it MUST be contained in a <wsse:BinarySecurityToken> element and MUST be referenced from the <ds:KeyInfo> element in the Message Signature. The value of wsu:Id attribute of the <wsse:BinarySecurityToken> containing the senders public key MUST be urn:oasis:names:tc:ebxml-regrep:rs:security:SenderCert. The <wsse:BinarySecurityToken> SHOULD contain a X509 Certificate.

3707

Listing 3 shows an example of Message signature including specifying the KeyInfo.

3708

10.3.2.4

3709 3710

Signature validation ensures message and attached RepositoryItems integrity and security, concerning both data and source.

3711 3712 3713

If the registry receives a request containing a Message Signature then it MUST validate the Message Signature as defined by [WSS-SMS]. In case the request contains an attached RepositoryItem it MUST validate the RepositoryItems signature as defined by [WSS-SWA].

3714 3715 3716

If the Registry Requestor receives a response containing a Message Signature then it SHOULD validate the Message Signature as defined by [WSS-SMS]. In case the response contains an attached RepositoryItem then it SHOULD validate the RepositoryItem signature as defined by [WSS-SWA].

3717

10.3.2.5

3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749

The following example shows the format of a Message Signature:

KeyInfo Requirements

Message Signature Validation

Message Signature Example

<soap:Envelope> <soap:Header> <wsse:Security> <wsse:BinarySecurityToken EncodingType="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-soap-message-security1.0#Base64Binary" ValueType="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" wsu:Id="urn:oasis:names:tc:ebxml-regrep:rs:security:SenderCert"> lui+Jy4WYKGJW5xM3aHnLxOpGVIpzSg4V486hHFe7sHET/uxxVBovT7JV1A2RnW SWkXm9jAEdsm/ hs+f3NwvK23bh46mNmnCQVsUYHbYAREZpykrd/eRwNgx8T+ByeFhmSviW77n6yT cI7XU7xZT54S9 hTSyBLN2Sce1dEQpQXh5ssZK9aZTMrsFT1NBvNHC3Qq7w0Otr5V4axH3MXffsuI 9WzxPCfHdalN4 rLRfNY318pc6bn00zAMw0omUWwBEJZxxBGGUc9QY3VjwNALgGDaEAT7gpURkCI8 5HjdnSA5SM4cY 7jAsYX/CIpEkRJcBULlTEFrBZIBYDPzRWlSdsJRJngF7yCoGWJ+/HYOyP8P4OM5 9FDi0kM8GwOE0 WgYrJHH92qaVhoiPTLi7 </wsse:BinarySecurityToken> <ds:Signature>  <ds:SignedInfo> <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" "> <c14n:InclusiveNamespaces PrefixList="wsse soap" xmlns:c14n="http://www.w3.org/2001/10/xml-exc-c14n#"/> </ds:CanonicalizationMethod> <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> <ds:Reference URI="#TheBody"> regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 106 of 133

3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778

<ds:Transforms> <ds:Transform Algorithm="http://www.w3.org/2001/10/xmlexc-c14n#"> <c14n:InclusiveNamespaces PrefixList="" xmlns:c14n="http://www.w3.org/2001/10/xml-exc-c14n#"/> </ds:Transform> </ds:Transforms> <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> <ds:DigestValue>i3qi5GjhHnfoBn/jOjQp2mq0Na4=</ds:DigestValu e> </ds:Reference> </ds:SignedInfo> <ds:SignatureValue>PipXJ2Sfc+LTDnq4pM5JcIYt9gg=</ds:SignatureVa lue> <ds:KeyInfo> <wsse:SecurityTokenReference> <wsse:Reference URI="#urn:oasis:names:tc:ebxmlregrep:rs:security:SenderCert" ValueType="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/> </wsse:SecurityTokenReference> </ds:KeyInfo> </ds:Signature> </wsse:Security> </soap:Header> <soap:Body wsu:Id="TheBody"> <lcm:SubmitObjectsRequest/> </soap:Body> </soap:Envelope>



3779

Listing 3: Message Signature Example

3780

10.3.2.6

3781

The following example shows the format of a Message Signature that also signs the attached RespositoryItem:

3782

Message With RepositoryItem: Signature Example

3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808

Content-Type: multipart/related; boundary=”BoundaryStr” type=”text/xml” --BoundaryStr Content-Type: text/xml <soap:Envelope> <soap:Header> <wsse:Security> <wsse:BinarySecurityToken EncodingType="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-soap-message-security1.0#Base64Binary" ValueType="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" wsu:Id="urn:oasis:names:tc:ebxml-regrep:rs:security:SenderCert"> lui+Jy4WYKGJW5xM3aHnLxOpGVIpzSg4V486hHFe7sHET/uxxVBovT7JV1A2RnW SWkXm9jAEdsm/ hs+f3NwvK23bh46mNmnCQVsUYHbYAREZpykrd/eRwNgx8T+ByeFhmSviW77n6yT cI7XU7xZT54S9 hTSyBLN2Sce1dEQpQXh5ssZK9aZTMrsFT1NBvNHC3Qq7w0Otr5V4axH3MXffsuI 9WzxPCfHdalN4 rLRfNY318pc6bn00zAMw0omUWwBEJZxxBGGUc9QY3VjwNALgGDaEAT7gpURkCI8 5HjdnSA5SM4cY 7jAsYX/CIpEkRJcBULlTEFrBZIBYDPzRWlSdsJRJngF7yCoGWJ+/HYOyP8P4OM5 9FDi0kM8GwOE0 WgYrJHH92qaVhoiPTLi7 </wsse:BinarySecurityToken> <ds:Signature>  regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 107 of 133

3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871

<ds:SignedInfo> <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" "> <c14n:InclusiveNamespaces PrefixList="wsse soap" xmlns:c14n="http://www.w3.org/2001/10/xml-exc-c14n#"/> </ds:CanonicalizationMethod> <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> <ds:Reference URI="#TheBody"> <ds:Transforms> <ds:Transform Algorithm="http://www.w3.org/2001/10/xmlexc-c14n#"> <c14n:InclusiveNamespaces PrefixList="" xmlns:c14n="http://www.w3.org/2001/10/xml-exc-c14n#"/> </ds:Transform> </ds:Transforms> <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> <ds:DigestValue>i3qi5GjhHnfoBn/jOjQp2mq0Na4=</ds:DigestValu e> </ds:Reference> </ds:SignedInfo>  <ds:SignedInfo> <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" "> <c14n:InclusiveNamespaces PrefixList="wsse soap" xmlns:c14n="http://www.w3.org/2001/10/xml-exc-c14n#"/> </ds:CanonicalizationMethod> <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> <ds:Reference URI="cid:${REPOSITORY_ITEM1_ID}"> <ds:Transforms> <ds:Transform Algorithm="http://www.w3.org/2001/10/xmlexc-c14n#"> <ds:Transform Algorithm="http://docs.oasisopen.org/wss/2004/XX/oasis-2004XX-wss-swa-profile-1.0#AttachmentContent-Only-Transform"/> </ds:Transform> </ds:Transforms> <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> <ds:DigestValue>j6lwx3rvEPO0vKtMup4NbeVu8nk=</ds:DigestValu e> </ds:Reference> </ds:SignedInfo> <ds:SignatureValue>PipXJ2Sfc+LTDnq4pM5JcIYt9gg=</ds:SignatureVa lue> <ds:KeyInfo> <wsse:SecurityTokenReference> <wsse:Reference URI="#urn:oasis:names:tc:ebxmlregrep:rs:security:SenderCert" ValueType="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"/> </wsse:SecurityTokenReference> </ds:KeyInfo> </ds:Signature> </wsse:Security> </soap:Header> regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 108 of 133

<soap:Body wsu:Id="TheBody"> <lcm:SubmitObjectsRequest/> </soap:Body> </soap:Envelope> --BoundaryStr Content-Type: image/png Content-ID: <${REPOSITORY_ITEM1_ID}> Content-Transfer-Encoding: base64 the repository item (e.g. PNG Image) goes here..

3872 3873 3874 3875 3876 3877 3878 3879 3880

Listing 4: RepositoryItem Signature Example

3881 3882

10.3.2.7

SOAP Message Security and HTTP/S

3883 3884

When using HTTP/S between a Registry Client and a registry, SOAP message security MUST NOT be used. Specifically:

3885

•

The Registry Client MUST NOT sign the request message or any repository items in the request.

3886

•

The registry MUST NOT verify request or RepositoryItem signatures.

3887

•

The registry MUST NOT sign the response message or any repository items in the response.

3888

•

The Registry Client MUST NOT verify response or RepositoryItem signatures.

3889

10.3.3

3890 3891

A registry SHOULD support encryption of protocol messages as defined section 9 of [WSI-BSP] as a mechanism to support confidentiality of protocol messages during transmission on the wire.

3892 3893

A Registry Client MAY use encryption of RepositoryItems as defined by [WSS-SWA] as a mechanism to support confidentiality of RepositoryItems during transmission on the wire.

3894

A registry SHOULD support the submission of encrypted repository items.

3895

10.3.4

3896 3897

The registry and Registered Users MUST mutually exchange their public keys. This is necessary to enable:

Message Confidentiality

Key Distribution Requirements

3898 3899

•

Mutual Authentication of Registry Client and registry using SSL/TLS handshake for transport layer security over HTTP/S

3900

•

Validation of Message Signature and RepositoryItem Signature (described in section ).

3901

•

Decryption of encrypted messages

3902

In order to enable Message Security the following requirements MUST be met:

3903

1. A Certificate is associated with the registry.

3904

2. A Certificate is associated with Registry Client.

3905 3906

3. A Registry Client registers its public key certificate with the registry. This is typically done during User Registration and is implementation specific.

3907 3908

4. Registry Client obtains the registry’s public key certificate and stores it in its own local key store. This is done in an implementation specific manner.

3909 3910

10.4

Authentication

3911 3912 3913 3914

The Registry MUST be able to authenticate the identity of the User associated with client requests in order to perform authorization and access control and to maintain an Audit Trail of registry access. In security terms a service that provides the ability to authenticate requestors is referred to as an Authentication Authority.

May 2, 2005 Page 109 of 133

3915

A registry MUST provide one or more of the following Authentication mechanisms:

3916

•

Registry as Authentication Authority

3917

•

External Authentication Authority

3918 3919

10.4.1

Registry as Authentication Authority

3920 3921 3922 3923 3924 3925

A registry MAY provide authentication capability by serving as an Authentication Authority. In this role the registry uses the <ds:KeyInfo> in the Message Signature as credentials to authenticate the requestor. This typically requires checking that the public key supplied in the <ds:KeyInfo> of the Message Signature matches the public key of a Registered User. This also requires that the registry maintain a “registry keystore” that contains the public keys of Registered Users. The remaining details of registry as an authentication authority are implementation specific.

3926 3927 3928 3929

Alternatively, if the Registry Client communicates with the registry over HTTP/S, the registry MUST authenticate the Registry Client User if a registered certificate is provided through SSL Client Authentication. If the certificate is not known to the registry then the Registry MUST assign the RegistryGuest principal with the Registry Client.

3930

10.4.2

3931 3932 3933

A registry MAY also use an external Authentication Authority to auhenticate client requests. The use of an external Authentication Authority requires that the registry implement the Registry SAML Profile as described in chapter 11.

3934

10.4.3

3935 3936 3937 3938

Once a request is authenticated a Registry SHOULD establish an authenticated session using implementation specific means to avoid having to re-authenticate subsequent request from the same requestor. When the underlying transport protocol is HTTP, a registry SHOULD implement authenticated session support based upon HTTP session capability as defined by [RFC2965].

3939

10.5

3940 3941 3942

Once a registry has authenticated the identity of the Registered User associated with a client request it MUST perform authorization and subsequently enforce access control rules based upon the authorization decision.

3943 3944

Authorization and access control is an operation conducted by the registry that decides WHO can do WHAT ACTION on WHICH RESOURCE.

External Authentication Authority

Authenticated Session Support

Authorization and Access Control

3945

•

The WHO is the User determined by the authentication step.

3946

•

The WHAT ACTION is determined by the registry protocol request sent by the client.

3947 3948

•

The WHICH RESOURCE consists of the RegistryObjects and RepositoryItems impacted by the registry protocol request.

3949 3950

The Access Control Policy associated with the resource that is impacted by the action determines authorization and access control.

3951 3952 3953 3954

A registry MUST provide an access control and authorization mechanism based upon chapter titled “Access Control Information Model” in [ebRIM]. This model defines a default access control policy that MUST be supported by the registry. In addition it also defines a binding to [XACML] that allows finegrained access control policies to be defined.

3955

10.6

3956 3957

Once a registry has performed authorization checks, enforced access control and allowed a client request to proceed it services the client request. A registry MUST create an Audit Trail of all

Audit Trail

May 2, 2005 Page 110 of 133

3958 3959 3960 3961 3962

LifeCycleManager operations. A registry MAY create an Audit Trail of QueryManager operations. To conserve storage resources, a registry MAY prune the Audit Trail information it stores in an implementation specific manner. A registry SHOULD perform such pruning by removing the older information in its Audit Trail content. However, it MUST not remove the original Create Event at the beginning of the audit trail since the Create Event establishes the owner of the RegistryObject.

3963 3964

Details of how a registry maintains an Audit Trail of client requests is described in the chapter title “Event Information Model” of [ebRIM].

May 2, 2005 Page 111 of 133

3965

Registry SAML Profile

3966 3967 3968

This chapter defines the Registry SAML Profile that a registry MAY implement in order to support SAML 2.0 protocols defined by [SAMLCore]. A specific focus of the Registry SAML Profile is the Web Single Sign On (SSO) profile defined by [SAMLProf].

3969

11.1

3970 3971

The reader should refer to the SAML Glossary [SAMLGloss] for various terms used in the Registry SAML profile. A few terms are described here for convenience:

Terminology

3972

Term Authentication Authority

Enhanced Client Proxy (ECP)

Identity Provider (IdP)

Principal SAML Requestor

Definition An Authentication Authority is a system entity (typically a service) that enables other system entities (typically a user or service) to establish an authenticated session by proving their identity by providing necessary credentials (e.g. username / password, certificate alias / password). An Authentication Authority produces authentication assertions as a result of successful authentication. Describes a client that operates under certain constraints such as not being able to support HTTP Redirect protocol. Typically these are clients that do not have a Web Browser environment. In this document the main example of an ECP is a Registry Client that uses SOAP to communicate with the registry (SOAP Requestor). A kind of service provider that creates, maintains, and manages identity information for principals (e.g. users). An Identity Provider is usually also an Authentication Authority. A system entity whose identity can be authenticated. This maps to User in [ebRIM]. A system entity that utilizes the SAML protocol to request services from another system entity (a SAML authority, a responder). The term “client” for this notion is not used because many system entities simultaneously or serially act as both clients and servers.

Service Provider (SP) Single Sign On (SSO)

Single Logout

A role donned by a system entity where the system entity provides services to principals or other system entities. The Registry Service is a SP The ability to share a single authenticated session across multiple SSO enabled services and application. The client may establish the authenticated session by authenticating with any Authentication Authority within the system. The client may then perform secure operations with any SSO enabled service within the system using the authenticated session. The ability to logout nearly simultaneously from multiple Service Providers within a federated system.

3973 3974

11.2

Use Cases for SAML Profile

3975 3976

The Registry SAML Profile is intended to address following use cases using the protocols defined by [SAMLCore].

3977

11.2.1

3978 3979

A large enterprise is deploying an ebXML Registry. The enterprise already has an existing Identity Provider (e.g. an Access Manager service) where it maintains user information and credentials. The

Registry as SSO Participant:

May 2, 2005 Page 112 of 133

3980 3981 3982

enterprise also has an existing Authentication Authority (which may be the same service as the Identity Provider) that is used to authenticate users and enable Single Sign On (SSO) across all their enterprise services applications.

3983 3984 3985 3986

The enterprise wishes to use its existing Identity Provider to manage registry users and to avoid duplicating the user database contained in the Identity Provider within the registry. The enterprise also wishes to use its existing Authentication Authority to authenticate registry users and expects the registry to participate in SSO capability provided by their Authentication Authority service.

3987

Source Web Site (Company.com)

A 1.

Web User

3988 3989

uth

2. A



Asserting Party

te ca i t en

Destination Web Site (Travel.com)

cc es s

Re so urc e

Relying Party

Figure 27: SAML SSO Typical Scenario

3990

11.3

SAML Roles Played By Registry

3991 3992

In order to conform to the registry SAML Profile an ebXML Registry plays the Service Provider (SP) role based upon conformance with SAML 2.0 protocols.

3993

11.3.1

3994 3995

The Service Provider role enables the registry to participate in SAML protocols. Specifically it allows the registry to utilize an Identity Provider to perform client authentication on its behalf.

3996

11.3.1.1

3997

The following are a list of requirements for the Service Provider role of the registry:

Service Provider Role

Service Provider Requirements

3998 3999 4000

•

MUST support the protocols, messages and bindings that are the responsibility of the Service Provider as defined by Web SSO Profile in [SAMLProf]. Specifically it MUST be able to intiate and participate in the Authentication Request Protocol with an Identity Provider.

4001

•

MUST be able to use a SAML Identity Provider to authenticate client requests.

4002 4003

•

MUST support the ability to maintain a security context for registry clients across multiple client requests.

4004

May 2, 2005 Page 113 of 133

4005

11.4

Registry SAML Interface

4006 4007

In order to conform to the registry SAML Profile an ebXML Registry MUST implement a new SAML interface in addition to its service interfaces such as QueryManager and LifeCycleManager.

4008 4009

Details of the registry’s SAML interface are not described by this specification. Instead they are described by the SAML 2.0 specifications and MUST support SAML HTTP and SOAP requests.

4010 4011 4012

A registry uses its SAML interface to participate in SAML protocols with SAML Clients and SAML Identity Providers. Specifically, an IdentityProvider uses the registry’s SAML Service Provider interface to deliver the Response to an Authentication Request.

4013

11.5

4014 4015

In order to conform to the Registry SAML Profile a registry MUST implement specific SAML protocol that support specific SAML protocol message exchanges using specific protocol bindings.

4016 4017

Table 7 lists the matrix of SAML Profiles, Protocols Messages and their Bindings that a registry MUST support in order to conform to the registry SAML Profile.

4018

The reader should refer to:

Requirements for Registry SAML Profile

4019

•

[SAMLProf] for description of profiles listed

4020

•

[SAMLCore] for description of Message Flows listed

4021

•

[SAMLBind] for description of Bindings listed

4022

Profile

Message Flows

Binding

Implementation Requirement

Web SSO

Single Logout

<AuthnRequest> from Registry to IdentityProvider

HTTP redirect

MUST

IdentityProvider <Response> to Registry

HTTP POST

MUST

HTTP artifact

MUST

HTTP redirect

MUST

SOAP

MAY

HTTP redirect

MUST

SOAP

MAY

<ArtifactResolve>,

SOAP

MUST

SOAP

MUST

ECP to Registry, Registry to ECP to IdentityProvider

PAOS

MUST

IdentityProvider to ECP to Registry, Registry to ECP

PAOS

MUST

Artifact Resolution Enhanced Client/Proxy SSO

4023



4024

Table 7: Required SAML Profiles, Protocols and Bindings

4025

11.6

SSO Operation

4026

This section describes the interaction sequnce for various types of SSO operations.

4027

11.6.1

4028

The following are the actors that will be participating the various SSO Operation scenarios described in

Scenario Actors

May 2, 2005 Page 114 of 133

4029

subsequent section:

4030 4031

•

HTTP Requestor: This represents a Registry Client that accesses the registry using the HTTP binding of the registry protocols typically through a User Agent such as a Web Browser.

4032 4033

•

SOAP Requestor: This represents a Registry Client that accesses the registry using the SOAP binding of the registry protocols.

4034 4035 4036

•

Registry: This represents a Registry and includes all Registry interfaces such as QueryManager, LifeCycleManager and the registry’s SAML Service Provider. The Registry participates in ebXML Registry protocols as well as SAML protocols.

4037 4038

•

IdentityProvider: This represents the IdentityProvider used by the registry to perform Authentication on its behalf.

4039

11.6.2

4040 4041

Figure 28 shows a high level view of the Single Sign On (SSO) operation when the SOAP Requestor is unauthenticated and accesses the registry over HTTP via a User Agent such as a Web Browser.

4042 4043

SSO Operation – Unauthenticated HTTP Requestor



Figure 28: SSO Operation – Unauthenticated HTTP Requestor

4044

11.6.2.1

Scenario Sequence

4045

Figure 28 shows the following sequence of steps for the operation:

May 2, 2005 Page 115 of 133

4046 4047

The HTTP Requestor sends a HTTP GET or POST request to a Registry interface such as the QueryManager or LifeCycleManager.

4048 4049

1.1

The Registry checks to see if it already has a security context established for the Subject associated with the request. It determines that there is no pre-existing security context.

4050 4051 4052

1.2

In order to establish a security context, the Registry therefor initiates the <samlp:AuthnRequest> protocol with the IdentityProvider. The <AuthnRequest> is sent using HTTP Redirect via the User Agent (e.g. Web Browser) used by the HTTP Requestor.

4053 4054 4055 4056 4057 4058

1.2.1

The IdentityProvider uses implementation specific means to identify the Subject. Typically this requires communicating with the User Agent being used by the HTTP Requestor to get the credentials associated with the Subject and then using the credentials to authenticate that the IdentityProvider knows the Subject. In case of SSL/TLS based communication the credetials are acquired without any user intervention directly from the User Agent. The figure assumes that the IdentityProvider is able to authenticate the Subject.

4059 4060 4061

1.2.2

The IdentityProvider sends a <sampl:Response> message containing a <saml:AuthenticationStatement> to the Registry using either HTTP POST or HTTP Artifact SAML Binding via the User Agent.

4062 4063 4064 4065

1.2.2.1

The Registry uses implementation specific means to establish a security context for the Subject authenticated by the IdentityProvider based upon the information contained about the Subject in the <samlp:Response> message. This may include creating an HTTP Session for the HTTP Requestor.

4066 4067

1.2.2.2

The Registry maps the information about the Subject in the <samlp:Response> message into a <rim:User> instance. This establishes the <rim:User>context for the security context.

4068 4069 4070 4071

1.2.2.3

The Registry then performs authorization decision based upon the original HTTP request and the <rim:User>. The figure assumes that authorization decision was to allow the request to be processed. The Registry processes the request and subsequently return the requested resource to the HTTP Requestor via the HTTP response.

4072 4073

11.6.3

SSO Operation – Authenticated HTTP Requestor

4074 4075

This is the case where the HTTP Requestor first authenticates with an IdentityProvider and then accesses the registry over HTTP via a User Agent such as a Web Browser.

4076 4077 4078 4079

Currently there are no standard means defined for carrying SAML Assertions resulting from the Registry Requestor authenticating with an IdentityProvider over HTTP protocol to a Service Provider such as the registry. A registry MAY support this scenario in an implementation specific manner. Typically, the Identity Provider will define any such implementation specific manner.

4080

11.6.4

4081

This is the case where an unauthenticated Registry Requestor accesses the registry over SOAP.

4082

Figure 29 shows the steps involved.

SSO Operation – Unuthenticated SOAP Requestor

May 2, 2005 Page 116 of 133

4083 4084



Figure 29: SSO Operation - Unauthenticated SOAP Requestor

4085

11.6.4.1

Scenario Sequence

4086

Figure 29 shows the following sequence of steps for the operation:

4087 4088 4089 4090

4091 4092

1.1

The Registry checks to see if it already has a security context established for the Subject associated with the request. It determines that there is no pre-existing security context.

4093 4094 4095 4096

1.2

Because the request is from an ECP client, the registry uses the ECP Profile defined by [SAMLProf] and sends a <samlp:AuthnRequest> SOAP message as response to the <rs:RegistryRequest> SOAP message to the SOAP Requestor using the PAOS Binding as defined by [SAMLBind]. The response has an HTTP Response status of OK.

4097 4098 4099

1.2.1

The SOAP Requestor then initiates the <samlp:AuthnRequest> protocol with the IdentityProvider. The <sampl:AuthnRequest> is sent using HTTP POST or Artifact Binding directly to the IdentityProvider.

4100 4101 4102 4103 4104 4105

1.2.1.1

The IdentityProvider uses implementation specific means to identify the Subject. Typically this requires communicating with the SOAP Requestor to get the credentials associated with the Subject and then using the credentials to authenticate that the IdentityProvider knows the Subject. In case of SSL/TLS based communication the credetials are acquired without any user intervention directly from the SOAP Requestor. The figure assumes that the IdentityProvider is able to authenticate the Subject.

4106 4107

1.2.1.2

The IdentityProvider sends a <sampl:Response> message containing a <saml:AuthenticationStatement> to the SOAP Requestor using SAML SOAP Binding. The

The SOAP Requestor sends a <rs:RegistryRequest> SOAP message such as a <lcm:SubmitObjectsRequest> to a Registry interface such as the LifeCycleManagerManager. In the request header the SOAP Requestor declares that it is an ECP requestor as defined by the ECP Profile in [SAMLProf].

May 2, 2005 Page 117 of 133

HTTP header specifies the Registry as the ultimate target of the response.

4108 4109 4110

1.2.1.2.1

The SOAP Requestor forwards the <sampl:Response> message containing a <saml:AuthenticationStatement> to the Registry using PAOS Binding via HTTP POST.

4111 4112 4113 4114

1.2.1.2.1.1

4115 4116 4117

1.2.1.2.1.2

The Registry maps the information about the Subject in the <samlp:Response> message into a <rim:User> instance. This establishes the <rim:User>context for the security context.

4118 4119 4120 4121 4122

1.2.1.2.1.3

The Registry then performs authorization decision based upon the original SOAP request and the <rim:User>. The figure assumes that authorization decision was to allow the request to be processed. The Registry processes the request and subsequently return a <rs:RegistryResponse> SOAP message as response to the original <rs:RegistryRequest> SOAP request.

4124

11.6.5

SSO Operation – Authenticated SOAP Requestor

4125 4126

This is the case where the Registry Requestor first authenticates with an IdentityProvider directly and then makes a request to the registry using SOAP.

4123

May 2, 2005 Page 118 of 133

4127 4128

Figure 30: SSO Operation - Authenticated SOAP Requestor

4129

11.6.5.1

Scenario Sequence

4130

The figure shows the following sequence of steps for the operation:

4131 4132

4133 4134 4135 4136 4137 4138

1.1

4139 4140 4141

1.2

The IdentityProvider sends a <sampl:Response> message containing a <saml:AuthenticationStatement> to the SOAP Requestor using SAML HTTP POST or HTTP Artifact Binding.

4142 4143

The SOAP Requestor sends a <rs:RegistryRequest> SOAP message such as a <lcm:SubmitObjectsRequest> to a Registry interface such as the LifeCycleManagerManager. The

The SOAP Requestor then initiates the <samlp:AuthnRequest> protocol directly with the IdentityProvider. The <sampl:AuthnRequest> is sent using HTTP POST or Artifact Binding.

May 2, 2005 Page 119 of 133

<rs:RegistryRequest> SOAP message includes SAML Tokens in the <soap:Header> of the SOAP message as defined by [WSS-SAML]. The SAML Tokens are based upon the <sampl:Response> during authentication.

4144 4145 4146 4147 4148

2.1

The registry maps the SAML Tokens from the <soap:Header> of the <rs:RegistryRequest> to a <rim:User> instance. This establishes the <rim:User> context for the request.

4149 4150 4151 4152 4153

2.2

4154 4155

11.6.6

<samlp:AuthnRequest> Generation Rules

4156 4157

The following rules MUST be observed when the registry or Registry Client issues a <samlp:AuthnRequest>:

4158 4159

•

A registry MUST specify a NameIDPolicy within the <samlp:AuthRequest>

4160 4161 4162

•

The Format of the NameIDPolicy MUST be urn:oasis:names:tc:SAML:2.0:nameidformat:persistent as defined by section in [SAMLCore]. Note that it is the Persistent Identifier that maps to the id attribute of <rim:User>.

4163

−

4164

11.6.7

4165

This section describes how the registry processes the <sampl:Response> to a <sampl:AuthnRequest>:

4166

<samlp:Response> Processing

<samlp:Response> Processing Rules

4167 4168

•

Response Processing: The registry MUST verify the <ds:Signature> for the <sampl:Response> if present.

4169 4170 4171

•

The registry MUST check the <samlp:Status> associated with <sampl:Response> for errors. If the <samlp:Status> has a top level <samlp:StatusCode> whose value is NOT urn:oasis:names:tc:SAML:2.0:status:Success then the registry MUST throw an AuthenticationException. The AuthenticationException message SHOULD include the information from the StatusCode, StatusMessage and StatusDetail from the <samlp:Status>.

4172 4173 4174 4175 4176 4177 4178 4179 4180

<saml:Assertion> Processing •

The registry SHOULD check the <saml:Assertion> for Conditions and honour any standard Conditions defined by [SAMLCore] if any are specified.

<saml:AuthnStatement> Processing •

The registry MUST check the SessionNotOnOrAfter attribute of the <saml:AuthnStatement> for validity of the authenticated session.

<saml:Subject> Processing

4181

•

4182

11.6.8

4183 4184 4185 4186

As required by [SAMLCore] a <samlp:Response> to a <samlp:AuthnRequest> MUST contain a <saml:Subject> that identifies the Subject that was authenticated by the IdentityProvider. In addition it MUST contain a <sampl:AuthnStatement> which asserts that the IdentityProvider indeed authenticated the Subject.

A registry MUST map the <saml:Subject> to a <rim:User> instance as described in 11.6.8.

Mapping Subject to User

May 2, 2005 Page 120 of 133

4187

The following table defines the mapping between a <saml:Subject> and a <rim:User>:

4188

− Subject Attribute − NameID content

− User Attribute

− Description

4189

NameID Format MUST be “urn:oasis:names:tc:SAML:1.1:nameidformat:persistent” Table 8: Mapping Subject to User

4190 4191 4192

Note that any attribute of Subject not specified above SHOULD be ignored when mapping Subject to User. Note that any attribute of User not specified above MUST be left unspecified when mapping Subject to User.

4193

11.7

4194 4195 4196

The SAML Profile allows registry Users to be registered in an Identity Provider external to the registry. These are referred to as “External Users”. A registry dynamically creates such External Users by mapping a SAML Subject to a User instance dynamically.

4197

The following are some restrictions on External User instances:

− id attribute

External Users

4198 4199

•

External User instances are transient from the registry’s perspective and MUST not be stored within the registry as User instances

4200 4201 4202

•

A RegistryObject MUST not have a reference to an External User unless it is composed within that RegistryObject. Composed RegistryObjects such as Classification instances are allowed to reference their parent External User instance.

4203

•

Since External User instances are transient they MUST not match a registry Query.

4204 4205 4206 4207 4208

May 2, 2005 Page 121 of 133

4209

Native Language Support (NLS)

4210

This chapter describes the Native Languages Support (NLS) features of ebXML Registry.

4211

12.1

4212

The following terms are used in NLS.

Terminology NLS Term

Description

Coded Character Set (CCS)

CCS is a mapping from a set of abstract characters to a set of integers. [RFC 2130]. Examples of CCS are ISO-10646, US-ASCII, ISO8859-1, and so on.

Character Encoding Scheme (CES)

CES is a mapping from a CCS (or several) to a set of octets. [RFC 2130]. Examples of CES are ISO2022, UTF-8.

Character Set (charset)

•

charset is a set of rules for mapping from a sequence of octets to a sequence of characters.[RFC 2277],[RFC 2278]. Examples of character set are ISO-2022JP, EUC-KR. A list of registered character sets can be found at [IANA].

4213 4214

12.2

NLS and Registry Protcol Messages

4215 4216

For the accurate processing of data in both registry client and registry services, it is essential for the recipient of a protocol message to know the character set being used by it.

4217 4218 4219

A Registry Client SHOULD specify charset parameter in MIME header when they specify text/xml as Content-Type. A registry MUST specify charset parameter in MIME header when they specify text/xml as Content-Type.

4220 4221 4222 4223

The following is an example of specifying the character set in the MIME header. Content-Type: text/xml; charset=ISO-2022-JP

4224 4225 4226

If a registry receives a protocol message with the charset parameter omitted then it MUST use the default charset value of "us-ascii" as defined in [RFC 3023].

4227 4228 4229

Also, when an application/xml entity is used, the charset parameter is optional, and registry client and registry services MUST follow the requirements in Section 4.3.3 of [REC-XML] which directly address this contingency.

4230

If another Content-Type is used, then usage of charset MUST follow [RFC 3023].

4231

12.3

4232 4233

The information model XML Schema [RR-RIM-XSD] defines the <rim:InternationalStringType> for defining elements that contains a locale senstive string value.

NLS Support in RegistryObjects

4234 4235 4236

May 2, 2005 Page 122 of 133

4237 4238 4239

4240 4241 4242 4243 4244 4245 4246 4247 4248

An InternationalStringType may contain zero or more LocalizedStrings within it where each LocalizedString contain a string value is a specified local language and character set. <complexType name="LocalizedStringType"> <attribute ref="xml:lang" default="en-US"/> <attribute default="UTF-8" name="charset"/> <attribute name="value" type="tns:FreeFormText" use="required"/> </complexType>

4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269

Examples of such attributes are the “name” and “description” attributes of the RegistryObject class defined by [ebRIM] as shown below. <complexType name="InternationalStringType"> <sequence maxOccurs="unbounded" minOccurs="0"> <element ref="tns:LocalizedString"/> </sequence> </complexType> <element name="InternationalString" type="tns:InternationalStringType"/> <element name="Name" type="tns:InternationalStringType"/> <element name="Description" type="tns:InternationalStringType"/> <complexType name="LocalizedStringType"> <attribute ref="xml:lang" default="en-US"/>  <attribute default="UTF-8" name="charset"/> <attribute name="value" type="tns:FreeFormText" use="required"/> </complexType> <element name="LocalizedString" type="tns:LocalizedStringType"/>

4270 4271 4272

An element InternationalString is capable of supporting multiple locales within its collection of LocalizedStrings.

4273 4274

The above schema allows a single RegistryObject instance to include values for any NLS sensitive element in multiple locales.

4275 4276 4277

The following example illustrates how a single RegistryObject can contain NLS sesnitive <rim:Name> and “<rim:Description> elements with their value specified in multiple locales. Note that the <rim:Name> and <rim:Description> use the <rim:InternationalStringType> as their type.

4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292

<rim:ExtrinsicObject id="${ID}" mimeType="text/xml"> <rim:Name> <rim:LocalizedString xml:lang="en-US" value="customACP1.xml"/> <rim:LocalizedString xml:lang="fi-FI" value="customACP1.xml"/> <rim:LocalizedString xml:lang="pt-BR" value="customACP1.xml"/> </rim:Name> <rim:Description> <rim:LocalizedString xml:lang="en-US" value="A sample custom ACP"/> <rim:LocalizedString xml:lang="fi-FI" value="Esimerkki custom ACP"/> <rim:LocalizedString xml:lang="pt-BR" value="Exemplo de ACP customizado "/> </rim:Description> regrep-rs-3.0-os Copyright © OASIS Open 2005. All Rights Reserved.

May 2, 2005 Page 123 of 133

</rim:ExtrinsicObject>

4293 4294 4295 4296

Since locale information is specified at the sub-element level there is no language or character set associated with a specific RegistryObject instance.

4297

12.3.1

4298 4299 4300

The character set used by a locale specific String (LocalizedString) is defined by the charset attribute. Registry Clients SHOULD specify UTF-8 or UTF-16 as the value of the charset attribute of LocalizedStrings for maximum interoperability.

4301

12.3.2

4302

The language MAY be specified in xml:lang attribute (Section 2.12 [REC-XML]).

4303

12.4

4304 4305 4306

While a single instance of an ExtrinsicObject is capable of supporting multiple locales, it is always associated with a single repository item. The repository item MAY be in a single locale or MAY be in multiple locales. This specification does not specify any NLS requirements for repository items.

4307

12.4.1

4308 4309 4310

When a submitter submits a repository item, they MAY specify the character set used by the respository item using the MIME Content-Type mime header for the mime multipart containing the repository item as shown below:

4311 4312

Character Set of LocalizedString

Language of LocalizedString

NLS and Repository Items

Character Set of Repository Items

Content-Type: text/xml; charset="UTF-8"

4313 4314 4315 4316 4317

Registry Clients SHOULD specify UTF-8 or UTF-16 as the value of the charset attribute of LocalizedStrings for maximum interoperability. A registry MUST preserve the charset of a repository item as it is originally specified when it is submitted to the registry.

4318

12.4.2

4319 4320 4321

The Content-language mime header for the mime bodypart containing the repository item MAY specify the language for a locale specific repository item. The value of the Content-language mime header property MUST conform to [RFC 1766].

4322 4323 4324 4325 4326

This document currently specifies only the method of sending the information of character set and language, and how it is stored in a registry. However, the language information MAY be used as one of the query criteria, such as retrieving only DTD written in French. Furthermore, a language negotiation procedure, like registry client is asking a favorite language for messages from registry services, could be another functionality for the future revision of this document.

Language of Repository Items

May 2, 2005 Page 124 of 133

4327

4328 4329

This chapter defines the technical conformance requirements for ebXML Registry. Note that it does not define specific conformance tests to verify compliance with various conformance profiles.

4330

13.1

4331

An ebXML Registry MUST comply with one of the following conformance profiles:

4332 4333 4334 4335

Conformance Conformance Profiles

• Registry Lite – This conformance profile requires the regsitry to implement a minimal set of core features defined by this specification. • Registry Full – This conformance profile requires the registry to implement additional set of features in addition to those required by the Registry Lite conformance profile.

4336

13.2

Feature Matrix

4337 4338

The following table identifies the implementation requirements for each feature defined by this specification for each conformance profile defined above.

May 2, 2005 Page 125 of 133

Table 9: Feature Conformance Matrix

May 2, 2005 Page 126 of 133

Feature

Registry Lite

Registry Full

SOAP Binding QueryManager binding

MUST

LifeCycleManager binding

MUST

RPC Encoded URL

MUST

User Defined URL

MAY

MUST

File Path URL

MAY

MUST

SubmitObjects Protocol

MUST

UpdateObjects Protocol

MUST

ApproveObjects Protocol

MUST

DeprecateObjects Protocol

MUST

UnderprecateObjects Protocol

MUST

RemoveObjects Protocol

MUST

Registry Managed Version Control

MAY

MUST

SQL Query

MAY

MUST

Filter Query

MUST

Stored Parameterized Query

MAY

MUST

Iterative Query

MAY

MUST

MAY

MUST

Validate Content Protocol

MAY

MUST

Catalog Content Protocol

MAY

MUST

Canonical XML Cataloging Service

MAY

MUST

Remote object references

MAY

MUST

Federated queries

MAY

MUST

Object Replication

MAY

MUST

Object Relocation

MAY

MUST

Transport layer security

MAY

MUST

SOAP Message Security

MUST

Default Access Control Policy

MUST

Custom Access Control Policies

MAY

MUST

HTTP Binding

LifeCycleManager

QueryManager

Event Notification Content Management Services

Cooperating Registries

Registry Security Identity Management Message Security

Repository Item Security Authorization and Access Control

May 2, 2005 Page 127 of 133

Feature

Registry Lite

Registry Full

Registry SAML Profile

MAY

MUST

NLS

MUST

4339

May 2, 2005 Page 128 of 133

4340

References

4341

14.1

Normative References

4342 4343

[RFC2119]

4344

[ebRIM]

4345 4346 4347

[REC-XML]

4348 4349

[RFC 1766]

4350 4351 4352

[RFC 2130]

4353 4354 4355 4356

[RFC 2277]

4357 4358 4359

[RFC 2278]

4360 4361 4362

[RFC2616]

4363 4364 4365

[RFC2965]

4366 4367 4368

[RR-CMS-XSD]

4369 4370

[RR-LCM-XSD]

4371 4372

[RR-RIM-XSD]

4373 4374

[RR-RS-XSD]

4375 4376

[RR-QM-XSD]

4377 4378 4379 4380 4381

[SAMLBind]

4382 4383 4384 4385 4386 4387

[SAMLConform]

S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, IETF RFC 2119, March 1997, http://www.ietf.org/rfc/rfc2119.txt. ebXML Registry Information Model Version 3.0 http://www.oasis-open.org/committees/regrep/documents/3.0/specs/regrep-rim3.0-cs-01.pdf W3C Recommendation. Extensible Markup language(XML)1.0(Second Edition) http://www.w3.org/TR/REC-xml IETF (Internet Engineering Task Force). RFC 1766: Tags for the Identification of Languages, ed. H. Alvestrand. 1995. http://www.cis.ohio-state.edu/htbin/rfc/rfc1766.html IETF (Internet Engineering Task Force). RFC 2130 The Report of the IAB Character Set Workshop held 29 February - 1 March, 1996 http://www.faqs.org/rfcs/rfc2130.html IETF (Internet Engineering Task Force). RFC 2277: IETF policy on character sets and languages, ed. H. Alvestrand. 1998. http://www.cis.ohio-state.edu/htbin/rfc/rfc2277.html IETF (Internet Engineering Task Force). RFC 2278: IANA Charset Registration Procedures, ed. N. Freed and J. Postel. 1998. http://www.cis.ohio-state.edu/htbin/rfc/rfc2278.html IETF (Internet Engineering Task Force). RFC 2616: Fielding et al. Hypertext Transfer Protocol -- HTTP/1.1 . 1999. http://www.w3.org/Protocols/rfc2616/rfc2616.html IETF (Internet Engineering Task Force). RFC 2965: D. Kristol et al. HTTP State Management Mechanism. 2000. http://www.w3.org/Protocols/rfc2616/rfc2616.html ebXML Registry Content Management Services XML Schema http://www.oasis-open.org/committees/regrep/documents/3.0/schema/rim.xsd ebXML Registry LifeCycleManager XML Schema http://www.oasis-open.org/committees/regrep/documents/3.0/schema/lcm.xsd ebXML Registry Information Model XML Schema http://www.oasis-open.org/committees/regrep/documents/3.0/schema/rim.xsd ebXML Registry Service Protocol XML Schema http://www.oasis-open.org/committees/regrep/documents/3.0/schema/rs.xsd ebXML Registry QueryManager XML Schema http://www.oasisopen.org/committees/regrep/documents/3.0/schema/query.xsd S. Cantor et al., Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, September 2004. Document ID sstc-samlbindings-2.0-cd-03. http://www.oasis-open.org/committees/security/. Note: when this document is finalized, this URL will be updated. P. Mishra et al. Conformance Requirements for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, September 2004. Document ID sstc-saml-conformance-2.0-cd-03. http://www.oasis-open.org/committees/security/.

May 2, 2005 Page 129 of 133

4388 4389 4390 4391 4392

[SAMLCore]

4393 4394 4395 4396

[SAMLProf]

4397 4398 4399 4400

[SAMLP-XSD]

4401 4402 4403 4404

[SAML-XSD]

4405 4406 4407 4408

[SOAP11]

4409

[SwA]

4410 4411

[SQL]

4412 4413

[SQL/PSM]

4414 4415

[UUID]

4416 4417

[WSDL]

4418 4419 4420

[XML]

4421 4422

[XMLDSIG]

4423 4424

[WSI-BSP]

4425 4426 4427

[WSS-SMS]

4428 4429 4430

[WSS-SWA]

4431 4432 4433 4434 4435 4436

14.2

Note: when this document is finalized, this URL will be updated. S. Cantor et al., Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, December 2004. Document ID sstc-saml-core-2.0-cd-03. http://www.oasis-open.org/committees/security/. Note: when this document is finalized, this URL will be updated. S. Cantor et al., Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, September 2004. Document ID sstc-saml-profiles2.0-cd-03. http://www.oasis-open.org/committees/security/. Note: when this document is finalized, this URL will be updated. S. Cantor et al., SAML protocols schema. OASIS SSTC, September 2004. Document ID sstc-saml-schema-protocol-2.0. http://www.oasis-open.org/committees/security/. Note: when this document is finalized, this URL will be updated. S. Cantor et al., SAML assertions schema. OASIS SSTC, September 2004. Document ID sstc-saml-schema-assertion-2.0. http://www.oasis-open.org/committees/security/. Note: when this document is finalized, this URL will be updated. W3C Note. Simple Object Access Protocol, May 2000 http://www.w3.org/TR/SOAP W3C Note: SOAP with Attachments, Dec 2000 http://www.w3.org/TR/SOAP-attachments Structured Query Language (FIPS PUB 127-2) http://www.itl.nist.gov/fipspubs/fip127-2.htm Database Language SQL — Part 4: Persistent Stored Modules (SQL/PSM) [ISO/IEC 9075-4:1996] DCE 128 bit Universal Unique Identifier http://www.opengroup.org/onlinepubs/009629399/apdxa.htm#tagcjh_20 W3C Note. Web Services Description Language (WSDL) 1.1 http://www.w3.org/TR/wsdl T. Bray, et al. Extensible Markup Language (XML) 1.0 (Second Edition). World Wide Web Consortium, October 2000. http://www.w3.org/TR/REC-xml XML-Signature Syntax and Processing http://www.w3.org/TR/2001/PR-xmldsig-core-20010820/ WS-I: Basic Security Profile 1.0 http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0-2004-05-12.html Note: when this document is finalized, this URL will be updated. Web Services Security: SOAP Message Security 1.0 http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-messagesecurity-1.0.pdf Web Services Security: SOAP Message with Attachments (SwA) Profile 1.0 http://www.oasis-open.org/apps/org/workgroup/wss/download.php/10902/wssswa-profile-1.0-cd-01.pdf Note: when this document is finalized, this URL will be updated.

Informative

[ebBPSS]

ebXML Business Process Specification Schema http://www.ebxml.org/specs

May 2, 2005 Page 130 of 133

4437

[ebCPP]

4438 4439

[ebMS]

4440 4441

[DeltaV]

4442 4443

[XPT]

4444 4445

[IANA]

4446 4447 4448 4449

[RFC2392]

4450 4451

[RFC 2828]

4452 4453 4454

[RFC 3023]

4455 4456 4457 4458 4459

[SAMLMeta]

4460 4461 4462 4463

[SAMLGloss]

4464 4465 4466 4467

[SAMLSecure]

4468 4469

[SAMLTech ]

4470 4471 4472 4473 4474 4475

[UML]

ebXML Collaboration-Protocol Profile and Agreement Specification http://www.ebxml.org/specs/ ebXML Messaging Service Specification, Version 1.0 http://www.ebxml.org/specs/ Versioning Extension to WebDAV, IETF RFC 3253 http://www.webdav.org/deltav/protocol/rfc3253.html XML Path Language (XPath) Version 1.0 http://www.w3.org/TR/xpath IANA (Internet Assigned Numbers Authority). Official Names for Character Sets, ed. Keld Simonsen et al. http://www.iana.org/ E. Levinson, Content-ID and Message-ID Uniform Resource Locators, IETF RFC 2392, http://www.ietf.org/rfc/rfc2392.txt IETF (Internet Engineering Task Force). RFC 2828: Internet Security Glossary, ed. R. Shirey. May 2000. http://www.cis.ohio-state.edu/htbin/rfc/rfc2828.html IETF (Internet Engineering Task Force). RFC 3023: XML Media Types, ed. M. Murata. 2001. ftp://ftp.isi.edu/in-notes/rfc3023.txt S. Cantor et al., Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, September 2004. Document ID sstc-samlmetadata-2.0-cd-02. http://www.oasis-open.org/committees/security/. J. Hodges et al., Glossary for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, September 2004. Document ID sstc-samlglossary-2.0-cd-02. http://www.oasis-open.org/committees/security/. F. Hirsch et al., Security and Privacy Considerations for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, September 2004. Document ID sstc-saml-sec-consider-2.0-cd-02. http://www.oasis-open.org/committees/security/. J.Hughes et al.,Technical Overview of the OASIS Security Assertion Markup Language (SAML)V2.0. http://www.oasis-open.org/committees/download.php/7874/sstc-saml-techoverview-2.0-draft-01.pdf Unified Modeling Language http://www.uml.org http://www.omg.org/cgi-bin/doc?formal/03-03-01

4476

May 2, 2005 Page 131 of 133

4477

A. Acknowledgments

4478 4479 4480

The editors would like to acknowledge the contributions of the OASIS ebXML Registry Technical Committee, whose voting members at the time of publication are listed as contributors on the title page of this document.

4481 4482

•

Finally, the editors wish to acknowledge the following people for their contributions of material used as input to the OASIS ebXML Registry specifications:

4483

Name Aziz Abouelfoutouh Ed Buchinski Asuman Dogac Michael Kass Richard Lessard Evan Wallace David Webber 4484

Affiliation Government of Canada Government of Canada Middle East Technical University, Ankara Turkey NIST Government of Canada NIST Individual

•

May 2, 2005 Page 132 of 133

4485

B. Notices

4486 4487 4488 4489 4490 4491 4492 4493

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification, can be obtained from the OASIS Executive Director.

4494 4495 4496

OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.

4497

4498 4499 4500 4501 4502 4503 4504 4505

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself does not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.

4506 4507

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

4508 4509 4510 4511 4512

This document and the information contained herein is provided on an “AS IS” basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

May 2, 2005 Page 133 of 133

ebXML Registry Services and Protocols v3.0 (2005-05-01)

Related documents