Changes between Version 49 and Version 50 of FCS-Specification-ScrapBook

Timestamp:

02/14/14 13:58:17 (10 years ago)

Author:

oschonef

Comment:

--

FCS-Specification-ScrapBook

@@ -477 +477 @@
 }}}
 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.
+
+=== Endpoint Custom Extensions ===
+The Endpoint can add custom extensions, i.e custom data, to the Result Format. This extension mechanism can for example be used to provide hints for an (XSLT/XQuery) application that works directly on CLARIN-FCS, e.g. to allow it to generate back and forward links to navigate in a result set. 
+
+The Endpoint `MAY` add arbitrary XML fragments to the extension hooks provided in the `<fcs:Resource>` element (see the XML schema for "Resource.xsd"). The Endpoint `MUST` use a custom XML namespace name for the extension. The Endpoint `MUST NOT` use XML namespace names, that start with the prefixes `http://clarin.eu`, `http://www.clarin.eu/`, `https://clarin.eu` or `http://www.clarin.eu/`.
+
+The Client `MUST` ignore any custom extensions it does not understand and skip over these XML fragments when parsing the Endpoint's response.
+
+The appendix contains an [#extensionExample example], how an extension could be implemented.
 
 == CLARIN-FCS to SRU/CQL binding ==
@@ -666 +675 @@
 The following extra request parameters are used in CLARIN-FCS:
 ||=Parameter Name =||=SRU operations =||=Allowed values =||= Description =||
-|| `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 an ''explain'' response. ||
+|| `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. ||
 || `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 ||
 
@@ -704 +713 @@
 }}}
 
-=== Endpoint custom extensions ===
-The CLARIN-FCS protocol specification allows Endpoints to add custom data to their responses. This extension mechanism can for example be used to provide hints to an (XSLT/XQuery) application that works directly on CLARIN-FCS, e.g. to allow it to generate back and forward links to navigate in a result set. 
-
-*WIP*
-
-The Endpoint `MAY` add arbitrary XML fragments to a `<fcs:Resource>` element. Clients `MUST` ignore any custom extensions they do not understand. 
-Endpoints `MUST` use a custom XML namespace name for their extensions. Endpoints `MUST NOT` use XML namespace names, that start with the prefixes `http://clarin.eu`, `http://www.clarin.eu/`, `https://clarin.eu` or `http://www.clarin.eu/`.
-
- * Example:
+=== Endpoint custom extensions ===#extensionExample
+The CLARIN-FCS protocol specification allows Endpoints to add custom data to their responses, e.g. to provide hints to for an (XSLT/XQuery) application that works directly on CLARIN-FCS. It could use the custom data to generate back and forward links for a GUI to navigate in a result set. 
+
+The following example illustrates how an extension can be embedded into the Result Format:
 {{{#!xml
 <fcs:Resource xmlns:fcs="http://clarin.eu/fcs/1.0" pid="hdl:4711/0815">