126 | | The following sections describe the profiles, how SRU/CQL is used in the context of CLARIN-FCS and the CLARIN-FCS specific extensions to SRU. |
| 126 | Generally, CLARIN-FCS Interface Specification consists of two components, a set of ''formats'' and a ''transport protocol''. The ''Endpoint'' component is a software component that acts as a bridge between the Formats, that are send by a ''Client'' using the ''Transport Protocol'', and a ''Search Engine''. The ''Search Engine'' is a custom software component, that allows searching in the language resources of a CLARIN center. The ''Endpoint'' basically implements the ''transport protocol'' and acts as an mediator between the CLRAIN-FCS speceific formats and the idiosyncrasies of ''Search Engines''. The following figure illustrates the overall architecture. |
| 127 | {{{ |
| 128 | +---------+ |
| 129 | | Client | |
| 130 | +---------+ |
| 131 | /|\ |
| 132 | | |
| 133 | ------------------------- |
| 134 | | SRU / CQL | |
| 135 | | w/CLARIN-FCS extensions | |
| 136 | ------------------------- |
| 137 | | |
| 138 | \|/ |
| 139 | +-----------------------------------------+ |
| 140 | | | Endpoint /|\ | |
| 141 | | | | | |
| 142 | | --------------- ------------------ | |
| 143 | | | Translate CQL | | Translate Result | | |
| 144 | | --------------- ------------------ | |
| 145 | | | | | |
| 146 | | \|/ | | |
| 147 | +-----------------------------------------+ |
| 148 | /|\ |
| 149 | | |
| 150 | \|/ |
| 151 | +---------------------------+ |
| 152 | | Search Engine | |
| 153 | +---------------------------+ |
| 154 | }}} |
| 155 | |
| 156 | The following sections describe the CLARIN-FCS profiles and query and result formats, how SRU/CQL is used as a transport protocol in the context of CLARIN-FCS and the required CLARIN-FCS specific extensions to SRU. |
153 | | |
154 | | |
155 | | === SRU/CQL === |
156 | | SRU (!Search/Retrieve via URL) specifies a general communication protocol for searching and retrieving records and the CQL (Contextual Query Language) specifies a extensible query language. CLARIN-FCS is built on SRU 1.2. A subsequent specification may be built on SRU 2.0. |
157 | | |
158 | | Endpoints and Clients `MUST` implement the SRU/CQL protocol suite as defined in [#REF_SRU_Overview OASIS-SRU-Overview], [#REF_SRU_APD OASIS-SRU-APD], [#REF_CQL OASIS-CQL], [#REF_Explain SRU-Explain], [#REF_Scan SRU-Scan], especially with respect to: |
159 | | * Data Model, |
160 | | * Query Model, |
161 | | * Processing Model, |
162 | | * Result Set Model, and |
163 | | * Diagnostics Model |
164 | | |
165 | | Endpoints and Clients `MUST` use the implement the APD Binding for SRU 1.2, as defined in [#REF_SRU_12 OASIS-SRU-12]. Endpoints and Clients `MAY` implement APD binding for version 1.1 or version 2.0. |
166 | | |
167 | | Endpoints and Clients `MUST` use the following namespace URIs for serializing responses: |
168 | | * `http://www.loc.gov/zing/srw/` for SRU response documents, and |
169 | | * `http://www.loc.gov/zing/srw/diagnostic/` for diagnostics within SRU response documents. |
170 | | CLARIN-FCS deviates from the OASIS specification [#REF_SRU_Overview OASIS-SRU-Overview] and [#REF_SRU_12 OASIS-SRU-12] to ensure backwards comparability with SRU 1.2 services as they where defined by the [#REF_LOC_SRU_12 LOC-SRU12]. |
171 | | |
172 | | Endpoints or Clients `MUST` support CQL conformance ''Level 2'' (as defined in [#REF_OASIS_CQL OASIS-CQL, section 6]), i.e. be able to ''parse'' (Endpoints) or ''serialize'' (Clients) all of CQL and respond with appropriate error messages to the search/retrieve protocol interface. |
173 | | |
174 | | '''NOTE''': this does ''not imply'', that Endpoints are ''required'' support for all of CQL, but rather that they are able to ''parse'' all of CQL and generate the appropriate error message, if a query includes a feature they do not support. |
175 | | |
176 | | Endpoints `MUST` generate diagnostics according to [#REF_SRU_12 OASIS-SRU-12, Appendix C] for error conditions or to indicate unsupported features. Unfortunately, the OASIS specification does not provides a comprehensive list of diagnostics for CQL related errors. Therefore, Endpoints `MUST` use diagnostics from [#REF_LOC_DIAG LOC-DIAG, section "Diagnostics Relating to CQL"] for CQL related errors. |
| 270 | === SRU/CQL === |
| 271 | SRU (!Search/Retrieve via URL) specifies a general communication protocol for searching and retrieving records and the CQL (Contextual Query Language) specifies a extensible query language. CLARIN-FCS is built on SRU 1.2. A subsequent specification may be built on SRU 2.0. |
| 272 | |
| 273 | Endpoints and Clients `MUST` implement the SRU/CQL protocol suite as defined in [#REF_SRU_Overview OASIS-SRU-Overview], [#REF_SRU_APD OASIS-SRU-APD], [#REF_CQL OASIS-CQL], [#REF_Explain SRU-Explain], [#REF_Scan SRU-Scan], especially with respect to: |
| 274 | * Data Model, |
| 275 | * Query Model, |
| 276 | * Processing Model, |
| 277 | * Result Set Model, and |
| 278 | * Diagnostics Model |
| 279 | |
| 280 | Endpoints and Clients `MUST` use the implement the APD Binding for SRU 1.2, as defined in [#REF_SRU_12 OASIS-SRU-12]. Endpoints and Clients `MAY` implement APD binding for version 1.1 or version 2.0. |
| 281 | |
| 282 | Endpoints and Clients `MUST` use the following namespace URIs for serializing responses: |
| 283 | * `http://www.loc.gov/zing/srw/` for SRU response documents, and |
| 284 | * `http://www.loc.gov/zing/srw/diagnostic/` for diagnostics within SRU response documents. |
| 285 | CLARIN-FCS deviates from the OASIS specification [#REF_SRU_Overview OASIS-SRU-Overview] and [#REF_SRU_12 OASIS-SRU-12] to ensure backwards comparability with SRU 1.2 services as they where defined by the [#REF_LOC_SRU_12 LOC-SRU12]. |
| 286 | |
| 287 | Endpoints or Clients `MUST` support CQL conformance ''Level 2'' (as defined in [#REF_OASIS_CQL OASIS-CQL, section 6]), i.e. be able to ''parse'' (Endpoints) or ''serialize'' (Clients) all of CQL and respond with appropriate error messages to the search/retrieve protocol interface. |
| 288 | |
| 289 | '''NOTE''': this does ''not imply'', that Endpoints are ''required'' support for all of CQL, but rather that they are able to ''parse'' all of CQL and generate the appropriate error message, if a query includes a feature they do not support. |
| 290 | |
| 291 | Endpoints `MUST` generate diagnostics according to [#REF_SRU_12 OASIS-SRU-12, Appendix C] for error conditions or to indicate unsupported features. Unfortunately, the OASIS specification does not provides a comprehensive list of diagnostics for CQL related errors. Therefore, Endpoints `MUST` use diagnostics from [#REF_LOC_DIAG LOC-DIAG, section "Diagnostics Relating to CQL"] for CQL related errors. |
| 292 | |
| 293 | |