This page contains proposed changes to Exposing arbitrary actions on RDF resources spec. Compare.
It also has a further incremental change/alternative available at Actions 2.0 with nil body profile.
Key sections: Terminology, Domain-specific clients, Implementation profiles
|
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.
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:
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.
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.
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.
- 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
Implementation identifier rule
An implementation is compatible with this profile if it is of type http:Request and it contains a triple whose predicate is actions:requestBodyParameters and whose object is either of type oslc:ResourceShape or is the value rdf:nil. Unfortunately the rdf:nil condition includes representations that other future profiles may produce. An implementation may be identified as being of this profile when actually there is another property present that ought to be considered. This rule does not produce a “clean” classification of implementations.
Provider restrictions
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 MUST be rdf:nil.
Execution (consumer restrictions)
The request is to be constructed and submitted as in the Core Actions Domain specific clients(#Domain-specific-clients) and Instructions for executing actions(#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).
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 is of type http:Request and it contains a triple whose predicate is actions:requestBodyParameters and whose object is of type oslc-automation:AutomationPlan.
Provider restrictions
This profile uses Core Actions with the following restrictions:
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 executingactions: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:
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
