Changes between Version 39 and Version 40 of FCS-Specification-ScrapBook


Ignore:
Timestamp:
02/13/14 11:14:09 (10 years ago)
Author:
oschonef
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • FCS-Specification-ScrapBook

    v39 v40  
    4040
    4141
     42=== Typographic and XML Namespace conventions ===
     43The following typographic conventions for XML fragments will be used throughout this specification:
     44 * `<prefix:Element>`: An XML element with the Generic Identifier ''Element'' that is bound an XML namespace denoted by the prefix ''prefix''.
     45 * `@attr`: An XML attribute with the name ''attr''
     46{{{#!comment
     47 * `@prefix:attr`: An XML attribute with the name ''attr'' that is bound to an XML namespaces denoted by the prefix ''prefix''.
     48}}}
     49 * `string`: the literal ''string'' must be used either as element content or attribute value
     50Endpoints and Clients `MUST` adhere the [#REF_XML_Namespaces XML-Namespaces] specification. This specification generally does not dictate whether XML elements should be serialized in their prefixed or non-prefixed syntax, but Endpoints `MUST` ensure, that the correct XML namespace is used for elements and that XML namespaces are declared correctly. Clients `MUST` be agnostic to which syntax was used by an Endpoint to serialize XML elements, i.e. if prefixed or unprefixed variant was used, and `SHOULD` operate solely on ''expanded name'', i.e. pairs of ''namespace name'' and ''local name''.
     51
     52The following XML namespace names and prefixes are used throughout this specification. The column ''Recommended Syntax'' indicates, which syntax variant `SHOULD` be used by Endpoints when serializing the XML response.
     53||=Prefix =||=Namespace Name                                 =||=Comment                        =||= Recommended Syntax =||
     54|| `fsc`   || `http://clarin.eu/fcs/1.0`                      || CLARIN-FCS Resources            || prefixed ||
     55|| `ed`    || `http://clarin.eu/fcs/1.0/endpoint-description` || CLARIN-FCS Endpoint Description || prefixed ||
     56|| `hits`  || `http://clarin.eu/fcs/1.0/hits`                 || CLARIN-FCS Generic Hits         || prefixed ||
     57|| `sru`   || `http://www.loc.gov/zing/srw/`                  || SRU                             || prefixed ||
     58|| `diag`  || `http://www.loc.gov/zing/srw/diagnostic/`       || SRU Diagnostics                 || prefixed ||
     59|| `cmdi`  || `http://www.clarin.eu/cmd/`                     || Component Metadata              || un-prefixed ||
     60|| `kml`   || `http://www.opengis.net/kml/2.2`                || Keyhole Markup Language         || un-prefixed ||
     61
    4262=== Glossary ===
    4363 Aggregator::
    … …  
    84104    Key words for use in RFCs to Indicate Requirement Levels, IETF RFC 2119, March 1997, \\
    85105    [http://www.ietf.org/rfc/rfc2119.txt]
     106
     107 XML-Namespaces[=#REF_XML_Namespaces]::
     108    Namespaces in XML 1.1 (Second Edition), W3C, August 2006, \\
     109    [http://www.w3.org/TR/2006/REC-xml-names11-20060816]
    86110
    87111 OASIS-SRU-Overview[=#REF_SRU_Overview]::
    … …  
    266290All entities of the Hit can be referenced by a persistent identifier and an URI. The complete Resource is referenceable by either the persistent identifier `http://hdl.handle.net/4711/08-15` or the URI `http://repos.example.org/file/text_08_15.html` and the CMDI metadata record in the CMDI Data View is referenceable either by the persistent identifier `http://hdl.handle.net/4711/08-15-1` or the URI `http://repos.example.org/file/08_15_1.cmdi`. The actual hit in the Resource Fragment is also directly referenceable by either the persistent identifier `http://hdl.handle.net/4711/00-15-2` or the URI `http://repos.example.org/file/text_08_15.html#sentence2`.   
    267291
    268 Endpoints `MUST` serialize one Resource for each hit, i.e. they `MUST NOT` combine several hits in one Resource. E.g., if a query matches five different sentences within one text (= the resource), the Endpoint must serialize five Resource (= one per hit) and embed each within one SRU result (see [#query below]).
     292Endpoints `MUST` serialize one Resource for each hit, i.e. they `MUST NOT` combine several hits in one Resource. E.g., if a query matches five different sentences within one text (= the resource), the Endpoint must serialize five Resource (= one per hit) and embed each within one SRU result (see [#searchRetrieve below]).
    269293
    270294
    … …  
    312336<!-- potential @pid and @ref attributes omitted -->
    313337<fcs:DataView type="application/x-cmdi+xml">
    314   <CMD xmlns="http://www.clarin.eu/cmd/" CMDVersion="1.1">
     338  <cmdi:CMD xmlns:cmdi="http://www.clarin.eu/cmd/" CMDVersion="1.1">
    315339    <!-- content omitted -->
    316   </CMD>
     340  </cmdi:CMD>
    317341</fcs:DataView>
    318342}}}
    … …  
    348372<!-- potential @pid and @ref attributes omitted -->
    349373<fcs:DataView type="application/vnd.google-earth.kml+xml">
    350   <kml xmlns="http://www.opengis.net/kml/2.2">
    351     <Placemark>
    352       <name>IDS Mannheim</name>
    353       <description>Institut für Deutsche Sprache, R5 6-13, 68161 Mannheim, Germany</description>
    354       <Point>
    355         <coordinates>8.4719510,49.4883700,0</coordinates>
    356       </Point>
    357     </Placemark>
    358   </kml>
     374  <kml:kml xmlns:kml="http://www.opengis.net/kml/2.2">
     375    <kml:Placemark>
     376      <kml:name>IDS Mannheim</kml:name>
     377      <kml:description>Institut für Deutsche Sprache, R5 6-13, 68161 Mannheim, Germany</kml:description>
     378      <kml:Point>
     379        <kml:coordinates>8.4719510,49.4883700,0</kml:coordinates>
     380      </kml:Point>
     381    </kml:Placemark>
     382  </kml:kml>
    359383</fcs:DataView>
    360384}}}
    … …  
    481505Endpoints and Clients `MUST` use the implement the APD Binding for SRU 1.2, as defined in [#REF_SRU_12 OASIS-SRU-12]. Endpoints and Clients `MAY` implement APD binding for version 1.1 or version 2.0.
    482506
    483 Endpoints and Clients `MUST` use the following namespace URIs for serializing responses:
     507Endpoints and Clients `MUST` use the following XML namespace names (namespace URIs) for serializing responses:
    484508 * `http://www.loc.gov/zing/srw/` for SRU response documents, and
    485509 * `http://www.loc.gov/zing/srw/diagnostic/` for diagnostics within SRU response documents.
    … …  
    499523=== Operation ''scan'' ===#scan
    500524
    501 The SRU operation ''scan'' is currently not used in the ''basic'' profile of CLARIN-FCS. An ''extended'' profile may use this operation, therefore Endpoints are `NOT RECOMMENDED` to define custom extensions that use this operation.
     525The SRU operation ''scan'' is currently not used in the ''basic'' profile of CLARIN-FCS. An ''extended'' profile may use this operation, therefore it `NOT RECOMMENDED` for Endpoints to define custom extensions that use this operation.
    502526
    503527
    … …  
    519543 * Example:
    520544{{{#!xml
    521 <CMD xmlns="http://www.clarin.eu/cmd/" CMDVersion="1.1">
    522   <!-- ...  -->
    523   <Resources>
    524     <ResourceProxyList>
     545<cmdi:CMD xmlns:cmdi="http://www.clarin.eu/cmd/" CMDVersion="1.1">
     546  <cmdi:Header>
     547    <!-- ... -->
     548    <cmdi:MdSelfLink>http://hdl.handle.net/4711/0815</cmdi:MdSelfLink>
     549    <!-- ... -->
     550  </cmdi:Header>
     551  <cmdi:Resources>
     552    <cmdi:ResourceProxyList>
    525553      <!-- ... -->
    526       <ResourceProxy id="r4711">
    527         <ResourceType mimetype="application/sru+xml">SearchService</ResourceType>
    528         <ResourceRef>http://repos.example.org/fcs-endpoint</ResourceRef>
    529       </ResourceProxy>
     554      <cmdi:ResourceProxy id="r4711">
     555        <cmdi:ResourceType mimetype="application/sru+xml">SearchService</cmdi:ResourceType>
     556        <cmdi:ResourceRef>http://repos.example.org/fcs-endpoint</cmdi:ResourceRef>
     557      </cmdi:ResourceProxy>
    530558      <!-- ... -->
    531     </ResourceProxyList>
    532   </Resources>
     559    </cmdi:ResourceProxyList>
     560  </cmdi:Resources>
    533561  <!-- ... -->
    534 </CMD>
     562</cmdi:CMD>
    535563}}}
    536564
    … …  
    543571
    544572An Endpoint `MAY` add arbitrary XML fragments to a `<fcs:Resource>` element. Clients `MUST` ignore any custom extensions they do not understand.
     573Endpoints `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/`.
    545574
    546575 * Example: