History   View   Links to this page 2013 November 6 | 11:09 am

This page contains a proposed change to Exposing arbitrary actions on RDF resources, as an incremental change/alternative to Actions 2.0 with nil body profile ( Compare ), which itself was an incremental change to Actions 2.0 with profile rules ( Compare ).

Key section: Implementation profiles

OSLC_logo.png

Open Services for Lifecycle Collaboration
Actions Specification Version 2.0

Status: Drafting

This Version

Latest Version

Previous Version

  • This is the first version of this specification.

Authors

  • John Arwe (IBM, OSLC-Core)
  • Martin Pain (IBM, OSLC-Automation Lead)
  • Samuel Padgett (IBM, OSLC-Change-Management Lead)
  • SteveSpeicher (IBM, OSLC-Core Lead)

Contributors

Table of Contents

Contents

TODO

  • Include http vocab’s headers property or not?
  • Discovering Actions on resources that don’t exist yet
    • From Resource Shapes & Automation Plans
  • Bring to Core WG for formal feedback (likely as companion to Automation spec, since Automation’s schedule is tighter than CM’s)

Notation and Conventions

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 RFC2119. Domain name examples use RFC2606.

Terminology

Action - a machine-readable hypermedia that describes an action, like start or stop, that can be used to operate on a resource at a level of abstraction suitable for human and/or programmatic consumption

Implementation profile - a named, constrained re-use of this specification in a specific domain, like Change Management or Automation. The additional constraints simplify the range of code clients are required to implement, making it cheaper and easier to adopt.

Implementation (of an Action) - the means of executing that action. Each currently available action can have one or more implementations, which MAY support different profiles. could be called “instructions” instead. Technically I see two concepts – the “implementation of an action” which is the endpoint you hit and the code behind it, and the “instructions [for constructing an HTTP request] to execute a specific implementation of an action”, which is the http:Request resource (but may be of other types in some cases).

Profile identification rule - a rule specified by an implementation profile that can be used to determine if an action’s implementation supports that profile.

Overview (informative)

At a high level:

  • Scenarios are listed on separate page.
  • A domain specification re-uses actions. In the process, it requires at least one particular implementation profile to serve as a basis for interoperability between clients and providers of that domain. It might define new actions and implementation profiles beyond what Core defines.
  • Providers in that domain annotate resources with actions, as described in and/or constrained by the domain specification.
  • Clients discover available actions on existing resources.
    • Domain-specific clients (the normal case) do so as described in and/or constrained by the domain specification; they need to understand whatever implementation profile(s) the domain specification requires in order to successfully invoke its actions.
    • Generic (cross-domain) clients might rely only on Core Actions (this specification), and be able to display and/or invoke actions from many resource types and implementation profiles.

Domain-specific clients

The first-order concern of domain specifications is clients written to that specification. The process such a client would follow to find resources with actions it is capable of consuming is:

  • Decide what the set of interesting resources is. It might be one or many, depending upon the usage scenario.

  • For each interesting resource:

    • Find potentially consumable actions by looking for the actions:action predicate on the resource

    • For each potentially consumable action

      • Determine if any of the action’s implementations match the profile identification rule for any of the implementation profiles understood by the client. (The set of profiles understood by the client MUST, as a minimum, include the profile(s) required by the domain specification(s) it is written against.)
  • Do whatever the client is coded to do.

The process such a client would follow to execute any action it is capable of consuming is to form and make an HTTP request. The instructions for forming and making the request are found by following actions:request link(s) and examining the target resources.

  • Start with the implementations that were identified during the find stage, for the appropriate action. (If that stage was not performed, perform it now solely on this action.)
  • If the action specifies implementations for more than one of the implementation profiles that are understood by the client (or more than one implementation that matches one of those profiles), choose one using whatever criteria the client prefers.
  • Form the HTTP request from the contents of the http:Request resource.
  • Follow the interaction pattern for the implementation profile.

Note: no mention is made of how many HTTP requests are required, since that is implementation-dependent. Best practices suggest minimizing them, especially when UI presentation performance is important.

Providers

The second-order concern of domain specifications is providers written to that specification. The process such a provider would follow to expose resources with actions its domain-specific clients are capable of consuming is:

  • Decide what the set of interesting resources is.
    • The most likely case is resources owned/exposed by the provider itself.
  • For each interesting resource:
    • Find any existing actions that the provider can add a new implementation of
      • The set of rdf:types on the action is identical to the provider’s action to be exposed, I don’t like this, as you may have two actions both identifying themselves as StopActions, but which are not semantically equivalent – one may be more like a “pause” while one may be more like a “delete”. I think we can only have the “semantically equivalent” multiple implementations when the same provider is providing both and knows for sure they are equivalent.
      • or (if applicable) the existing implementations are semantically equivalent to the provider’s action to be exposed, where equivalence is defined by the code that defined the actions or implementations.
    • Add the provider’s action to be exposed, either as a new implementation (actions:request) link or as a new action (actions:action) link.

Generic or cross-domain clients

Domain specifications often care little about clients not written to that particular specification, beyond adhering to basic HTTP and Linked Data principles. Core specifications, in effect, enable cross-domain clients.

The process such a client would follow to find resources with actions it is capable of consuming, and executing those, is the same as for a domain-specific client, but without the limitations on domain and/or implementation profile. A generic client could, for example, look at all actions (actions:action predicates) across a set of resources, present those to a user, and let the user select one or more to invoke. The only restriction on the set of implementation profiles is the set of those understood by the client code, since there is no single domain specification involved.

Description

Re-use by domain specifications

Domain specifications re-using this specification SHOULD make their readers aware of Best Practices for representing actions and their related resources.

Domain specifications re-using this specification MUST require at least one implementation profile for interoperability within the target domain. They MAY use any implementation profile defined here, or they MAY define new implementation profile(s).

Domain specifications re-using this specification MAY add new constraints beyond the ones here. Domain specifications re-using this specification MUST NOT weaken absolute constraints (MUST, MUST NOT) in this specification.

Discovering the actions applicable to a resource

Any resource MAY link to any number of Actions, using the actions:action predicate as shown below. The actions:action predicate links to currently available actions, i.e. it lists actions that the provider asserts are currently available for execution by clients at the time the representation was formed. In a distributed system, clients can lose race conditions that result in an “available”-appearing action execution requests being rejected.

Action resources MAY be represented as either blank nodes or separate resources, and when separate either hash or non-hash URIs MAY be used.

Actions-Finding-Actions-From-Resources.png

Types of actions

Action types are identified by rdf:type values, e.g. actions:DeleteAction, actions:StopAction, which SHOULD all be sub-classes of actions:Action. Since informal OSLC Core guidance states that providers must not depend upon client-side inferencing, action representations are multi-typed: they MUST contain actions:Action as one type, and MAY (usually do, in practice) contain additional types that convey more specific semantics more useful for programmatic consumption. The additional type URIs MAY belong to any vocabulary or namespace, however it is RECOMMENDED that working groups in need of new types consult with Core before defining new actions outside the Core namespace. Widely applicable action profiles SHOULD be allocated (by the Core working group) within the Actions vocabulary.

Instructions for executing actions

Each Action linked to by an actions:action predicate MUST contain one or more actions:request predicates, each of which links to a resource containing instructions (the “implementation”) for creating the HTTP request, such as the HTTP request resource (http:Request) shown below. An action is executed by constructing the described HTTP request and sending it to the appropriate server, in accordance with the definition of the implementation profile in use. This specification permits the use of resources with types other than http:Request for future extensibility, but it assigns them no meaning and when they are used interoperability will be reduced. Clients MUST tolerate other resource types, but MAY ignore them.

Actions-Request-Linkage.png

Request resources MAY be represented as either blank nodes or separate resources, and when separate either hash or non-hash URIs MAY be used.

Each implementation (e.g. http:Request resource) describes an HTTP request that can be made by the consumer to perform the action. Each of the implementations (e.g. http:Request resources) linked to from a single Action MUST be semantically equivalent - they are different means of achieving exactly the same thing. If the implementation is an http:Request resource, the URL to which the HTTP request will be made is specified via the http:requestURI predicate, the HTTP method (e.g. POST, PUT, or PATCH) that MUST be used is specified via the http:mthd predicate, and anything else necessary for the client to construct the request MUST be specified, such as required headers or a request body. The concrete instructions for constructing the HTTP request are defined by the implementation profile in use.

Implementation profiles

In order to encourage interoperability, this specification lists a small number of implementation profiles that domain specifications have defined and? SHOULD re-use. These describe coherent subsets or extensions of Actions’ general capabilities. In this context, re-using a profile means that the domain specifications MUST require that the Actions provided by providers written against that domain MUST support that profile. Supporting a profile means at least one implementation of the Action MUST adhere to the profile’s restrictions.

Each implementation profile (whether defined in this specification or future extensions) MUST specify:

  • An “implementation identification rule”, which clients use to determine if an implementation supports this implementation profile, if any. New implementation profiles SHOULD take into account potential future extensions or changes, and form the rule in such a way that future backward-compatible changes will still match the original rule, but that backward-incompatible changes will not. In other words, new profiles should consider how to break this rule when future incompatible changes are made to the profile. This SHOULD solely check a flag (such as an rdf:type value) that is present solely to identify the supported profile.
  • Instructions on how to construct the HTTP request and the interaction pattern used to execute the action.

POST RDF described by a OSLC Resource Shape to the Action resource

This is an extension of the POST empty body to a specified URL profile. All consumers who support this profile MUST also support that profile, to support the situation where no parameters are required.

Implementation identifier rule

An implementation is compatible with this profile if it has an rdf:type value of actions:BasicResourceShapeAction.

Provider restrictions

This profile uses the POST empty body to a specified URL profile with the following modifications:

This profile uses Core Actions with the following restrictions:

  • The actions:requestURI object MUST be the URL of the Action resource that links to it.
  • The http:mthd object MUST be http-methods:POST.
  • Advertising input parameters is OPTIONAL
  • When input parameters are advertised, they MUST be described using the actions:requestBodyParameters predicate, with an object whose type is oslc:ResourceShape
  • When input parameters are not advertised the actions:requestBodyParameters predicate MAY have a value of rdf:nil.
Execution (consumer restrictions)

The request is to be constructed and submitted as in the Core Actions Domain specific clients and Instructions for executing actions sections, with the following modifications:

  • When input parameters are advertised, they MUST be supplied as RDF in the HTTP request body, unless the following condition applies.
  • If a resource shape is used to advertise input parameters, and the shape indicates that all parameters are optional (all have a min-occurs constraint value of zero), then the client MAY omit the request-body entirely, i.e. it can send a request whose HTTP Content-Length header has a value of 0 (zero).
  • If the actions:requestBodyParameters predicate has a value of rdf:nil, then the client MUST omit the request-body entirely, i.e. it will send a request whose HTTP Content-Length header has a value of 0 (zero).

Image:Actions-Parameters-Resource-Shape.png

Known adopters of this profile:

  • OSLC Change Management 3.0(???) - anticipated; add link to example usage. Expected to provide inference rules to produce RDF that supports this profile from a reduced set of properties provided by the providers.

Create an Automation Request

Implementation identifier rule

An implementation is compatible with this profile if it has an rdf:type value of actions:AutomationPlanAction.

Provider restrictions

This profile uses Core Actions with the following restrictions:

  • The actions:requestURI object MUST be the URL of an Automation Request creation factory capable of accepting as input a creation request formed according to the http:Request’s instructions.
  • The http:mthd object MUST be http-methods:POST.
      • The actions:requestBodyParameters predicate MUST be present, with an object whose type includes oslc-automation:AutomationPlan. The Automation Plan’s oslc-automation:parameterDefinition links describe any required/optional parameters.

  • Domain specifications using this profile SHOULD specify at least one specific version of the OSLC Automation specification that clients are required to support, to establish a concrete base for interoperability.

Execution (consumer restrictions)
  • Clients MUST construct an Automation Request as defined in an OSLC Automation specification, and SHOULD POST it to the actions:requestURI link target. Clients MAY use delegated dialogs to accomplish creation; this profile does not define how clients would locate an appropriate dialog, but existing OSLC links could be used.

wrt: this profile does not define how clients would locate an appropriate dialog, but existing OSLC links could be used.

SHOULD this spec show/define how the linkage is made? Does CM need this?

Image:Actions-Parameters-Automation-Plan.png

Known adopters of this profile:

  • OSLC Automation 2.1 - anticipated; add link to example usage

Parameters

Add: SHOULD provide a zero-parameter option

Not all actions need (or accept) input parameters. For those that do, client code needs a way to find parameter descriptions, and it might need to solicit values from a human. Core Actions defines the optional actions:requestBodyParameters predicate as the way for clients to locate optional and/or required parameters when they exist, and re-uses existing OSLC mechanisms for describing those parameters. The actions:requestBodyParameters predicate links to a resource that describes the parameters; Core Actions defines the behavior of oslc:ResourceShapes and oslc-automation:AutomationPlans for describing parameters, but permits other resources for future extensibility. When other resources are used, Core Actions assigns them no meaning and interoperability will be reduced. Clients MUST tolerate other resource types, but MAY ignore them.

  • oslc:ResourceShapes are used when the parameters are RDF triples; the Core Resource Shape specification is used without modifications.
  • oslc-automation:AutomationPlans are used when the parameters are name-value pairs, and the names are unqualified by a namespace. Clients use oslc-automation:parameterDefinition links in the oslc-automation:AutomationPlan to introspect information about the parameters, and instantiate them as oslc-automation:ParameterInstances as described in the OSLC Automation specifications.
  • rdf:nil MAY be used to explicitly tell clients that no parameters are permitted.

The absence of an actions:requestBodyParameters predicate on a http:Request resource conveys no information about parameters. Loosely coupled clients have little practical choice but to interpret this to mean that no parameters are permitted.

Resources

This section defines the resources of the Actions specification. Providers MUST support Turtle (i.e., text/turtle) representations of these resources. Providers MAY provide representations beyond those necessary to conform to this specification, using standard HTTP content negotiation. If the client does not indicate a preference, text/turtle MUST be returned.

Actions Namespace

The namespace used for resources and properties defined in this specification is as follows:

  • Namespace URI: http://open-services.net/ns/core/actions#
  • Default Prefix: actions

Other namespaces

This specification re-uses content from namespaces defined by other specifications. This specification assumes the following mappings from prefixes to namespaces, in addition to those suggested in OSLC Core.

| Prefix | Namespace * | ——– | ——– | http | http://www.w3.org/2011/http# | http-methods | http://www.w3.org/2011/http-methods#

Resource: Action

Action Properties

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Core: Common Properties
dcterms:title exactly-one unspecified XMLLiteral n/a n/a Title (reference: Dublin Core) of the resource represented as rich text in XHTML content.
dcterms:description zero-or-one unspecified XMLLiteral n/a n/a Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content. SHOULD include only content that is valid and suitable inside an XHTML <div> element.
rdf:type One or many unspecified Resource Reference n/a The resource type URIs. At least one type MUST be actions:Action.
OSLC Actions: Start of additional properties
actions:request 1:* unspecified Resource Either Any Instructions for executing the action. It is likely that the target resource will be an http:Request but that is not necessarily the case. Multiple occurrences of this property MUST be different ways of achieving the same operation; they are semantically the same, but achieved through different data or technologies.

Action types

These are notionally subtypes of actions:Action, but whenever they are used rdf:type SHOULD be multi-valued, with both actions:Action and the sub-type(s), to avoid requiring clients to infer the actions:Action triple. e.g:

< http://example.com/sa/2314?stopREST > a actions:Action, newns:StopAction ;     # This

< http://example.com/sa/2314?stopREST > a                 newns:StopAction ;     # NOT this

These subtypes are used to identify different types of actions:

  • actions:StopAction - stops something that is executing
  • actions:DeleteAction - deletes a resource. (This is MAY point to a DELETE call to the resource (although it does not have to), but advertises this to consumers who are looking at Actions.)
  • actions:ChangeStateAction - changes some “state” property of a resource (or any other property)

Proposal note: This list is still wide open for discussion. I suggest we define these for now.

Link to vocabulary document; explicitly say that types might be added w/o updating this spec, give some way to dynamically find the current list if practical.

We mention that DeleteAction might “point” to DELETE “call”, but at this point we only have profiles for POST implementations.

Property: actions:action

In addition to resource definitions, this specification defines one property below that can occur in any RDF resource. This property is defined to be a well-known way of finding available actions on any resource. Resource types may want to specify their own property/ies instead, but this one is defined as a sensible default.

Proposal note: We propose that this goes in Core’s “common properties” appendix

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Actions: Start of additional re-usable properties
actions:action 0:* unspecified Resource Either Any An action currently available on the subject resource. It is likely that the target resource will be a actions:Action, but that is not necessarily the case.

Resource: Request

Note: this resource is re-used by Actions, not defined by Actions.

  • Name: Request
  • Description: A Request provides a representation of an HTTP request. (Reference: HTTP in RDF)
  • Type URI: http://www.w3.org/2011/http#Request

Request Properties

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Actions: Start of additional properties
http:requestURI 1:1 unspecified Resource Ref Any HTTP Request-URI for the request. (Reference: HTTP 1.1)
http:mthd 1:1 unspecified Resource Ref Any HTTP method for the request. The target resource SHOULD come from the http-methods vocabulary. Many clients are likely to support only widely used methods such as POST.
actions:requestBodyParameters 0:1 unspecified Resource Either Any Parameters executing the action. It is likely that the target resource will be a core:ResourceShape, or an oslc-automation:AutomationPlan but that is not necessarily the case.

This is defined here: http://www.w3.org/TR/HTTP-in-RDF10/#RequestClass

  • http:body (in our case, zero-or-one) - See above.

Do we still need http:body? we have it as 0:1 above.

Proposal note: We are talking to the W3C members involved in writing this vocabulary about extending http:requestURI to allow this usage.

Other parameters that may be useful include:

  • http:headers

Talk about headers? How much?

Examples

Specifying a single implementation with a simple, empty POST:

@base <http://example.com/>.
<sa/2314?stopCM30>
   a actions:Action, new:StopAction ; 
   dcterms:description "Stop the [Implicitly specified] managed resource.";
   dcterms:title "STOP";
   # This (no parameters) is the lowest common denominator form.
   # Core should encourage all Actions to provide at least this implementation alternative as a base for interop.
   actions:request [
        a               http:Request ;
        http:requestURI <sa/2314?stopCM30> ;
        http:mthd       http-methods:POST ;
        http:body       rdf:nil ; # Perform the POST with no message body
   ];
.

An automation plan is the implementation:

@base <http://example.com/>.
<sa/2314#stop3>
   a actions:Action, new:StopAction ; 
   dcterms:description "Stop the [Implicitly specified] managed resource.";
   dcterms:title "STOP";
   actions:request [
        a                         http:Request ;
        http:requestURI              <requestCreationDialog> ;
        http:mthd                    http-methods:POST ;
        actions:requestBodyParameters <stop/plan?resourceId=2314>; # Server hides resource ID within (opaque to client) URI
   ];
.

Provider exposes two alternatives, so the consumer can choose amongst those it understands:

@base <http://example.com/>.
<sa/2314#stop4>
   dcterms:description "Stop the [Implicitly specified] managed resource.";
   dcterms:title "STOP";
   actions:request [                      # One of possibly several equivalent ways to invoke the action
        a                       http:Request ;
        http:requestURI         <stop/plan> ;
        http:mthd               http-methods:POST ;
        # The addition of a non-empty body means that a Content-Type (at least) is "required"
        http:headers ( [             # :headers uses parseType=collection => an ordered list (...) in Turtle
            a               http:RequestHeader ;
            http:hdrName    http-headers:content-type ;
            http:fieldValue "text/plain";   # needs to match cnt:chars value below
        ] );
        http:body [
            a                  http-content:ContentAsText ;
            http-content:chars "...resource context is http://example.com/sa/2314 ...";
        ];
   ];
   actions:request [                      # One of possibly several equivalent ways to invoke the action
            a                            http:Request ;
            http:requestURI              <sa/2314?stopCM30> ;
            http:mthd                    http-methods:POST ;
            actions:requestBodyParameters <stop/shape>;    # Resource Shape
   ];
.

Best Practices

Minimize the number of HTTP round-trips

Actions will often be and/or link to inline resources, possibly anonymous ones (without their own URL, i.e. blank nodes). But they can be separate, addressable resources if needed. Since a client might need to retrieve Action descriptions, e.g. in a UI, in order to find the one with the correct type (if it is looking for a particular type of action), it is likely advantageous to minimize the number of HTTP round trips by returning the representation of all a resource’s actions along with the resource’s representation. The same pattern applies to actions:request target resources.

Appendix A: Samples

(this section is informative)

See samples within the body of this specificiation.

Appendix B: Resource Shapes

Not applicable

Appendix C: Notices and References

Contributors

  • John Arwe (IBM, OSLC-Core)
  • Martin Pain (IBM, OSLC-Automation Lead)
  • Samuel Padgett (IBM, OSLC-Change-Management Lead)
  • SteveSpeicher (IBM, OSLC-Core Lead)

Reporting Issues on the Specification

The working group participants who author and maintain this working draft specification, monitor a distribution list where issues or questions can be raised, see Core Mailing List

Also the issues found with this specification and their resolution can be found at Core 2.0 Issues.

License and Intellectual Property

We make this specification available under the terms and conditions set forth in the site Terms of Use, IP Policy, and the Workgroup Participation Agreement for this Workgroup.

References

Appendix D: Changes

  • Still drafting