Nick, As I recall, in the CM space this high degree of variability led to the inclusion of Web UI integration components in the spec. The justification was that since the CM systems varied so much, it was not practical to standardize the required resource format, so it was delegated to the native UI of the tool. It sounds like you are trying to create a generic UI that would work with any CM service. If you think Resource Shapes can solve that problem, great. However there will be a limit to what you can describe. We could easily be led down the road of creating another XForms.
Regards, ___________________________________________________________________________ Arthur Ryman, PhD, DE Chief Architect, Project and Portfolio Management IBM Software, Rational Markham, ON, Canada | Office: 905-413-3077, Cell: 416-939-5063 Twitter | Facebook | YouTube From: Nick Crossley <[email protected]> To: oslc-core <[email protected]> Date: 05/06/2010 04:00 PM Subject: Re: [oslc-core] Guidelines for specifying future-proof resources/capabilities Sent by: [email protected] But at least for CM, the spec cannot help! Most CM systems are highly configurable, so the set of required properties varies from site to site, not just between providers. A client wanting to create a change request needs to be able to discover the set of required properties in a particular installation - that is, if we are trying to allow for such generic clients. As in many other recent discussions, it all comes back to the scope of OSLC - what are we really trying to achieve? Nick. -----Arthur Ryman <[email protected]> wrote: ----- To: Nick Crossley/Irvine/IBM@IBMUS From: Arthur Ryman <[email protected]> Date: 05/06/2010 12:42PM Cc: oslc-core <[email protected]>, [email protected] Subject: Re: [oslc-core] Guidelines for specifying future-proof resources/capabilities Nick, Perhaps the real point here is how much information we should try to put in the resource shape descriptions. In general, any operation on a resource will have a set of pre-conditions, e.g. that some properties be present or satisfy some condition. We could describe some simple ones in the shape, but at some point we'd have to tell consumers to read the spec. Having a lot of variant shapes could get out of hand quickly. The shape should describe necessary, but perhaps not sufficient, pre-conditions. So in your multiple creation example, you could have a very generic shape with lots of optional properties, and the consumer would have to read the spec to determine which ones were required in any given state. Regards, ___________________________________________________________________________ Arthur Ryman, PhD, DE Chief Architect, Project and Portfolio Management IBM Software, Rational Markham, ON, Canada | Office: 905-413-3077, Cell: 416-939-5063 Twitter | Facebook | YouTube From: Nick Crossley <[email protected]> To: oslc-core <[email protected]> Date: 05/06/2010 01:34 PM Subject: Re: [oslc-core] Guidelines for specifying future-proof resources/capabilities Sent by: [email protected] I'm not sure it is a simple as that. For example, in Change, different properties of a change request resource are required at different stages of its life cycle. Some are required on creation, some are required in later states. Even the set required on creation can vary: one of my colleagues just described the way he needs to describe required attributes during creation in Rational Change: In Change, we can submit new CRs to different states. Each state may have different required attributes to create the CR. I think it would be modeled like this in OSLC 2: - Each state we can submit to has a different creationFactory URL (e..g., /oslc/crfactory/START_HERE2entered, /oslc/crfactory/START_HERE2assigned). - Each factory has as associated shape URL. - Requesting the "shape" returns XML describing how to POST to that URL including an element for each attribute that can be submitted. - Each attribute description has an "occurs" element. For required attributes, this would be set to "exactly-one". Many of these required properties are still editable - they are not system-supplied. For example, the name of the person to whom the change request is currently assigned is modifiable, but is required when creating a CR in the assigned state. Note that the shape for query has to be different from both of the shapes he described above - since life cycles and process requirements can change leaving older objects with a slightly different set of properties, and since objects can change state allowing some properties to be deleted, there can be very few "exactly-one" required attributes for a query shape - almost all would have to be optional. Nick. [email protected] wrote: ----- To: Dave <[email protected]> From: Arthur Ryman <[email protected]> Sent by: [email protected] Date: 05/06/2010 06:30AM Cc: oslc-core <[email protected]>, [email protected] Subject: Re: [oslc-core] Guidelines for specifying future-proof resources/capabilities Dave, I think the spirit of REST is that you create via PUT or POST and that GET is more or less the inverse of PUT. The only exception is that when you GET the resource, it may have acquired some additional properties, e.g. creator, creation date, an identifier, etc. The way I was distinguishing these in the EMS spec is via the editability of the property, not its occurrence. The properties that are maintained by the service are read-only and they should not be provided on creation since they are generated by the system. Normal properties are read-write. You could also imagine write-once properties that you only set on creation and that cannot be changed later. Given that we can distinguish client-provided (read-write) versus system-generated (read-only) properties, then there should be no need to have different creation and query resource shapes. Regards, ___________________________________________________________________________ Arthur Ryman, PhD, DE Chief Architect, Project and Portfolio Management IBM Software, Rational Markham, ON, Canada | Office: 905-413-3077, Cell: 416-939-5063 Twitter | Facebook | YouTube From: Dave <[email protected]> To: oslc-core <[email protected]> Date: 05/06/2010 08:04 AM Subject: [oslc-core] Guidelines for specifying future-proof resources/capabilities Sent by: [email protected] re: Specification versioning I'm still working representations today, but I've been thinking more about the guidance that we should provide in Core spec to help workgroups specify "future proof" resources. The rule * A new version of an OSLC specification is not allowed to introduce changes that will break old clients. The guidelines For OSLC workgroups, these are some guidelines to help you live with the above rule and specify OSLC resources that are as future-proof as possible. 1) Think you need a property but cannot agree on the value-type? This is a strong indication that you should not attempt to standardize on the property. Once decide on a value-type you are stuck with it forever. Wait until you have the scenarios or implementation experience needed to agree upon a value-type. 2) When introducing a new capability, e.g. a creation factory, query capability or delegated UI dialog; one that works differently than those specified in the Core spec or older versions of your own spec, you should create a new resource type to represent the service. This will enable old clients to continue to work against old services and new clients to work with your new capabilities. 3a) When defining resources, you are not allowed to remove, change the meaning or the value-type of any properties that you defined in earlier versions of the specification. You can add new properties but not change those that already exist. 3b) When defining resources, consider which ones are required to provided by clients at creation or update time vs. those which are required to be in representations returned by the server. When creating a new version of a specification: it's OK to relax restrictions on clients but it is not OK to add new required properties because that will break old clients. ISSUE: we should pick either 3a or 3b. At this point, I think 3b seems more reasonable and gives workgroups some more leeway in making changes, but... ISSUE: how can we enable 3b? Do we recommend that OSLC domains provide different shapes for creation vs. query? Do we require that domains specify two ""occurs" values for each property: oslc:creationOccurs and oslc:queryOccurs? Does this overlap with the oslc:queryable value that we discussed yesterday? I'd like to write this up (and the rest of the changes in http://open-services.net/bin/view/Main/OslcCoreMeetings04302010) this week, so any feedback, comments, suggestions, etc. you might share are all most welcome. Thanks, - Dave _______________________________________________ Oslc-Core mailing list [email protected] http://open-services.net/mailman/listinfo/oslc-core_open-services.net _______________________________________________ Oslc-Core mailing list [email protected] http://open-services.net/mailman/listinfo/oslc-core_open-services.net _______________________________________________ Oslc-Core mailing list [email protected] http://open-services.net/mailman/listinfo/oslc-core_open-services.net _______________________________________________ Oslc-Core mailing list [email protected] http://open-services.net/mailman/listinfo/oslc-core_open-services.net
