| 519 | | Yada yada ... |
| | 520 | The ''explain'' operation of SRU serves to announce server capabilities and to allows clients to configure themselves automatically. This operation is used similarly. |
| | 521 | |
| | 522 | An Endpoint `MUST` respond to a ''explain'' request by a proper ''explain'' response. As per [#REF_Explain SRU-Explain], the response `MUST` contain one `<sru:record>` element that contains an ''SRU Explain'' record. The `<sru:recordSchema>` element `MUST` contain the literal `http://explain.z3950.org/dtd/2.0/`, i.e. the official ''identifier'' for Explain records. |
| | 523 | |
| | 524 | According to the Profile supported by the Endpoint the Explain record `MUST` contain the following elements: |
| | 525 | ''Basic'' Profile:: |
| | 526 | `<zr:serverInfo>` as defined in [#REF_Explain SRU-Explain] (`REQUIRED`) \\ |
| | 527 | `<zr:databaseInfo>` as defined in [#REF_Explain SRU-Explain] (`REQUIRED`) \\ |
| | 528 | `<zr:schemaInfo>` as defined in [#REF_Explain SRU-Explain] (`REQUIRED`). This element `MUST` contain an element `<zr:schema>` with an `@identifier` attribute with a value of `http://clarin.eu/fcs/1.0` and an `@name` attribute with a value of `fcs`. \\ |
| | 529 | `<zr:configInfo>` is `OPTIONAL``\\ |
| | 530 | An ''extended'' profile may define how the `<zr:indexInfo>` element is to be used, therefore it `NOT RECOMMENDED` for Endpoints to define custom extensions. |
| | 531 | ''Extended'' Profile:: |
| | 532 | '''NOTE''': the extended profile is not yet defined and will be part of a future CLARIN-FCS specification. |
| | 533 | |
| | 534 | To support auto-configuration in CLARIN-FCS, an Endpoint provide an ''Endpoint Description''. The Endpoint Description is included in explain response utilizing SRUs extension mechanism, i.e. by embedding an XML fragment into the `<sru:extraResponseData>` element. Endpoints `MUST` include the Endpoint Description ''only'' if a Client performs an explain request with the ''extra request parameter'' `x-clarin-fcs-endpoint-description` with a value of `true`. If a Client performs an explain request ''without'' supplying this extra request parameter the Endpoint `MUST NOT` include |
| | 535 | the Endpoint Description. The format of the Endpoint Description XML fragment is defined in [#REF_endpointDescription Endpoint Description]. |
| | 536 | |
| | 537 | The following show a complete response to an explain request with added extra request parameter `x-clarin-fcs-endpoint-description`: |
| | 538 | {{{#!xml |
| | 539 | <sru:explainResponse xmlns:sru="http://www.loc.gov/zing/srw/"> |
| | 540 | <sru:version>1.2</sru:version> |
| | 541 | <sru:record> |
| | 542 | <sru:recordSchema>http://explain.z3950.org/dtd/2.0/</sru:recordSchema> |
| | 543 | <sru:recordPacking>xml</sru:recordPacking> |
| | 544 | <sru:recordData> |
| | 545 | <zr:explain xmlns:zr="http://explain.z3950.org/dtd/2.0/"> |
| | 546 | <!-- <zr:serverInfo > is REQUIRED --> |
| | 547 | <zr:serverInfo protocol="SRU" version="1.2" transport="http"> |
| | 548 | <zr:host>repos.example.org</zr:host> |
| | 549 | <zr:port>80</zr:port> |
| | 550 | <zr:database>sru</zr:database> |
| | 551 | </zr:serverInfo> |
| | 552 | <!-- <zr:databaseInfo> is REQUIRED --> |
| | 553 | <zr:databaseInfo> |
| | 554 | <zr:title lang="de">Goethe Corpus</zr:title> |
| | 555 | <zr:title lang="en" primary="true">Goethe Korpus</zr:title> |
| | 556 | <zr:description lang="de">Der Goethe Korpus des IDS Mannheim.</zr:description> |
| | 557 | <zr:description lang="en" primary="true">The Goethe corpus of IDS Mannheim.</zr:description> |
| | 558 | </zr:databaseInfo> |
| | 559 | <!-- <zr:configInfo> is REQUIRED --> |
| | 560 | <zr:schemaInfo> |
| | 561 | <zr:schema identifier="http://clarin.eu/fcs/1.0" name="fcs"> |
| | 562 | <zr:title lang="en" primary="true">CLARIN Federated Content Search</zr:title> |
| | 563 | </zr:schema> |
| | 564 | </zr:schemaInfo> |
| | 565 | <!-- <zr:configInfo> is OPTIONAL --> |
| | 566 | <zr:configInfo> |
| | 567 | <zr:default type="numberOfRecords">250</zr:default> |
| | 568 | <zr:setting type="maximumRecords">1000</zr:setting> |
| | 569 | </zr:configInfo> |
| | 570 | </zr:explain> |
| | 571 | </sru:recordData> |
| | 572 | </sru:record> |
| | 573 | <!-- <sru:echoedExplainRequest> is OPTIONAL --> |
| | 574 | <sru:echoedExplainRequest> |
| | 575 | <sru:version>1.2</sru:version> |
| | 576 | <sru:baseUrl>https://clarin.ids-mannheim.de/digibibsru</sru:baseUrl> |
| | 577 | </sru:echoedExplainRequest> |
| | 578 | <sru:extraResponseData> |
| | 579 | <ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/1.0/endpoint-description"> |
| | 580 | <ed:Profile>basic</ed:Profile> |
| | 581 | <ed:SupportedDataViews> |
| | 582 | <ed:SupportedDataView>application/x-clarin-fcs-hits+xml</ed:SupportedDataView> |
| | 583 | </ed:SupportedDataViews> |
| | 584 | <ed:Collections> |
| | 585 | <!-- just one top-level collection at the Endpoint --> |
| | 586 | <ed:Collection pid="http://hdl.handle.net/4711/0815"> |
| | 587 | <ed:Title xml:lang="de">Goethe Corpus</ed:Title> |
| | 588 | <ed:Title xml:lang="en">Goethe Korpus</ed:Title> |
| | 589 | <ed:Description xml:lang="de">Der Goethe Korpus des IDS Mannheim.</ed:Description> |
| | 590 | <ed:Description xml:lang="en">The Goethe corpus of IDS Mannheim.</ed:Description> |
| | 591 | <ed:LandingPageURI>http://repos.example.org/corpus1.html</ed:LandingPageURI> |
| | 592 | <ed:Languages> |
| | 593 | <ed:Language>deu</ed:Language> |
| | 594 | </ed:Languages> |
| | 595 | </ed:Collection> |
| | 596 | </ed:Collections> |
| | 597 | </ed:EndpointDescription> |
| | 598 | </sru:extraResponseData> |
| | 599 | </sru:explainResponse> |
| | 600 | }}} |
| | 601 | |
