| 591 | | Yada yada ... |
| 592 | | |
| 593 | | |
| 594 | | == Appendix: Non-normative |
| | 597 | The ''searchRetrieve'' operation of the SRU protocol is used for searching in the Resources that are provided by an Endpoint. The SRU protocol defines request and response formats in [#REF_SRU_12 OASIS-SRU-12]. Search result hits are encoded down to a record level, i.e. the `<sru:record>` element, and SRU allows records to be serialized in various formats, so called ''record schemas''. Endpoints `MUST` support the CLARIN-FCS record schema (see [#resultFormat above]). The ''responseItemType'' ("record schema identifier") that `MUST` be used for that for that schema is `http://clarin.eu/fcs/1.0`. |
| | 598 | |
| | 599 | In CLARIN-FCS, each record, i.e. `<sru:record>` element, `MUST` represent exactly ''one hit'' within the Resource. to belong in within the resource fragment. |
| | 600 | |
| | 601 | The following example shows a request and response to an ''searchRetrieve'' request with a ''term-only'' query for "cat": |
| | 602 | * HTTP GET request: Client -> Endpoint: |
| | 603 | {{{#!sh |
| | 604 | http://repos.example.org/fcs-endpoint?operation=searchRetrieve&version=1.2&query=cat |
| | 605 | }}} |
| | 606 | * HTTP Response: Endpoint -> Client |
| | 607 | {{{#!xml |
| | 608 | <?xml version='1.0' encoding='utf-8'?> |
| | 609 | <sru:searchRetrieveResponse xmlns:sru="http://www.loc.gov/zing/srw/"> |
| | 610 | <sru:version>1.2</sru:version> |
| | 611 | <sru:numberOfRecords>6</sru:numberOfRecords> |
| | 612 | <sru:records> |
| | 613 | <sru:record> |
| | 614 | <sru:recordSchema>http://clarin.eu/fcs/1.0</sru:recordSchema> |
| | 615 | <sru:recordPacking>xml</sru:recordPacking> |
| | 616 | <sru:recordData> |
| | 617 | <fcs:Resource xmlns:fcs="http://clarin.eu/fcs/1.0" pid="http://hdl.handle.net/4711/08-15"> |
| | 618 | <fcs:ResourceFragment> |
| | 619 | <fcs:DataView type="application/x-clarin-fcs-hits+xml"> |
| | 620 | <hits:Result xmlns:hits="http://clarin.eu/fcs/1.0/hits"> |
| | 621 | The quick brown <hits:Hit>cat</hits:Hit> jumps over the lazy dog. |
| | 622 | </hits:Result> |
| | 623 | </fcs:DataView> |
| | 624 | </fcs:ResourceFragment> |
| | 625 | </fcs:Resource> |
| | 626 | </sru:recordData> |
| | 627 | <sru:recordPosition>1</sru:recordPosition> |
| | 628 | </sru:record> |
| | 629 | <!-- more <sru:records> omitted for brevity --> |
| | 630 | </sru:records> |
| | 631 | <sru:echoedSearchRetrieveRequest> |
| | 632 | <sru:version>1.2</sru:version> |
| | 633 | <sru:query>cat</sru:query> |
| | 634 | <sru:xQuery xmlns="http://www.loc.gov/zing/cql/xcql/"> |
| | 635 | <searchClause> |
| | 636 | <index>cql.serverChoice</index> |
| | 637 | <relation> |
| | 638 | <value>=</value> |
| | 639 | </relation> |
| | 640 | <term>cat</term> |
| | 641 | </searchClause> |
| | 642 | </sru:xQuery> |
| | 643 | <sru:startRecord>1</sru:startRecord> |
| | 644 | <sru:baseUrl>http://repos.example.org/fcs-endpoint</sru:baseUrl> |
| | 645 | </sru:echoedSearchRetrieveRequest> |
| | 646 | </sru:searchRetrieveResponse> |
| | 647 | }}} |
| | 648 | |
| | 649 | In general, the Endpoint is `REQUIRED` to accept an unrestricted search and `MUST` then perform the search operation on all Resources at an Endpoint. The Client can request the Endpoint to ''restrict the search'' to a sub-collection of the Resources available. In this case, the Client `MUST` pass a comma-separated list of persistent identifiers in the {{{x-clarin-fcs-context}}} extra request parameter of the ''searchRetrieve'' request. The Endpoint `MUST` then restrict the search to those Resources, that are identified by the persistent identifiers passed by Client. A Client can extract all valid persistent identifiers from the `@pid` attribute of the `<ed:Collection>` element, obtained by the ''explain'' request (see section [#explain Operation ''explain''] and section [#endpointDescription Endpoint Description]). The list of persistent identifiers can get extensive, but an agent `MAY` use the POST method instead of GET method for submitting the request. |
| | 650 | |
| | 651 | For example, to restrict the search to the Resource with the persistent identifier `http://hdl.handle.net/4711/0815` the Client must issue the following request: |
| | 652 | {{{#!sh |
| | 653 | http://repos.example.org/fcs-endpoint?operation=searchRetrieve&version=1.2&query=cat&x-clarin-fcs-context=http://hdl.handle.net/4711/0815 |
| | 654 | }}} |
| | 655 | To restrict the search to the Resources with the persistent identifier `http://hdl.handle.net/4711/0815` and `http://hdl.handle.net/4711/0816-2` the Client must issue the following request: |
| | 656 | {{{#!sh |
| | 657 | http://repos.example.org/fcs-endpoint?operation=searchRetrieve&version=1.2&query=cat&x-clarin-fcs-context=http://hdl.handle.net/4711/0815,http://hdl.handle.net/4711/0816-2 |
| | 658 | }}} |
| | 659 | |
| | 660 | If an invalid persistent identifier is passed by a Client, the Endpoint `MUST` issue a `http://clarin.eu/fcs/1.0/diagnostic/1` diagnostic, i.e add the appropiate XML fragment to the `<sru:diagnostics>` element of the response. The Endpoint `MAY` treat this condition as fatal, i.e. just issue the diagnostic and perform no search or it `MAY` treat it a non-fatal and perform the search. |
| | 661 | |
| | 662 | |
| | 663 | == Normative Appendix |
| | 664 | === List of extra request parameters === |
| | 665 | The following extra request parameters are used in CLARIN-FCS: |
| | 666 | ||=Parameter Name =||=SRU operations =||=Allowed values =||= Description =|| |
| | 667 | || `x-clarin-fcs-endpoint-description` || explain || `true` \\ All other values are reserved an `MUST` not be used by Clients || If present, the Endpoint `MUST` include a Endpoint Description in the\\`<sru:extraResponseData>` element of an ''explain'' response. || |
| | 668 | || `x-clarin-fcs-context` || searchRetrieve || A comma separated list of persistent identifiers || The Endpoint `MUST` restrict the search to the collections identified by\\the persistent identifiers || |
| | 669 | |
| | 670 | === List of diagnoistics === |
| | 671 | Apart from the SRU diagnostics defined in [#REF_SRU_12 OASIS-SRU-12, Appendix C] and LOC-DIAG[=#REF_LOC_DIAG], the following diagnostics are used in CLARIN-FCS. The "Details Format" column specifies what `SHOULD` be returned in the details field. If this column is blank, the format is "undefined" and the Endpoint `MAY` return whatever it feels appropriate, including nothing. |
| | 672 | ||=Identifier URI =||=Description =||= Details Format =|| |
| | 673 | || `http://clarin.eu/fcs/1.0/diagnostic/1` || Persistent identifier passed in for restricting the search is invalid || The offending persistent identifier || |
| | 674 | |
| | 675 | == Non-normative Appendix |
