Changes between Version 66 and Version 67 of FCS-Specification-ScrapBook


Ignore:
Timestamp:
02/24/14 09:51:47 (10 years ago)
Author:
teckart
Comment:

Just some typos

Legend:

Unmodified
Added
Removed
Modified

  • FCS-Specification-ScrapBook

    v66 v67  
    145145=== Typographic and XML Namespace conventions ===
    146146The following typographic conventions for XML fragments will be used throughout this specification:
    147  * `<prefix:Element>` \\ An XML element with the Generic Identifier ''Element'' that is bound an XML namespace denoted by the prefix ''prefix''.
     147 * `<prefix:Element>` \\ An XML element with the Generic Identifier ''Element'' that is bound to an XML namespace denoted by the prefix ''prefix''.
    148148 * `@attr` \\ An XML attribute with the name ''attr''
    149149{{{#!comment
    … …  
    214214cat AND (mouse OR "lazy dog")
    215215}}}
    216    The Endpoint is `MUST` perform the query on an annotation tier, that makes the most sense for the user, i.e. the textual content for a text corpus resource or the orthographic transcription of a spoken language corpus. Endpoints `SHOULD` perform the query case-sensitive.\\
     216   The Endpoint `MUST` perform the query on an annotation tier, that makes the most sense for the user, i.e. the textual content for a text corpus resource or the orthographic transcription of a spoken language corpus. Endpoints `SHOULD` perform the query case-sensitive.\\
    217217   Endpoint `MUST NOT` silently accept queries that include CQL features besides ''term-only'' and ''terms'' combined with boolean operator queries, i.e. queries involving context sets, etc.
    218218
    … …  
    233233   A ''Resource Fragment'' is a smaller unit in a ''Resource'', i.e. a sentence in a text corpus or a time interval in an audio transcription.
    234234
    235 A Resource `SHOULD` be the most precise unit of data that is directly addressable as a "whole". A Resource `SHOULD` contain a Resource Fragment, if the hit consists of just a part of the Resource unit, if the hit is a sentence within a large text. A Resource Fragment `SHOULD` be addressable within a resource, i.e. it has an offset or a resource-internal identifier. Using Resource Fragments is `OPTIONAL`, but Endpoints are encouraged to use them. If the Endpoint encodes a hit with a Resource Fragment, the actual hit `SHOULD` be encoded as a Data View that is encoded in a Resource Fragment.
     235A Resource `SHOULD` be the most precise unit of data that is directly addressable as a "whole". A Resource `SHOULD` contain a Resource Fragment, if the hit consists of just a part of the Resource unit (for example if the hit is a sentence within a large text). A Resource Fragment `SHOULD` be addressable within a resource, i.e. it has an offset or a resource-internal identifier. Using Resource Fragments is `OPTIONAL`, but Endpoints are encouraged to use them. If the Endpoint encodes a hit with a Resource Fragment, the actual hit `SHOULD` be encoded as a Data View that is encoded in a Resource Fragment.
    236236
    237237Endpoints `SHOULD` always provide a links to the resource itself, i.e. each Resource or Resource Fragment `SHOULD` be identified by a persistent identifier or providing a URI, that is unique for Endpoint. Even if direct linking is not possible, i.e. due to licensing issues, the Endpoints `SHOULD` provide a URI to link to a web-page describing the corpus or collection, including instruction on how to obtain it. Endpoints `SHOULD` provide links that are as specific as possible (and logical), i.e. if a sentence within a resource cannot be addressed directly, the Resource Fragment `SHOULD NOT` contain a persistent identifier or a URI.
    … …  
    326326||=MIME type           =|| `application/x-cmdi+xml` ||
    327327||=Payload Disposition =|| ''inline'' or ''reference'' ||
    328 The ''Component Metadata'' Data View allows to embed a CMDI metadata record that ''applicable'' to the specific context into the Endpoint response, e.g. metadata about the resource in which the hit was produced. If this CMDI record is applicable for the entire Resource, is `SHOULD` be put in a `<fcs:DataView>` element below the `<fcs:Resource>` element. If it is applicable to the Resource Fragment, i.e. it contains more specialized metadata than the metadata for the encompassing resource, it `SHOULD` be put in a `<fcs:DataView>` element below the `<fcs:ResourceFragment>` element. Endpoints `SHOULD` provide the payload ''inline'', but Endpoints `MAY` also use the ''reference'' method. If an Endpoint uses the ''reference'' method, the CMDI metadata record `MUST` be downloadable without any restrictions.
     328The ''Component Metadata'' Data View allows to embed a CMDI metadata record that is ''applicable'' to the specific context into the Endpoint response, e.g. metadata about the resource in which the hit was produced. If this CMDI record is applicable for the entire Resource, it `SHOULD` be put in a `<fcs:DataView>` element below the `<fcs:Resource>` element. If it is applicable to the Resource Fragment, i.e. it contains more specialized metadata than the metadata for the encompassing resource, it `SHOULD` be put in a `<fcs:DataView>` element below the `<fcs:ResourceFragment>` element. Endpoints `SHOULD` provide the payload ''inline'', but Endpoints `MAY` also use the ''reference'' method. If an Endpoint uses the ''reference'' method, the CMDI metadata record `MUST` be downloadable without any restrictions.
    329329 * Example (inline):
    330330{{{#!xml
    … …  
    347347||=Payload Disposition =|| ''reference'' ||
    348348
    349 The ''Image'' Data View allows top provide an image, that is relevant to the hit, e.g. a facsimile of the source of a transcription. Endpoints `MUST` provide the payload by the ''reference'' method and the image file `SHOULD` be downloadable without any restrictions.
     349The ''Image'' Data View allows to provide an image, that is relevant to the hit, e.g. a facsimile of the source of a transcription. Endpoints `MUST` provide the payload by the ''reference'' method and the image file `SHOULD` be downloadable without any restrictions.
    350350 * Example:
    351351{{{#!xml
    … …  
    477477</ed:EndpointDescription>
    478478}}}
    479 This more complex [#REF_Example_5 example] show an Endpoint Description for an Endpoint that, similar to [#REF_Example_4 Example 4], supports the ''basic'' profile. In addition to the Generic Hits Data View it also supports CMDI the CMDI Data View. The Endpoint has two top-level collections (identified by the persistent identifiers `http://hdl.handle.net/4711/0815` and `http://hdl.handle.net/4711/0816`. The second top-level collection has two sub-collections, identified by the persistent identifier `http://hdl.handle.net/4711/0816-1` and `http://hdl.handle.net/4711/0816-2`. All collections are described using several properties, like title, description, etc.
     479This more complex [#REF_Example_5 example] show an Endpoint Description for an Endpoint that, similar to [#REF_Example_4 Example 4], supports the ''basic'' profile. In addition to the Generic Hits Data View it also supports the CMDI Data View. The Endpoint has two top-level collections (identified by the persistent identifiers `http://hdl.handle.net/4711/0815` and `http://hdl.handle.net/4711/0816`. The second top-level collection has two sub-collections, identified by the persistent identifier `http://hdl.handle.net/4711/0816-1` and `http://hdl.handle.net/4711/0816-2`. All collections are described using several properties, like title, description, etc.
    480480
    481481=== Endpoint Custom Extensions ===
    … …  
    523523   `<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`. \\
    524524   `<zr:configInfo>` is `OPTIONAL``\\
    525    An ''extended'' profile may define how the `<zr:indexInfo>` element is to be used, therefore it `NOT RECOMMENDED` for Endpoints to define custom extensions.
     525   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.
    526526 ''Extended'' Profile::
    527527   '''NOTE''': the extended profile is not yet defined and will be part of a future CLARIN-FCS specification.
    528528
    529 To support auto-configuration in CLARIN-FCS, the 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. The Endpoint `MUST` include the Endpoint Description ''only'' if the Client performs an explain request with the ''extra request parameter'' `x-clarin-fcs-endpoint-description` with a value of `true`. If the Client performs an explain request ''without'' supplying this extra request parameter the Endpoint `MUST NOT` include
     529To support auto-configuration in CLARIN-FCS, the Endpoint provides 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. The Endpoint `MUST` include the Endpoint Description ''only'' if the Client performs an explain request with the ''extra request parameter'' `x-clarin-fcs-endpoint-description` with a value of `true`. If the Client performs an explain request ''without'' supplying this extra request parameter the Endpoint `MUST NOT` include
    530530the Endpoint Description. The format of the Endpoint Description XML fragment is defined in [#REF_endpointDescription Endpoint Description].
    531531
    … …  
    676676The following extra request parameters are used in CLARIN-FCS:
    677677||=Parameter Name =||=SRU operations =||=Allowed values =||= Description =||
    678 || `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 an Endpoint Description in the\\`<sru:extraResponseData>` element of the ''explain'' response. ||
     678|| `x-clarin-fcs-endpoint-description` || explain || `true` \\ All other values are reserved and `MUST` not be used by Clients || If present, the Endpoint `MUST` include an Endpoint Description in the\\`<sru:extraResponseData>` element of the ''explain'' response. ||
    679679|| `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 ||
    680680