| 376 | | </fcs:DataView> |
| 377 | | }}} |
| 378 | | |
| 379 | | ===== Component Metadata (CMDI) ===== |
| 380 | | ||=Description =|| A CMDI metadata record || |
| 381 | | ||=MIME type =|| `application/x-cmdi+xml` || |
| 382 | | ||=Payload Disposition =|| ''inline'' or ''reference'' || |
| 383 | | The ''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. |
| 384 | | * Example (inline): |
| 385 | | {{{#!xml |
| 386 | | <!-- potential @pid and @ref attributes omitted --> |
| 387 | | <fcs:DataView type="application/x-cmdi+xml"> |
| 388 | | <cmdi:CMD xmlns:cmdi="http://www.clarin.eu/cmd/" CMDVersion="1.1"> |
| 389 | | <!-- content omitted --> |
| 390 | | </cmdi:CMD> |
| 391 | | </fcs:DataView> |
| 392 | | }}} |
| 393 | | * Example (referenced): |
| 394 | | {{{#!xml |
| 395 | | <!-- potential @pid attribute omitted --> |
| 396 | | <fcs:DataView type="application/x-cmdi+xml" ref="http://repos.example.org/resources/4711/0815.cmdi" /> |
| 397 | | }}} |
| 398 | | |
| 399 | | ===== Images (IMG) ===== |
| 400 | | ||=Description =|| An image related to the hit || |
| 401 | | ||=MIME type =|| `image/png`, `image/jpeg`, `image/gif`, `image/svg+xml` || |
| 402 | | ||=Payload Disposition =|| ''reference'' || |
| 403 | | |
| 404 | | The ''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. |
| 405 | | * Example: |
| 406 | | {{{#!xml |
| 407 | | <!-- potential @pid attribute omitted --> |
| 408 | | <fcs:DataView type="image/png" ref="http://repos.example.org/resources/4711/0815.png" /> |
| 409 | | }}} |
| 410 | | |
| 411 | | ===== Geolocation (GEO) ===== |
| 412 | | ||=Description =|| An geographic location related to the hit || |
| 413 | | ||=MIME type =|| `application/vnd.google-earth.kml+xml` || |
| 414 | | ||=Payload Disposition =|| ''inline'' || |
| 415 | | The ''Geolocation'' Data View allows to geolocalize a hit. If `MUST` be encoded using the XML representation of the Keyhole Markup Language (KML). The KML fragment `MUST` comply with the specification as defined by [#REF_KML_Spec KML]. |
| 416 | | * Example: |
| 417 | | {{{#!xml |
| 418 | | <!-- potential @pid and @ref attributes omitted --> |
| 419 | | <fcs:DataView type="application/vnd.google-earth.kml+xml"> |
| 420 | | <kml:kml xmlns:kml="http://www.opengis.net/kml/2.2"> |
| 421 | | <kml:Placemark> |
| 422 | | <kml:name>IDS Mannheim</kml:name> |
| 423 | | <kml:description>Institut für Deutsche Sprache, R5 6-13, 68161 Mannheim, Germany</kml:description> |
| 424 | | <kml:Point> |
| 425 | | <kml:coordinates>8.4719510,49.4883700,0</kml:coordinates> |
| 426 | | </kml:Point> |
| 427 | | </kml:Placemark> |
| 428 | | </kml:kml> |
| | 772 | ---- |
| | 773 | == Proposal for new specification: Federated Content Search - Data Views == |
| | 774 | The following is a proposal for the separate specification of Data Views for CLARIN-FCS. When done, cut and paste to the appropriate section of the Wiki and publish on the CLARIN web page. |
| | 775 | ---- |
| | 776 | = CLARIN Federated Content Search (CLARIN-FCS) - Data Views = |
| | 777 | [[PageOutline(1-5)]] |
| | 778 | |
| | 779 | == Introduction == |
| | 780 | This specification is a supplementary specification to the CLARIN-FCS Core specification and defines additional Data View to be used in CLARIN-FCS. This specification will tersely describe the supplementary Data Views. For detailed information about the CLARIN-FCS ''interface specification'' see [#REF_FCS_Core CLARIN-FCS-Core]. |
| | 781 | |
| | 782 | === Terminology === |
| | 783 | The key words `MUST`, `MUST NOT`, `REQUIRED`, `SHALL`, `SHALL NOT`, `SHOULD`, `SHOULD NOT`, `RECOMMENDED`, `MAY`, and `OPTIONAL` in this document are to be interpreted as described in [#REF_RFC_2119 RFC2119]. |
| | 784 | |
| | 785 | === Normative References === |
| | 786 | RFC2119[=#REF_RFC_2119]:: |
| | 787 | Key words for use in RFCs to Indicate Requirement Levels, IETF RFC 2119, March 1997, \\ |
| | 788 | [http://www.ietf.org/rfc/rfc2119.txt] |
| | 789 | |
| | 790 | XML-Namespaces[=#REF_XML_Namespaces]:: |
| | 791 | Namespaces in XML 1.0 (Third Edition), W3C, 8 December 2009, \\ |
| | 792 | [http://www.w3.org/TR/2009/REC-xml-names-20091208/] |
| | 793 | |
| | 794 | CLARIN-FCS-Core[=#REF_FCS_Core]:: |
| | 795 | CLARIN Federated Content Search (CLARIN-FCS) - Core, SCCTC FCS Task Force, March 2014, \\ |
| | 796 | [http://www.clarin.eu/fcs/add/link/here] |
| | 797 | |
| | 798 | === Non-Normative References === |
| | 799 | RFC6838[=#REF_RFC_6838]:: |
| | 800 | Media Type Specifications and Registration Procedures, IETF RFC 6838, January 2013, \\ |
| | 801 | [http://www.ietf.org/rfc/rfc6838.txt] |
| | 802 | |
| | 803 | RFC3023[=#REF_RFC_3023]:: |
| | 804 | XML Media Types, IETF RFC 3023, January 2001, \\ |
| | 805 | [http://www.ietf.org/rfc/rfc3023.txt] |
| | 806 | |
| | 807 | KML[=#REF_KML_Spec]:: |
| | 808 | Keyhole Markup Language (KML), Open Geospatial Consortium, 2008, \\ |
| | 809 | [http://www.opengeospatial.org/standards/kml] |
| | 810 | |
| | 811 | === Typographic and XML Namespace conventions === |
| | 812 | The following typographic conventions for XML fragments will be used throughout this specification: |
| | 813 | * `<prefix:Element>` \\ An XML element with the Generic Identifier ''Element'' that is bound to an XML namespace denoted by the prefix ''prefix''. |
| | 814 | * `@attr` \\ An XML attribute with the name ''attr'' |
| | 815 | {{{#!comment |
| | 816 | * `@prefix:attr` \\ An XML attribute with the name ''attr'' that is bound to an XML namespaces denoted by the prefix ''prefix''. |
| | 817 | }}} |
| | 818 | * `string` \\ The literal ''string'' must be used either as element content or attribute value. |
| | 819 | Endpoints and Clients `MUST` adhere the [#REF_XML_Namespaces XML-Namespaces] specification. The CLARIN-FCS interface 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 for serializing the XML elements, i.e. if the prefixed or un-prefixed variant was used, and `SHOULD` operate solely on ''expanded names'', i.e. pairs of ''namespace name'' and ''local name''. |
| | 820 | |
| | 821 | The 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. |
| | 822 | ||=Prefix =||=Namespace Name =||=Comment =||=Recommended Syntax =|| |
| | 823 | || `fsc` || `http://clarin.eu/fcs/resource` || CLARIN-FCS Resources || prefixed || |
| | 824 | || `cmdi` || `http://www.clarin.eu/cmd/` || Component Metadata || un-prefixed || |
| | 825 | || `kml` || `http://www.opengis.net/kml/2.2` || Keyhole Markup Language || un-prefixed || |
| | 826 | |
| | 827 | == Data Views == |
| | 828 | A Data View serves as a container for representing search results within CLARIN-FCS. Data Views are designed to allow for different representations of results. This specification defines supplementary Data Views beyond the Generic Hits Data View, that is part of the CLARIN-FCS Core specification. For detailed information what Data Views are and how they are integrated in CLARIN-FCS see [#REF_FCS_Core CLARIN-FCS-Core]. |
| | 829 | |
| | 830 | '''NOTE''': The examples in the following sections ''show only'' the payload with the enclosing `<fcs:DataView>` element of a Data View. Of course, the Data View must be embedded either in a `<fcs:Resource>` or a `<fcs:ResourceFragment>` element. The `@pid` and `@ref` attributes have been omitted for all ''inline'' payload types. |
| | 831 | |
| | 832 | === Generic Hits (HITS) === |
| | 833 | The ''Generic Hits'' (HITS) Data View is an integral part of the Core specification and serves as the as the ''most basic'' agreement in CLARIN-FCS for the serialization of search results. For details about this Data View, see refer to the Core specification [#REF_FCS_Core CLARIN-FCS-Core, Section "Generic Hits (HITS)"]. |
| | 834 | |
| | 835 | === Component Metadata (CMDI) === |
| | 836 | ||=Description =|| A CMDI metadata record || |
| | 837 | ||=MIME type =|| `application/x-cmdi+xml` || |
| | 838 | ||=Payload Disposition =|| ''inline'' or ''reference'' || |
| | 839 | The ''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. |
| | 840 | * Example (inline): |
| | 841 | {{{#!xml |
| | 842 | <!-- potential @pid and @ref attributes omitted --> |
| | 843 | <fcs:DataView type="application/x-cmdi+xml"> |
| | 844 | <cmdi:CMD xmlns:cmdi="http://www.clarin.eu/cmd/" CMDVersion="1.1"> |
| | 845 | <!-- content omitted --> |
| | 846 | </cmdi:CMD> |
| | 847 | </fcs:DataView> |
| | 848 | }}} |
| | 849 | * Example (referenced): |
| | 850 | {{{#!xml |
| | 851 | <!-- potential @pid attribute omitted --> |
| | 852 | <fcs:DataView type="application/x-cmdi+xml" ref="http://repos.example.org/resources/4711/0815.cmdi" /> |
| | 853 | }}} |
| | 854 | |
| | 855 | === Images (IMG) === |
| | 856 | ||=Description =|| An image related to the hit || |
| | 857 | ||=MIME type =|| `image/png`, `image/jpeg`, `image/gif`, `image/svg+xml` || |
| | 858 | ||=Payload Disposition =|| ''reference'' || |
| | 859 | |
| | 860 | The ''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. |
| | 861 | * Example: |
| | 862 | {{{#!xml |
| | 863 | <!-- potential @pid attribute omitted --> |
| | 864 | <fcs:DataView type="image/png" ref="http://repos.example.org/resources/4711/0815.png" /> |
| | 865 | }}} |
| | 866 | |
| | 867 | === Geolocation (GEO) === |
| | 868 | ||=Description =|| An geographic location related to the hit || |
| | 869 | ||=MIME type =|| `application/vnd.google-earth.kml+xml` || |
| | 870 | ||=Payload Disposition =|| ''inline'' || |
| | 871 | The ''Geolocation'' Data View allows to geolocalize a hit. If `MUST` be encoded using the XML representation of the Keyhole Markup Language (KML). The KML fragment `MUST` comply with the specification as defined by [#REF_KML_Spec KML]. |
| | 872 | * Example: |
| | 873 | {{{#!xml |
| | 874 | <!-- potential @pid and @ref attributes omitted --> |
| | 875 | <fcs:DataView type="application/vnd.google-earth.kml+xml"> |
| | 876 | <kml:kml xmlns:kml="http://www.opengis.net/kml/2.2"> |
| | 877 | <kml:Placemark> |
| | 878 | <kml:name>IDS Mannheim</kml:name> |
| | 879 | <kml:description>Institut für Deutsche Sprache, R5 6-13, 68161 Mannheim, Germany</kml:description> |
| | 880 | <kml:Point> |
| | 881 | <kml:coordinates>8.4719510,49.4883700,0</kml:coordinates> |
| | 882 | </kml:Point> |
| | 883 | </kml:Placemark> |
| | 884 | </kml:kml> |
| | 885 | </fcs:DataView> |
| | 886 | }}} |
| | 887 | ---- |
