This is actually a big one.
According to Michael:
Service Description is a document that defines the service for its
potential consumers and, sometimes, to its developers. This document has to
have enough business, marketing and technical information to 'win the
consumer'.
The issue here is that most of the people do not even try to
define the audience for service description and often automatically assume that
that it is targeting to developer, where in reality it targets three very
distinct audiences, each of which is looking for different sets of information.
The first line is BA, who is interested in the functional
capabilities of the service, RWE, advertized QoS and service invocation
policies He has to determine how relevant the service is for the problem that
he is trying to solve.
Depending of whether service in internal or external, Business
Affairs can look at the service provider and determine whether he is worth
partnering with. The information that they are looking for is pricing, current
amount of users, how long service has been operational, how many complaints
service has and viability of a service provider as a company
Finally technicians are concerned with the service APIs, access
methods/protocols, capacities, security requirements, etc.
As service complexity grows, it becomes not feasible to package
all this information into a single documents (it will become huge) and as a
result there can be multiple service descriptions targeted to different
audiences.
Another dimension here is service lifecycle. Description is
tightly coupled to it but the fact, that description should often appear and be
published/advertised before implementation. The reasoning here is to try to
avoid duplicate internal development and drum up interest at the market.
All these issues seem to be missing.
This said, service contract is typically a part of service
description aimed mostly at technicians and providing precise definitions of
service interfaces (APIs and protocols) and service invocation policies. Although,
technically BA’s need the same information, they would rarely look at the
service contract due to its very technical content. Forcing them to do this
will typically result in them being frustrated (try to show WSDL to a BA) and
not recommending service usage.
So I am with Michael – the two should be explicitly split
Michael,
This was written years ago. It raises an issue as directly
as possible with the realization that we weren’t going to get everyone to
uniformly use our preferred term. I’ve actually seen more movement than I
expected. However, I still think it would not be feasible to press for a
stronger statement.
Ken
---------------------------------------------------------------------------
Dr. Kenneth Laskey
MITRE Corporation, M/S
H305
phone: 703-983-7934
7515 Colshire
Drive
fax: 703-983-1379
McLean VA 22102-7508
I am sorry for bothering you
again with regard to Service Description and Service Contract. Based on the
Ken's note below (in bold), I allow myself to re-open this case.
We have several years of history
of the discussion what is the Contract and what is the Service Contract vs.
Service Description. Instead of quoting who said what and when, let me briefly
summarise my memories and understanding.
Service Description is a document
that defines the service for its potential consumers and, sometimes, to its
developers. This document has to have enough business, marketing and technical
information to 'win the consumer'. Our diagram for Service Description (Figure
15, Editors’ Draft, 17-01-2011) is rich and, probably still incomplete
because it does not include EC where the service characteristics are guaranteed
by the service provider, but it is not my point of concern for now.
Service Contract, even expressed
in the form of a bunch of Policies, is an agree subset of the Service
Description (in exceptional cases Service Contract may include Service
Description in full, i.e. Service Description may be used as a Service Contract
for such services as Security, Compliance, and alike) and combined with
some policies that the consumer has brought to the table. Nonetheless, in
essence, Service Contract is an agreed part of Service Description. For
example, if Service Description contains definition of 2 public service
interfaces - Web Servces and MOM Messaging - but the Service Contract with
Consumer C mentions only MOM Messaging, the Consumer C has no rights
to call the Web Service interface (though this interface is public too).
Any public service interface
including Web Services / WSDL is only an interface and, rhetorically, may
be called a PROGRAMMATIC COMMUNICATION contract (thanks to buzz-marketing and
Thomas Erl). I do not even attribute it to the programmatic interface because
there are no place for EC (communication and execution policies) in it.
Based on this observation, I've
spotted one place, where we are not that clear Service Contract and Service Description as we, IMO,
have to be:
1586 This Reference Architecture
Foundation uses the term service description for
1587 consistency with the concept
defined in the Reference Model. Some SOA literature
1588 treats the idea of a
―service contract‖ as equivalent to service description. In this
1589 Reference Architecturethe
SOA-RAF, the term service description is preferred.
1590 Replacing service
description with service contract implies just one side of the
1591 interaction is governing and
misses the point that a single set of policies identified by a
1592 service description may lead
to numerous contracts, i.e. service level agreements,
1593 leveraging the same
description.
IMO, we may not say "is
preferred"; we have to say that in SOA-RAF we clearly distinguish between
them (because of the many reasons one of which is partially stated in the
followed sentence). Moreover, the expression "numerous contracts, i.e. service level agreements"
is incorrect IMO because Service Contract contains much more than SLA,
particularly, business functionality, promised results, promised RWE, multiple
polices, and so on.
Since Service Description is a
part of section 4, I do not know how we would clean this potential mess...
I had a chance to look through
this and have some overall comments.
-
At line 2318, you added some words on risk but it seems strange
where placed because it’s followed by a list of benefits and then followed
again by a list of risks. Any reason your text shouldn’t be an addition
to the list of risks?
-
Need a clearer connection to having maintainable connections (not
just text to be edited) from service description to collected information
needed for management. Consumers (including those creating compositions)
need information to determine sufficiency of service considering.
Management will have an interpretation of this information but not necessarily
the final word.
-
In section 5.3, there are a bunch of short blurbs on an endless
set of manageabilities. What I get is life cycle manageability is the
ability to manage life cycles, …, X managemeability is the ability to manage
Xs. Does the elaboration through some 400 lines really add anything that
couldn’t concisely be presented as a bullet list in one page?
-
Is the term service contract used the same way as in other parts
of the document? This term has a lot of use in the vendor and user world
but little firm understanding beyond the idea that a WSDL defines an
interface. This often gets swallowed in SLAs. I think we need to
take this on at some point and I haven’t checked to see whether other
discussion in sections 3 and 4 are sufficient.
-
In section 5.3.5, the detail on what constitutes infrastructure is
beyond the scope of the RAF. However, the immediately following list of
things needed for service management is thought-provoking, but it should not be
presented as a complete list.
-
How is section 5.3.6 different from what is in the section 5.3
life cycle chunk and how should it relate? (Above, I questioned whether
the 5.3 detail is needed.)
There seems to be a few things on
which we need to focus:
-
Management to operationalize governance
-
Monitoring so you have data from which to get status and make decisions
-
Specific things to manage in a SOA ecosystem that weren’t of
consequence in traditional systems
Capability to manage seems to
require policies from governance translated to rules and regulations that get
to specifics and then measurement and feedback on the specifics.
---------------------------------------------------------------------------
MITRE Corporation, M/S
H305
phone: 703-983-7934
7515 Colshire
Drive
fax: 703-983-1379