Changes between Version 70 and Version 71 of FCS-Specification-ScrapBook


Ignore:
Timestamp:
03/12/14 17:52:24 (10 years ago)
Author:
Oliver Schonefeld
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • FCS-Specification-ScrapBook

    v70 v71  
    3131 3. '''Explicitly list supported Data Views by collection''': Amend the Endpoint Description to explicitly encode which Data Views are supported by a given collection. The semantics between parent-child is, that children `MUST` "inherit" the Data Views of the parent, i.e. a child collection must support all Data Views supported by the parent collection. Something along the lines of:
    3232{{{#!xml
    33 <ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/1.0/endpoint-description">
     33<ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/endpoint-description">
    3434  <ed:Profile>basic</ed:Profile>
    3535  <ed:SupportedDataViews>
    … …  
    6666 4. '''Endpoint Capabilities''': `<Capability>` elements in the Endpoint Description verbosely describe capabilities of an Endpoint in a more fine grained fashion than a Profile. A Profile is a collection of capabilities. Endpoint Description could look like the following:
    6767{{{#!xml
    68 <ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/1.0/endpoint-description">
     68<ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/endpoint-description">
    6969  <ed:Profile>basic</ed:Profile>
    7070  <ed:Capabilities>
    … …  
    218218The following XML namespace names and prefixes are used throughout this specification. The column "Recommended Syntax" indicates, which syntax variant `SHOULD` be used by the Endpoint to serialize the XML response.
    219219||=Prefix =||=Namespace Name                                 =||=Comment                        =||= Recommended Syntax =||
    220 || `fsc`   || `http://clarin.eu/fcs/1.0`                      || CLARIN-FCS Resources            || prefixed ||
    221 || `ed`    || `http://clarin.eu/fcs/1.0/endpoint-description` || CLARIN-FCS Endpoint Description || prefixed ||
    222 || `hits`  || `http://clarin.eu/fcs/1.0/hits`                 || CLARIN-FCS Generic Hits         || prefixed ||
     220|| `fsc`   || `http://clarin.eu/fcs/resource`                 || CLARIN-FCS Resources            || prefixed ||
     221|| `ed`    || `http://clarin.eu/fcs/endpoint-description`    || CLARIN-FCS Endpoint Description || prefixed ||
     222|| `hits`  || `http://clarin.eu/fcs/dataview/hits`            || CLARIN-FCS Generic Hits         || prefixed ||
    223223|| `sru`   || `http://www.loc.gov/zing/srw/`                  || SRU                             || prefixed ||
    224224|| `diag`  || `http://www.loc.gov/zing/srw/diagnostic/`       || SRU Diagnostics                 || prefixed ||
    … …  
    266266 ''Basic profile''::
    267267   Endpoints `MUST` support ''term-only'' queries. \\
    268    Endpoints `SHOULD` support ''terms'' combined with boolean operator queries (''AND'' and ''OR''), including subqueries. Endpoints `MAY` also support ''NOT'' or ''PROX'' operator queries. If the Endpoint does not support a query, i.e. the used operators are not supported by the Endpoint, it `MUST` return an appropriate error message using the appropriate SRU diagnostic. \\
     268   Endpoints `SHOULD` support ''terms'' combined with boolean operator queries (''AND'' and ''OR''), including sub-queries. Endpoints `MAY` also support ''NOT'' or ''PROX'' operator queries. If the Endpoint does not support a query, i.e. the used operators are not supported by the Endpoint, it `MUST` return an appropriate error message using the appropriate SRU diagnostic. \\
    269269   Examples for valid CQL queries for the ''basic profile'':
    270270{{{
    … …  
    306306The elements `<fcs:Resource>`, `<fcs:ResourceFragment>` and `<fcs:DataView>` `MAY` carry a `@pid` and/or a `@ref` attribute, which allows linking to the original data represented by the Resource, Resource Fragment, or Data View. A `@pid` attribute `MUST` contain a valid persistent identifier, a `@ref` `MUST` contain valid URI, i.e. a "plain" URI without the additional semantics of being a persistent reference.
    307307
    308 Endpoints `MUST` use the identifier `http://clarin.eu/fcs/1.0` for the ''responseItemType'' (= content for the `<sru:recordSchema>` element) in SRU responses.
     308Endpoints `MUST` use the identifier `http://clarin.eu/fcs/resource` for the ''responseItemType'' (= content for the `<sru:recordSchema>` element) in SRU responses.
    309309
    310310Endpoints `MAY` serialize hits as multiple Data Views, however they `MUST` provide the Generic Hits (HITS) Data View either encoded as a Resource Fragment (if applicable), or otherwise within the Resource (if there is no reasonable Resource Fragment). Other Data Views `SHOULD` be put in a place that is logical for their content (as is to be determined by the Endpoint), e.g. a metadata Data View would most likely be put directly below Resource and a Data View representing some annotation layers directly around the hit is more likely to belong within a Resource Fragment.
    … …  
    312312[=#REF_Example_1]Example 1:
    313313{{{#!xml
    314 <fcs:Resource xmlns:fcs="http://clarin.eu/fcs/1.0" pid="http://hdl.handle.net/4711/00-15">
     314<fcs:Resource xmlns:fcs="http://clarin.eu/fcs/resource" pid="http://hdl.handle.net/4711/00-15">
    315315  <fcs:DataView type="application/x-clarin-fcs-hits+xml">
    316316      <!-- data view payload omitted -->
    … …  
    322322[=#REF_Example_2]Example 2:
    323323{{{#!xml
    324 <fcs:Resource xmlns:fcs="http://clarin.eu/fcs/1.0" pid="http://hdl.handle.net/4711/08-15">
     324<fcs:Resource xmlns:fcs="http://clarin.eu/fcs/resource" pid="http://hdl.handle.net/4711/08-15">
    325325  <fcs:ResourceFragment>
    326326    <fcs:DataView type="application/x-clarin-fcs-hits+xml">
    … …  
    334334[=#REF_Example_3]Example 3:
    335335{{{#!xml
    336 <fcs:Resource xmlns:fcs="http://clarin.eu/fcs/1.0"
     336<fcs:Resource xmlns:fcs="http://clarin.eu/fcs/resource"
    337337              pid="http://hdl.handle.net/4711/08-15" ref="http://repos.example.org/file/text_08_15.html">
    338338  <fcs:DataView type="application/x-cmdi+xml"
    … …  
    370370<!-- potential @pid and @ref attributes omitted -->
    371371<fcs:DataView type="application/x-clarin-fcs-hits+xml">
    372   <hits:Result xmlns:hits="http://clarin.eu/fcs/1.0/hits">
     372  <hits:Result xmlns:hits="http://clarin.eu/fcs/dataview/hits">
    373373    The quick brown <hits:Hit>fox</hits:Hit> jumps over the lazy dog.
    374374  </hits:Result>
    … …  
    379379<!-- potential @pid and @ref attributes omitted -->
    380380<fcs:DataView type="application/x-clarin-fcs-hits+xml">
    381   <hits:Result xmlns:hits="http://clarin.eu/fcs/1.0/hits">
     381  <hits:Result xmlns:hits="http://clarin.eu/fcs/dataview/hits">
    382382    The quick brown <hits:Hit>fox</hits:Hit> jumps over the lazy <hits:Hit>dog</hits:Hit>.
    383383  </hits:Result>
    … …  
    466466[=#REF_Example_4]Example 4:
    467467{{{#!xml
    468 <ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/1.0/endpoint-description">
     468<ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/endpoint-description">
    469469  <ed:Profile>basic</ed:Profile>
    470470  <ed:SupportedDataViews>
    … …  
    490490[=#REF_Example_5]Example 5:
    491491{{{#!xml
    492 <ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/1.0/endpoint-description">
     492<ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/endpoint-description">
    493493  <ed:Profile>basic</ed:Profile>
    494494  <ed:SupportedDataViews>
    … …  
    584584   `<zr:serverInfo>` as defined in [#REF_Explain SRU-Explain] (`REQUIRED`) \\
    585585   `<zr:databaseInfo>` as defined in [#REF_Explain SRU-Explain] (`REQUIRED`) \\
    586    `<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`. \\
     586   `<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/resource` and an `@name` attribute with a value of `fcs`. \\
    587587   `<zr:configInfo>` is `OPTIONAL``\\
    588588   An ''extended'' profile may define how the `<zr:indexInfo>` element is to be used, therefore it is `NOT RECOMMENDED` for Endpoints to define custom extensions.
    … …  
    641641  </sru:echoedExplainRequest>
    642642  <sru:extraResponseData>
    643     <ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/1.0/endpoint-description">
     643    <ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/endpoint-description">
    644644      <ed:Profile>basic</ed:Profile>
    645645      <ed:SupportedDataViews>
    … …  
    670670The ''searchRetrieve'' operation of the SRU protocol is used for searching in the Resources that are provided by the Endpoint. The SRU protocol defines the serialization of request and response formats in [#REF_SRU_12 OASIS-SRU-12]. In SRU, 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''.
    671671
    672 Endpoints `MUST` support the CLARIN-FCS record schema (see section [#resultFormat Result Format]) and `MUST` use the value `http://clarin.eu/fcs/1.0` for the ''responseItemType'' ("record schema identifier").
     672Endpoints `MUST` support the CLARIN-FCS record schema (see section [#resultFormat Result Format]) and `MUST` use the value `http://clarin.eu/fcs/resource` for the ''responseItemType'' ("record schema identifier").
    673673Endpoints `MUST` represent exactly ''one hit'' within the Resource as one SRU record, i.e. `<sru:record>` element.
    674674
    … …  
    686686  <sru:records>
    687687    <sru:record>
    688       <sru:recordSchema>http://clarin.eu/fcs/1.0</sru:recordSchema>
     688      <sru:recordSchema>http://clarin.eu/fcs/resource</sru:recordSchema>
    689689      <sru:recordPacking>xml</sru:recordPacking>
    690690      <sru:recordData>
    691         <fcs:Resource xmlns:fcs="http://clarin.eu/fcs/1.0" pid="http://hdl.handle.net/4711/08-15">
     691        <fcs:Resource xmlns:fcs="http://clarin.eu/fcs/resource" pid="http://hdl.handle.net/4711/08-15">
    692692          <fcs:ResourceFragment>
    693693            <fcs:DataView type="application/x-clarin-fcs-hits+xml">
    … …  
    732732}}}
    733733
    734 If an invalid persistent identifier is passed by the 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.
     734If an invalid persistent identifier is passed by the Client, the Endpoint `MUST` issue a `http://clarin.eu/fcs/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.
    735735
    736736
    … …  
    744744=== List of diagnoistics ===
    745745Apart from the SRU diagnostics defined in [#REF_SRU_12 OASIS-SRU-12, Appendix C] and [#REF_LOC_DIAG 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.
    746 ||=Identifier URI                         =||=Description                                                          =||= Details Format =||
    747 || `http://clarin.eu/fcs/1.0/diagnostic/1` || Persistent identifier passed in for restricting the search is invalid || The offending persistent identifier ||
     746||=Identifier URI                     =||=Description                                                          =||= Details Format =||
     747|| `http://clarin.eu/fcs/diagnostic/1` || Persistent identifier passed in for restricting the search is invalid || The offending persistent identifier ||
    748748
    749749== Non-normative Appendix
    … …  
    782782The following example illustrates how an extension can be embedded into the Result Format:
    783783{{{#!xml
    784 <fcs:Resource xmlns:fcs="http://clarin.eu/fcs/1.0" pid="hdl:4711/0815">
     784<fcs:Resource xmlns:fcs="http://clarin.eu/fcs/resource" pid="hdl:4711/0815">
    785785    <fcs:DataView type="application/x-clarin-fcs-hits+xml">
    786       <hits:Result xmlns:hits="http://clarin.eu/fcs/1.0/hits">
     786      <hits:Result xmlns:hits="http://clarin.eu/fcs/dataview/hits">
    787787        The quick brown <hits:Hit>fox</hits:Hit> jumps over the lazy <hits:Hit>dog</hits:Hit>.
    788788      </hits:Result>
    … …  
    818818   * [[oschonef|Oliver (IDS)]]: We could already prepare for for feature encoding, by adding adding a `<feature>` elements to the Endpoint Description. Or better call the capabilities, so something along the lines of:
    819819{{{#!xml
    820 <ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/1.0/endpoint-description">
     820<ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/endpoint-description">
    821821  <ed:Profile>basic</ed:Profile>
    822822  <ed:Capabilities>
    823823    <!-- capabilities should be identified by closed vocabulary; maybe encoded by URIs? -->
    824     <ed:Capability>http://clarin.eu/fcs/1.0/feature/basic-search</ed:Capability>
     824    <ed:Capability>http://clarin.eu/fcs/feature/basic-search</ed:Capability>
    825825    <!-- actually the next would already be an extended capability beyond the basic profile -->
    826     <ed:Capability>http://clarin.eu/fcs/1.0/feature/query-expansion</ed:Capability>
     826    <ed:Capability>http://clarin.eu/fcs/feature/query-expansion</ed:Capability>
    827827  </ed:Capabilities>
    828828  <!-- other EndpointDescription stuff ... -->
    … …  
    838838    * [[oschonef|Oliver (IDS)]]: Yes, so do you think we should mark "supported dataviews" per collection/resource? Something along the lines like:
    839839{{{#!xml
    840 <ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/1.0/endpoint-description">
     840<ed:EndpointDescription xmlns:ed="http://clarin.eu/fcs/endpoint-description">
    841841  <ed:Profile>basic</ed:Profile>
    842842  <ed:SupportedDataViews>