OSLC Resource Preview 3.0

[Jim Amsden <jamsden@us.ibm.com>]

Here's my review notes on resource-preview.html...
There are some other minor wording edits in the attached document. After
review and discussion on the items below, I'll make any final changes and
check the document in.


1. Small and/or large, section 5 - indicated both are
possible

2. Section 5.1: HEAD or OPTIONS for Compact resource,
see section 6.1.2

3. 6.1.2 resources that support Preview, but also compact
resources (through which one would discover the preview URL) should also
support OPTIONS?

4. 6.5 Previews - there are tightly coupled to HTML5 and
iframe. Is it necessary to specify these as must for the client? Could
clients display the HTML some other way, say an app that isn’t a browser?

Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575

Title: OSLC Resource Preview 3.0

A technique to get a minimal HTML representation of a resource identified by a URL. Applications often use this representation to display a preview when a user mouses over a link.

---

Introduction

This specification describes how a client application can display links and embed rich previews for resources from other applications. Links may have a label and an icon, and previews are HTML markup displayed directly inside the client application.

Preview for a Link

Previews often appear as a pop-up when a user mouses over a link as in . A client can display a preview differently, however, depending on the kind of application, the size of the screen, and the capabilities of the device. A desktop application on a PC might handle previews differently than a mobile application running on a small touchscreen.

Servers can provide both small and large previews. A client might show a small preview first, then if the user gestures, show additional details from the large preview. Servers suggest sizes for previews, and previews can ask to be resized after they are displayed.

A client only needs to know the URI of a resource to display a link and a preview. It doesn't need to know anything else about the resource. Clients don't need to copy, synchronize, or cache any data.

Terminology

Terminology is based on OSLC Core Overview [[OSLCCore3]], W3C Linked Data Platform [[LDP]], W3C's Architecture of the World Wide Web [[WEBARCH]], and Hyper-text Transfer Protocol [[HTTP11]].

The following terms are used in discussions of previews:

Compact resource

A resource describing how to display a link and preview for another, associated resource.

Preview

An HTML representation of a resource that can be embedded in another user interface.

Conventions Used in This Document

The namespace for OSLC Core is http://open-services.net/ns/core#.

Commonly used namespace prefixes:

    @prefix dcterms: <http://purl.org/dc/terms/>.
    @prefix oslc:    <http://open-services.net/ns/core#>.
    @prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
    @prefix xsd:     <http://www.w3.org/2001/XMLSchema#>.

Motivation

Applications often display links to related resources from other applications. For example, a quality management application might show a link to a related defect when displaying a test result. In some cases, the quality management application only has a URI pointing to the defect. How can it show the link with an appropriate label? How can testers find out the status of the defect without leaving the quality management application?

Compact resources and resource preview solve both problems. Clients can discover the link label and a resource icon given only the resource URI. The cleint can then use the link lable and icon as a means of displaying the link in a meaningful way. Previews allow users to see see information about related resources quickly without leaving the application they're in, even when the resources are from another server.

Working with Previews

To enable previews of a resource, servers supply an associated Compact resource describing the preview. The Compact resource can contain a link label, icon, and small and/or large previews of the resource. Compact resources always have a JSON representation [[RFC4627]], but they can also have other representations such as turtle [[turtle]] or JSON-LD [[JSON-LD]]. Here is a simple example of a Compact resource:

{
    "title": "Screenshot of the problem",
    "icon": "http://example.com/icons/attachment.jpg",
    "smallPreview": {
        "document": "http://example.com/bugs/324/screenshot?preview=small"
    }
}

To display a link with a label or a preview of a resource, clients request its Compact resource. The URI of the Compact resource is found through an HTTP Link header [[RFC5988]] in HTTP responses to the resource URI. Alternatively, a client can use a Prefer request header in requests for the resource to ask for its Compact resource. The server can then inline the Compact resource directly in the response, saving an HTTP request.

The Compact resource may contain small and/or large previews. Each preview can have size hints and a link to an HTML representation designed to be embedded in other user interfaces. To display the preview, the client creates an HTML iframe element in its user interface and sets the iframe element's src to the preview document URI. This sandboxes the preview from other content in the client application and allows the preview to use its own stylesheets and scripts.

Getting the Compact Resource

Clients can discover Compact resources in two ways:

1. Discovering Compact Resources Using the HTTP Link Header
2. Discovering Compact Resources Using the HTTP Prefer Header

The HTTP Link header allows servers to offer previews for any resource, even binary resources with no RDF or JSON representations. To discover previews using the Link header, a client typically performs an HTTP HEAD or OPTIONS request on the resource URI. The response contains a Link header with the URI of the Compact resource. The client then performs a GET request on the Compact URI to retrieve the Compact resource.

Clients might instead use the HTTP Prefer header to get the Compact resource in a single HTTP request. If the client is confident that the resource has a preview, it makes an HTTP GET request on the resource URI using the return=representation preference [[RFC7240]] and an include parameter [[LDP]] asking for the Compact resource to be included in the response. The provider responds with a minimal representation of the resource and the Compact resource in the HTTP response body.

The Link header is the only way to discover the associated Compact resource for resources that don't have RDF or JSON representations, such as binary files.

Discovering Compact Resources Using the HTTP Link Header

In responses to HTTP requests for resources that have a preview, servers include a Link header [[RFC5988]] where the link relation is http://open-services.net/ns/core#Compact and the target URI is the URI of the Compact resource.

HEAD /bugs/324/screenshot HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Length: 45789
Content-Type: image/png
ETag: "678609cdee68e0fb8aea5f252b84a511"
Link: <http://example.com/bugs/324/screenshot?compact>; rel="http://open-services.net/ns/core#Compact"

Clients can request the Compact resource using the target URI of the Link header.

GET /bugs/324/screenshot?compact HTTP/1.1
Host: example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Length: 192
Content-Type: application/json; charset=UTF-8
ETag: "3bf6fbc90e11b3c2cc30acb534b452ea"
Vary: Accept,Accept-Language

{
    "title": "Screenshot of the problem",
    "shortTitle": "screenshot.png",
    "smallPreview": {
        "document": "http://example.com/bugs/324/screenshot?preview=small"
    }
}

Servers can also return a Link header in response to successful requests that create resources. This allows the client to get the Compact resource URI for new resources without making additional requests. Note that servers set the Link context using an anchor parameter if the request URI is not the same as the newly-created resource URI.

POST /bugs HTTP/1.1
Host: example.com
Content-Length: 153
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .

<>      a              <http://example.com/ns#Bug> ;
        dcterms:title  "Something went wrong" .

HTTP/1.1 201 Created
Content-Length: 0
Link: <http://example.com/bugs/478?compact>; rel="http://open-services.net/ns/core#Compact"; anchor="http://example.com/bugs/478"
Location: http://example.com/bugs/478

Discovering Compact Resources Using the HTTP Prefer Header

Clients can request a Compact resource by making an HTTP GET request to the target resource's URI using the return=representation preference of the HTTP Prefer request header [[RFC7240]] and include parameter [[LDP]] value http://open-services.net/ns/core#PreferCompact. Servers supporting resource preview must support this method of discovery for resources with RDF or JSON representations.

GET /bugs/324 HTTP/1.1
Host: example.com
Accept: application/json
Prefer: return=representation; include="http://open-services.net/ns/core#PreferCompact"

If the provider supports a preview for this resource and the request is successful, the response includes the Compact resource in its body.

The response content type is negotiated using the HTTP Accept request header. If the negotiated content type is application/json, the response body is a JSON object. The top-level JSON object has a compact property whose value is the JSON object describing the Compact resource in . The JSON may include other properties.

HTTP/1.1 200 OK
Content-Length: 315
Content-Type: application/json; charset=UTF-8
ETag: "f9d76afe5fbed1655c5768906db8958a"
Preference-Applied: return=representation
Vary: Accept,Accept-Language,Prefer

{
    "compact": {
        "title": "324: Need a fix <em>NOW</em>",
        "icon": "http://example.com/icons/defect.jpg",
        "largePreview": {
            "document": "http://example.com/bugs/324?preview=large",
            "hintHeight": "250px",
            "hintWidth": "400px"
        }
    }
}

Services may including a JSON-LD context in an application/json response. Clients who prefer RDF should request text/turtle or application/ld+json using the HTTP Accept request header, rather than application/json.

HTTP/1.1 200 OK
Content-Length: 788
Content-Type: application/json; charset=UTF-8
ETag: "d53d19be87fa9c61043c70bd91413dab"
Preference-Applied: return=representation
Vary: Accept,Accept-Language,Prefer

{
    "@id": "http://example.com/bugs/324",
    "@type": "http://example.com/ns#Bug",
    "@context": "http://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/specs/contexts/preview.jsonld",
    "compact": {
        "@id": "http://example.com/bugs/324?compact",
        "@type": "http://open-services.net/ns/core#Compact",
        "title": "324: Need a fix <em>NOW</em>",
        "shortTitle": "324",
        "icon": "http://example.com/icons/defect.jpg",
        "iconTitle": "Defect",
        "iconAltLabel": "Defect",
        "largePreview": {
            "document": "http://example.com/bugs/324?preview=large",
            "hintHeight": "250px",
            "hintWidth": "400px"
        },
        "smallPreview": {
            "document": "http://example.com/bugs/324?preview=small"
        }
    }
}

Displaying Previews

When displaying a preview inside another HTML-based presentation, clients create an iframe element, setting its src attribute to the preview's document URI. Previews can contain HTML, stylesheets, and scripts and might not render properly outside of an iframe. Using the iframe element also sandboxes the preview, avoiding cross-site scripting vulnerabilities.

Preview iframe

Typically, the server does not include the icon or title in the preview itself. The client can display these as needed. In , the preview document is the content inside the yellow, dashed lines.

Resources can have both a small and large preview, and clients can choose which to display. Some clients display the small preview initially and let users expand to the large preview using a button or "Show more" link.

The Compact resource can include oslc:hintHeight and oslc:hintWidth properties for each preview. Values for oslc:hintWidth and oslc:hintHeight are expressed in length units specified in [[CSS21]].

Servers can also request dynamic resizing for small and large previews. The communication of dynamic size information happens within a web browser. _javascript_ code running in the preview iframe sends a message that is received and acted upon by _javascript_ code running in the iframe's parenting window. This cross-frame communication is done using HTML 5 postMessage. Dynamic resizing will not work inside browsers that do not support postMessage.

A resize message begins with oslc-resize: followed by a JSON object describing the dimensions using properties oslc:hintHeight and oslc:hintWidth.

JSON Property Name	Type	Occurs	Description
oslc:hintHeight	String	Zero-or-one	Preferred height of the preview. Values are expressed using length units as specified in [[CSS21]].
oslc:hintWidth	String	Zero-or-one	Preferred width of the preview. Values are expressed using length units as specified in [[CSS21]].

For example, the following message requests that the preview be resized to height of 277 pixels and a width of 400 pixels.

    oslc-resize:{"oslc:hintHeight": "277px", "oslc:hintWidth": "400px"}

The following _javascript_ example sends a resize request to the parent window.

var size = {
    'oslc:hintHeight': '277px',
    'oslc:hintWidth': '400px'
};

if (window.postMessage && window.parent)  {
    window.parent.postMessage('oslc-resize:' + JSON.stringify(size), "*");
}

Clients can ignore a server's size hints and use other values. For instance, a client might choose another size if the preview is too large for the window.

Implementation Conformance

General

Servers MAY choose to provide Compact resources for some resources and not others.

Resources with previews MUST support the HTTP OPTIONS method.

In responses to HTTP GET requests targeting resources that have a Compact resource, servers SHOULD either include a Vary response header with at least Accept and Prefer field values or a Cache-Control header value no-store.

Servers MAY consult the Accept-Language header on requests for a Compact resource (and on requests for preview documents) to return a resource for the requested natural language.

Clients SHOULD gracefully handle unsuccessful attempts to use previews. Previews may not be supported for all resources or may not work due to security or service availability issues.

Link Headers

In responses to successful HTTP requests for a target resource that has a Compact resource, servers MUST include a Link header [[!RFC5988]] where

• The context URI is the effective request URI,
• The link relation is http://open-services.net/ns/core#Compact, and
• The target URI is the URI of the Compact resource.

Link: <http://example.com/bugs/324/screenshot?compact>; rel="http://open-services.net/ns/core#Compact"

If a newly-created resource has a Compact resource, servers MAY return a Link header in response to the creation request where

• The context URI is the URI of the newly-created resource,
• The link relation is http://open-services.net/ns/core#Compact, and
• The target URI is the URI of the associated Compact resource.

Link: <http://example.com/bugs/478?compact>; rel="http://open-services.net/ns/core#Compact"; anchor="http://example.com/bugs/478"

Prefer Headers

Clients MAY request that the Compact resource is returned inline with the target resource using the Prefer request header [[!RFC7240]] and

• Preference return, value representation
• Parameter include [[!LDP]], value http://open-services.net/ns/core#PreferCompact.

Prefer: return=representation; include="http://open-services.net/ns/core#PreferCompact"

Servers MUST honor a client's request to inline the Compact resource in JSON and RDF representations if the target resource has a Compact resource and the request is successful.

If the target resource does not exist or is not accessible to the requesting client, servers MUST return the same status code that it would have returned had the client not included the Prefer header in the request.

When servers inline the Compact resource with the target resource in an application/json [[!RFC4627]] response, the response entity MUST be a JSON object with a compact property where the value is the Compact resource JSON as described in .

Servers MAY choose to return only a subset of the target resource properties when a client requests that the Compact resource is returned inline.

Clients SHOULD inspect the response body for the Compact resource even if the server omits the Preference-Applied header [[!RFC7240]].

Compact Resources

Servers MUST support the application/json [[!RFC4627]] and text/turtle [[!turtle]] media types for the Compact resource.

Servers SHOULD support the application/ld+json media type [[JSON-LD]] for the Compact resource.

The application/json Compact resource representation MUST be in the JSON format described in .

Servers MAY respond with JSON-LD in compacted document form when clients request the application/json representation of the Compact resource as long as the response meets the requirements for the JSON representation.

RDF representations of the Compact resource MUST conform to the shape specified in .

The Compact resource MAY have additional server-specific properties.

Previews

When displaying a preview inside another HTML presentation, clients MUST use an iframe element, setting its src attribute to the preview's document URI.

Servers MUST express the oslc:hintWidth and oslc:hintHeight properties of an oslc:Preview in length units as specified in [[!CSS21]].

Servers MAY use dynamic resizing for small and large previews in addition to oslc:Preview oslc:hintHeight and oslc:hintWidth properties.

Servers that support dynamic sizing MUST send resize messages to the parent window using the Window.postMessage method [[!webmessaging]] where the source of the event is the preview's window.

A resize message MUST consist of the characters oslc-resize: followed by a JSON object with at least one of the following properties:

• oslc:hintHeight or
• oslc:hintWidth.

oslc-resize:{"oslc:hintHeight": "277px", "oslc:hintWidth": "400px"}

The oslc:hintHeight and oslc:hintWidth property values in the resize message JSON MUST be length units as specified in [[!CSS21]].

Servers MAY send more than one dynamic resize request.

Clients MAY choose to ignore the size hints in oslc:Preview resources or in dynamic resize messages.

Resources

Resource: Compact

Resource: Preview

JSON Representation Format

A Compact resource JSON representation might look like the following for the target resource http://example.com/bugs/324:

{
    "title": "324: Need a fix <em>NOW</em>",
    "shortTitle": "324",
    "icon": "http://example.com/icons/defect.jpg",
    "iconTitle": "Defect",
    "iconAltLabel": "Defect",
    "largePreview": {
        "document": "http://example.com/bugs/324?preview=large",
        "hintHeight": "250px",
        "hintWidth": "400px"
    },
    "smallPreview": {
        "document": "http://example.com/bugs/324?preview=small"
    }
}

The JSON representation has the following constraints:

• The value of the title or shortTitle properties MUST, if present, only contain markup valid in an HTML span element. To afford clients the greatest flexibility to style the text to match the context in which it is being displayed, the titles SHOULD be plain text with HTML markup used only to emphasize words or phrases or to convey additional information about the target resource.
• icon, if present, MUST be the URI of an image. The image SHOULD be square. A client MAY scale the image as needed.
• iconAltLabel and iconTitle, if present, MUST only have string content with no markup.
• smallPreview and largePreview, if present, MAY have any number of properties, including none.
  • The value of smallPreview and largePreview, if present, MUST be the JSON representation of an oslc:Preview.
    • A Preview MUST include a document property. It MAY have any number of other properties.
    • document MUST be the URI of a document containing a preview of the resource.
    • hintWidth and hintHeight, if present, MUST be expressed using length units as specified in [[CSS21]].

JSON-LD Context

The following JSON-LD Context may be used with JSON Compact representations.

JSON Schema

The following JSON Schema [[JSONSchema]] describes the Compact JSON representation.

Terms

This section highlights the new RDF vocabulary terms defined in this specification.

Change History

Below is a summary of some of the changes in this draft

• 2015-03-19 Add JSON Schema for Compact JSON. (SP)
• 2015-03-06 Require HTTP OPTIONS support for resources with preview and only require Link headers on successful responses. (SP)
• 2015-03-05 Recommend Vary only if Cache-Control header is not set to no-store. (SP)
• 2015-03-04 Allow Cache-Control in place of Vary (6.1.2). (SP)
• 2015-02-20 Refine section 6.1.4 wording. (SP)
• 2015-02-13 Add example preview images. (SP)
• 2015-01-29 Add titles to examples. (SP)
• 2015-01-28 Create Implementation Conformance section with conformance clauses. (SP)
• 2014-12-09 Generate terms from RDF vocabulary. (SP)
• 2014-12-09 Generate shape tables from RDF resource shapes. (SP)
• 2014-12-04 Shorten spec title. (SP)
• 2014-12-04 Include example JSON-LD context from a separate file. (SP)
• 2014-09-09 Move some statements on preview sizing to guidance document. Allow Consumers to ignore a Provider's size hints. (SP)
• 2014-09-08 Reorder some document sections. (SP)
• 2014-09-08 Restore the iframe requirement for displaying previews. (SP)
• 2014-09-08 Remove statement on backwards compatibility since it will be moved to a separate committee note. (SP)
• 2014-09-05 Add additional informative descriptions of how previews work and give more guidance on when to use Link or Prefer discovery. (SP)
• 2014-09-05 Move "Resources" section near the bottom. (SP)
• 2014-09-04 Move "Displaying a Preview" sections to non-standards track committee note. (SP)
• 2014-09-02 Recommend adding Accept-Language to the Vary response header when appropriate. (SP)
• 2014-09-02 Remove some unnecessary response headers to simplify examples. (SP)
• 2014-09-02 Include anchor in Link response header for POST example. (SP)
• 2014-08-29 Clarify use of Preference-Applied and Link headers. (SP)
• 2014-08-26 Discuss preview for resources with no RDF. (SP)
• 2014-08-21 Use Prefer: return=representation with an include parameter instead of type=oslc-compact. (SP)
• 2014-08-20 Start to convert to respec-style references. (SS)
• 2014-08-19 Add sections for separate terms and shapes, also propose doc structure changes. (SS)
• 2014-08-18 Add a minimal JSON example. (SP)
• 2014-08-15 Update Prefer discovery method and use oslc:resize. (SP)
• 2014-05-01 Use ReSpec. (SP)
• 2014-03-28 Initial draft. (SP)

Acknowledgments

The editors would like to thank to OSLC Core Technical Committee for contributions and feedback, especially John Arwe for his thorough review. This specification is based on [[OSLCUIPreview20]], authored by Scott Bosworth.