[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [Joe's Comments, Part 3 - Web Services Profile] RE: [regrep] RE: ACTION ITEM
Here is my final set of comments for today's deadline. My review left off at line 1048 (I regret that I could not cover the entire draft in the timeframe allotted), so I will pick up reviewing from there when our next version is issued (and then start back at the top). Farrukh: If you would like me to continue where I left off rather than waiting for the next draft, please let me know (I'd be happy to). Joe Comments: Chapter 8 (general): Recommend adding text at the top of this section that describes what this section is about. For example, “This section will describe a standard mechanism by which WSDL content (i.e. information contained within a registered WSDL document) that is registered within ebXML Registry through the means described earlier can be discovered using ebXML Registry’s query capabilities.”. Line 1017: Misspelled “Registry”. Line 1017, “provides the ability for a user defined parameterized queries”: Either change “for a user” to “for user”, or “queries” to “query”. Line 1017, after “for each type of content”: Recommend citing some brief examples here (“For example, ebXML CPPA, UBL business documents, and WSDL documents.”). Lines 1020-1021, after “simply providing their parameters”: Recommend citing the place in our ebRS spec where we show an example of submission of a parameterized stored query (should be section 6.3.1). Such citations may also be valuable in other places in this spec (perhaps worth identifying these places). Line 1025: Add a simply introductory line for the figure (“An example of this is shown in the figure below.”). Line 1032: Not sure whether this line is an instruction to the reader, or a reminder to one of the editors of this spec. If the former, I recommend striking it as I don’t believe that it’s necessary to remind the reader of the information in chapter 2 (they can make the association themselves once they see the concepts in this section). Lines 1033-1034, “based on search criteria that predicates upon attributes of the type of object being discovered as well.”: This doesn’t seem to make sense (is a word missing? Or should we substitute “queries” for “predicates”?). In any event, making the update suggested earlier called “Chapter 8 (general)” may obviate the need for the text on lines 1033-1035. Lines 1033-1034, references to “higher level objects” and “lower level objects”: This is the first time in this spec that we refer to these terms. Recommend that we define them earlier, if they are important to retain. My understanding is that for WSDL, a higher level object would be the “master” RegistryObject that represents the WSDL document as a whole, and that contains associations to each of the 3 parts of the WSDL document (each of which would be a lower-level object): interfaces, bindings, and services. Line 1036: It appears that we are contrasting discovery vs. drill-down here - recommend stating that earlier, perhaps around line 1031 or earlier. We should also refer to both of these (discovery and drill-down) as two mechanisms for doing something, so that their association is clear. Perhaps we can say that they are 2 mechanisms of discovery - in which case we would need to change the name of “discovery” to something more specific, perhaps “general discovery” or “ad-hoc discovery”. This would tie the contents of this chapter together more cohesively. Line 1036: Come to think of it, the last time I recall seeing the term “drill-down” in an ebXML Registry spec was (I believe) version 2.6. If my understand is indeed correct, should we re-introduce this concept here in the spec if it is not in our primary specs? (ebRIM and ebRS) Line 1042: Here we state that “The queries defined in this chapter are therefore focused on discovery rather than drill-down.”. Recommend we say this earlier in this chapter - right after the text that is recommended for line 1036 above. Line 1044: What do we mean by “discoverable type”? Perhaps it might be better to say “discoverable part”, so as not to be confused with WSDL types. Lines 1044 “Each query may be” to line 1047: This was already stated earlier (lines 1018-1021) Kind Regards, Joseph Chiusano Associate Booz Allen Hamilton 700 13th St. NW Washington, DC 20005 O: 202-508-6514 C: 202-251-0731 Visit us online@ http://www.boozallen.com > -----Original Message----- > From: Chiusano Joseph [mailto:chiusano_joseph@bah.com] > Sent: Sunday, October 30, 2005 2:28 PM > To: ebXML Regrep > Subject: [regrep] [Joe's Comments, Part 2 - Web Services > Profile] RE: [regrep] RE: ACTION ITEM > > Here is my second set of comments on the Web Services > Profile. Not sure why they're showing up in "Gothic" font > (perhaps my PC knows that Halloween is imminent): > > Line 904: Recommend having a section called “Content > Management Services” with 2 sub-sections (“Validation Service > Profile” and “Cataloging Service Profile”), for consistency > with representation in our specs. > > Line 905: Misspelled “Registry”. > > Lines 907-908: Why is content validation a key feature for > enabling SOA governance within ebXML Registry? I suspect it’s > because it helps ensure that services that are available to > be used within a SOA behave in a manner that is expected > according to requirements (i.e. by validating their > definition according to these requirements, as much as is > possible through the capabilities of ebXML Registry). Having > said that, I recommend we don’t make the SOA leap here in the > middle of the spec (it’s the first time we’re mentioning SOA, > and it seems rather odd to do so this late). Instead, I > recommend we strike this sentence, and consider creating a > “Using ebXML Registry for SOA Governance” TN or spec in the > future, where we have SOA governance as the general topic and > we discuss how content validation (and other ebXML Registry > features) is key for enabling SOA governance. > > Line 911: Recommend providing an example(s) of an Invocation > Control File somewhere in this spec (i.e. the actual XSLT > code). For example it would be very helpful to see an XSLT > excerpt for each of the business rules stated in section 6.2 > (line 915). > > Line 916-917, “and MUST be expressable declaratively within > the Invocation Control File”: Recommend striking this > statement, as long as it is understood that the Invocation > Control File must be an XSLT style sheet (in our latest RS > spec, the Canonical XML Content Cataloging Service has this > requirement for its Invocation Control File, but I don’t > believe it is clear that all Invocation Control Files have > this requirement). > > Line 919-920: Change “WSDLBindingType” to “ProtocolType”, > which is the actual name of the ClassificationScheme (see line 768). > > Line 923: Change “SOAPBindingStyle” to “SOAPStyle”, which is > the actual name of the ClassificationScheme (see line 768). > > Line 929: Change “http” to “HTTP”. > > Line 932: Misspelled “Registry”. > > Line 944: Why is support for an Invocation Control File for a > cataloging service optional? How would the necessary > transformations be done without an Invocation Control File? > > Line 946: Add introductory sentence above this line for all > metadata sections that follow “Input Metadata”, etc.). For > example, ”The following sections describe the metadata and > content requirements for input to the WSDL cataloging > service, and the metadata that is produced by the WSDL > cataloging service as output.”. Line 978 can then be deleted. > > Line 951, “specified in chapter 11”: On line 590 and > subsequent places we reference “the WSDL ClassificationNode > in the ObjectType ClassificationScheme.”. Rather than > referring the reader to Chapter 11 here, I recommend instead > adding a reference to the WSDL ClassificationNode earlier in > the spec (in the context of “This is how a WSDL document is > classified within the ebXML Registry ObjectType > ClassificationScheme”), perhaps early in chapter 4 (before > line 590). Adding this seems natural, since we refer to that > node multiple times later on (line 590 and subsequent > places). If this is done, we don’t have to refer the reader > to chapter 11 here because they will have already read about > the canonical WSDL ClassificationNode back in chapter 4. We > can just say “refers to the canonical WSDL > ClassificationNode”. Same idea for lines 953-954. > > Lines 949-956: What separates these two cases is whether or > not the WSDL document will be stored in the repository, or > referenced as an ExternalLink. Recommend making this clear up > front, by adding the following text to follow the current > text on line 949: “The difference between the two types of > metadata has to do with whether the WSDL document will be > stored in the repository, or referenced via URL as an > ExternalLink. The sentence beginning on line 955 (“Recall > that, in the ExternalLink case the WSDL document is not be > stored in the repository.”) should then be deleted. > > Lines 958-969: Recommend listing each example following its > description, instead of together afterward. > > Line 958: The description that precedes the example discusses > ObjectType, but the example shows “id”. Recommend replacing > the id with ObjectType as follows: > objectType=”urn:oasis:names:tc:ebxmlregrep:ObjectType:Registry > Object:ExtrinsicObject:WSDL”>. Same idea for the next > example, which begins on line 963. > > Line 976: Need to replace “??” with something (not sure what > should be there). > > Line 979: Recommend dividing section 7.4.1 into two > subsections: “Slots” and “Instances” (or “Registry > Instances”, or some other better term). Then for the > “Instances” subsection, I recommend using the RIM classes as > the heading of each sub-subsection (e.g. > “rim:ExtrinsicObject”), rather than including the wsdl > elements. This makes sense because at this point, we are > concentrating on the registry while earlier we were > concentrating on WSDL (i.e. WSDL was driving the discussion). > > Lines 982-991: Recommend adding a single example that shows > both types of slots. > > > Kind Regards, > Joseph Chiusano > Associate > Booz Allen Hamilton > > 700 13th St. NW > Washington, DC 20005 > O: 202-508-6514 > C: 202-251-0731 > Visit us online@ http://www.boozallen.com > > > > -----Original Message----- > > From: Chiusano Joseph [mailto:chiusano_joseph@bah.com] > > Sent: Wednesday, October 26, 2005 10:09 PM > > To: Breininger, Kathryn R; ebXML Regrep > > Subject: [regrep] [Joe's Comments, Part 1] RE: [regrep] RE: > > ACTION ITEM > > > > Here are my comments on the first half of the spec (up to > Section 5, > > inclusive). Rest are in process. > > > > COMMENTS: > > > > Line 205: Misspelled “artifacts” > > > > Lines 206-222: Move to above Chapter 1, or do not reference > Chapter 1 > > in the list, as we are currently in Chapter 1 > > > > Line 209: Switch with line 208, for better flow > > > > Lines 207-222: Present as a table, with chapter number/chapter > > title/chapter description > > > > Lines 212-219: Present all profiles as a single chapter, with a > > section for each type of profile > > > > Line 233: What type of UML Diagrams? Only class diagrams? > > > > Line 261: This chapter is called “WSDL Information Model Overview” > > here, but in the earlier list of chapters it was described as > > “provides an overview of the Web Services information model.”. > > Recommend changing the earlier description to be ““provides an > > overview of the information model for Web Services > description within > > an ebXML Registry”, and changing the title on line 261 to “ebXML > > Registry Information Model for Web Services”. > > > > Line 263: Before “For more information”, add a sentence > stating that > > “This chapter will focus on Web Services that are described > using the > > W3C Web Services Description Language > > (WSDL) standard”. > > > > Line 263: Change “For more information see” to will “For more > > information on WSDL see” > > > > Line 264: Add the following above the figure: “The following figure > > illustrates the WSDL information model:” > > > > Line 266: “At the lowest level” - is the PortType really considered > > the “lowest” level? Some would consider it to be the highest level. > > > > Lines 266-271: Recommend replacing this with a statement that “The > > WSDL information model is shown above. Its elements are described > > below”. Otherwise, it appears that we are duplicating information > > between here and the descriptions below. > > > > Line 273: Misspelled “description” > > > > Line 273: Capitalize “Service” and “Port”, and any other > WSDL elements > > that are referred to from this point on in the document. > > > > Line 278, “described”: On line 274 we used the term “define” > > for port. This may be considered inconsistent. > > > > Line 278, “end-point”: Change to “endpoint”, for consistency > > throughout the document. > > > > Illustration 1, General: Recommend replacing/augmenting > with a figure > > that shows the “native” WSDL elements (PortType, Operation, etc.) > > separately from the “binding” WSDL elements (Service, Port, > etc.), and > > the relation between them (as described in the subsection for each > > element). > > > > Illustration 1, General: Should we add “Part” (message part) as an > > element? > > > > Line 285: Add “the” before “definition” > > > > Chapter 2, General: Consider adding a concrete example either woven > > throughout the subsections that describe the WSDL elements, or > > following all of the subsections. > > > > Chapter 3, General: I recall we discussed on a TC call the idea of > > removing this section, and having the reader refer to our specs. I > > recommend instead that we focus this chapter only on the Service > > Information Model and its classes, describing each class as > we do in > > the ebRIM spec (but perhaps with less detail) > > > > Lines 514-515: Does the mapping have to stop at the WSDL > PortType? Why > > couldn’t we have Operations, Messages, and Types (and > Message Parts) > > as ExtrinsicObjects in the registry that are reused among various > > PortTypes? > > > > Line 521: Add an introductory statement prior to this line stating > > that we will now describe each mapping occurrence (is > “occurrence” the > > correct word? Perhaps “instance”?) from WSDL to ebRIM. > > > > Line 522: Add an explanation after this line of why this mapping is > > accurate - i.e. what is it above the ebXML “Service” class that > > enables it to be mapped to the WSDL “service” element? Recommend > > citing the description of the “Service” class in ebRIM 3.0 which > > states that “Service instances describe services, such as web > > services.”. > > > > Line 535: This appears to me to be different than a > mapping; rather, > > it is a rule or convention for consistency (and > subsequently enhanced > > interoperability). Recommend separating it (and any other such > > rules/conventions) from the mappings, perhaps by having multiple > > subsections (i.e. one for mapping, one for rules/conventions, etc.). > > > > Line 549: Same idea as with line 535. > > > > Line 565: Same idea as with line 535. > > > > Line 571: Recommend including an “xml:lang” attribute in the > > wsdl:documentation element, since we describe this case. > > > > Line 587: Recommend including a figure that visually depicts the > > following lengthy description: “Classifies the rim:Service for > > wsdl:service by the Service ClassificationNode child of the WSDL > > ClassificationNode in the ObjectType > ClassificationScheme.”. Whew!!! > > (same for later similar instances, such as line 683) > > > > Line 606: I was going to recommend depicting wsdl:port instances in > > example, as well as the full representation of the > > <rim:ServiceBinding> element - but I see that that is done on line > > 620. So I recommend removing the line 606 example, as it is > redundant > > (it’s also redundant). > > > > Line 665: We cover SOAP bindings for accessURI; should we cover the > > other possible WSDL 1.1 bindings as well (HTTP GET & POST, > MIME)? If > > not, we should state up front that the only WSDL 1.1 > binding discussed > > in the specification will be SOAP. > > > > Line 680: Recommend showing the rim:ServiceBinding “service” > > attribute in the figure on line 670, and including the > explanation on > > line 680 before the figure on line 670. > > > > Line 858: Since this line describes associations, it has > occurred to > > me that we might like to have a description up front of the various > > techniques that will be used in this specification (i.e. mappings, > > matching (identifier matching, name matching, description > matching), > > classifications, associations, ExtrinsicObject creation, > etc.) so that > > the reader is better prepared when the various sections are > described. > > > > Chapter 4, General: I recommend organizing this section a bit more > > consistently. Perhaps we can list the following sub-subsections for > > each subsection (a subsection would be 4.3, for example): > > > > - Maps To (ebXML Registry mapping - i.e. instead of listing the > > subsection name as “4.3 wsdl:binding → rim:ExtrinsicObject > Mapping”, > > list it as “wsdl:binding” and state what the part of ebRIM the > > wsdl:binding maps to) > > - Technique Used (i.e. mapping, matching, etc.) > > - Description > > - Example > > > > This uniformity would make the subsections easier to read. > > > > Line 876: Recommend showing an example of this. > > > > Line 879: Recommend showing an example of this. > > > > Line 882: Recommend showing an example of this. > > > > Line 889: Recommend showing an example of this. > > > > Line 890: Should we really care how registered WSDL files are > > partitioned? Could this requirement be a burden on users? > We point out > > that such partitioning facilitates better reuse - but > shouldn’t that > > be up to the submitting party? (that is, if they wish to > have better > > reuse abilities, they should partition their WSDL files - > if they do > > not, they won’t have better reuse abilities). > > > > General: Section 5 sparked a thought: Are we anticipating > that there > > will be “WSDL assembly tools” available in the future that interact > > with ebXML Registry? (similar idea to schema assembly tools) Such > > tools would (for example) take a registered Service instance and > > serialize it (and its associated information) as a WSDL > document. This > > would enable users to register WSDL documents, and construct other > > WSDL documents from their constituent “parts”, or to create WSDL > > documents from registry contents that did not even > originate from WSDL > > documents. > > > > General: We don’t specify anywhere that we are referencing > WSDL 1.1, > > not WSDL 1.2. Recommend adding a statement to this effect > near the top > > of the document. > > > > General: We don’t describe anywhere why we are writing this > > specification and why it is needed. I recommend adding a > paragraph or > > two to this early on (I would be very happy to contribute a first > > cut). > > > > Kind Regards, > > Joseph Chiusano > > Associate > > Booz Allen Hamilton > > > > 700 13th St. NW > > Washington, DC 20005 > > O: 202-508-6514 > > C: 202-251-0731 > > Visit us online@ http://www.boozallen.com > > > > > > > -----Original Message----- > > > From: Breininger, Kathryn R > [mailto:kathryn.r.breininger@boeing.com] > > > Sent: Wednesday, October 26, 2005 12:06 PM > > > To: ebXML Regrep > > > Subject: [regrep] RE: ACTION ITEM > > > > > > Schedule update - Farrukh plans to have draft 4 out in a > week or so. > > > Please review and send comments ASAP. Thank you. > > > > > > > > > Kathryn Breininger > > > Boeing Library Services > > > 425-965-0182 phone > > > > > > > > > > > > > > > > > > > _____________________________________________ > > > > From: Breininger, Kathryn R > > > > Sent: Wednesday, October 26, 2005 8:52 AM > > > > To: 'ebXML Regrep' > > > > Subject: ACTION ITEM > > > > > > > > Please review the Web Services Profile document: > > > > > > > > > > http://www.oasis-open.org/apps/org/workgroup/regrep/download.php/14756 > > > > /regrep-ws-profile-1.0-draft3.pdf and send comments by > > > November 3rd. > > > > We will be discussing this document and determining > > whether we are > > > > ready to open a vote on it as a TC approved document. > > > > > > > > > > > > Kathryn Breininger > > > > CENTRAL Project Manager > > > > Emerging Technologies > > > > Boeing Library Services > > > > > > > > 425-965-0182 phone > > > > 425-237-3491 fax > > > > kathryn.r.breininger@boeing.com > > > > > > > > How was your service? Please click link below....... > > > > http://socal.web.boeing.com/ssglibsurvey/ > > > > > > > > > > > > > > > > > --------------------------------------------------------------------- > > > To unsubscribe from this mail list, you must leave the > > OASIS TC that > > > generates this mail. You may a link to this group and all > > your TCs in > > > OASIS > > > at: > > > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr > > oups.php > > > > > > > > > > > --------------------------------------------------------------------- > > To unsubscribe from this mail list, you must leave the > OASIS TC that > > generates this mail. You may a link to this group and all > your TCs in > > OASIS > > at: > > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr > > oups.php > > > > > > --------------------------------------------------------------------- > To unsubscribe from this mail list, you must leave the OASIS > TC that generates this mail. You may a link to this group > and all your TCs in OASIS > at: > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr > oups.php > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]