RE: [tag] General comments on the new split

["Jacques R. Durand" <JDurand@us.fujitsu.com>]

>However I'm not sure we need to suffix these with 'Class' 

Agree, that was just an example.
I think your second convention might be best:  the component identifier always starts with an upper-case (makes it easier to refer to it in the main doc, e.g. a glossary or so), while the class / type name always starts with a lower-case (already the case for atomic predef types like "string"):

>NormativeSource : normativeSource  (0..1)  
>Target : target (0..1)  
>Prerequisite : prerequisite (0..1)  
>Predicate : predicate (0..1)
...

Although again in the present case, I'd argue that we have no reason to distinguish Prerequisite type from Predicate type:

>Prerequisite : logicalExpr (0..1)  
>Predicate : logicalExpr (0..1)

Jacques


-----Original Message-----
From: stephengreenubl@gmail.com [mailto:stephengreenubl@gmail.com] On Behalf Of Stephen Green
Sent: Monday, November 23, 2009 2:41 PM
To: Jacques R. Durand
Cc: TAG TC List
Subject: Re: [tag] General comments on the new split

I agree we can use a notation like your suggestion.

I'm not sure there is any problem calling those structures based on classes by the term 'association'
(it is, as far as I know, 'operations' which are meant to be 'functions').

However I'm not sure we need to suffix these with 'Class' as wouldn't that mean we have to name the class 'targetClass' and not just 'target'. Some people distinguish the association name from the class name by making one start with upper case and the other with lower case.

e.g.
 normativeSource : NormativeSource  (0..1)  target : Target (0..1)  prerequisite : Prerequisite (0..1)  predicate : Predicate (0..1)  prescription : Prescription (0..1)  description : Description (0..1)  tag : Tag (0..*)
 var: Var (0..*)

or

 NormativeSource : normativeSource  (0..1)  Target : target (0..1)  Prerequisite : prerequisite (0..1)  Predicate : predicate (0..1)  Prescription : prescription (0..1)  Description : description (0..1)  Tag : tag (0..*)
 Var: var (0..*)

This seems OK.

e.g.

class testAssertion {
 id : string (0..1)
 language : string (0..1)
 NormativeSource : normativeSource  (0..1)  Target : target (0..1)  Prerequisite : prerequisite (0..1)  Predicate : predicate (0..1)  Prescription : prescription (0..1)  Description : description (0..1)  Tag : tag (0..*)
 Var: var (0..*)
}

Here I think people would understand the convention we are using (especially is we define it like with the 0.5 draft, etc). The attributes would have lower case names and have types like string and integer while the associations would be upper camel case and the classes on which they are based lower camel case.

I prefer this to UML for normative statements.
I don't think we are using UML quite as intended since we aren't quite in the OO paradigm here (we are concerned only with the structures of the information and with how it is accessed or used).
For that reason I don't think we would be safe to use it normatively. We would probably be breaking some UML rules while having to make UML a normative reference and that could cause some conflict between what we are specifying and what the UML strictly says. I note in UBL TC's UBL 2.0 the data structures were not modeled with UML except as informative appendix material.
http://docs.oasis-open.org/ubl/os-UBL-2.0/UBL-2.0.html#MODELS

We can allude to the OO and UML concepts when we use terms like 'class', 'attribute' and 'association'
(not 'operation' though) but we are only using those terms loosely, I think. Actually using UML seems too risky since we are not intending that the implementation be strictly object oriented as such. After all, one prime implementation target is XML and our Test Assertion Markup Language in particular and we don't have a normative way to implement a UML diagram as XML.
There are some generally accepted conventions but not that we can refer to normatively as such, I think.

Best regards
---
Stephen D Green




2009/11/23 Jacques R. Durand <JDurand@us.fujitsu.com>:
> Stephen:
>
> The latest TA Model post (0.5) is definitely an improvement.
>
> Model notation:
> What you have proposed seems to work (I don't think we have to worry about "choices" or sequences vs. groups so far), but I have a couple of concerns:
>
>
> (1) in case there already exists a standard notation for object models 
> we should probably try to reuse it. But I am not aware of any textual standard for this (UML is graphical, OCL is more focused on constraints...) Now, we could just use UML diagram snippets as well and forego textual model notation?
>
> (2) Technical issues (I believe) in your notation:
>
> - You define TA components (e.g. Target, Predicate, etc.) as "associations" i.e. as functions  that access to the object. That causes confusion with the cardinality notation that is more appropriate for "objects" (e.g. several "tag" occurrences are allowed 0..* does that mean the "tag" association returns several tag items? That seems to imply that there is a need for such a function that returns all tags of a TA. But I am not sure we want to impose this).
> - we may want the name of components to be distinct from their type name. E.g. that is what we have for "id": it is of type string. But your notation imposes "prerequisite" component to be of same name as the related class. That makes it hard to create two distinct components of a same type. E.g. we may want to say that Predicate and Prerequisite are of same "logExpr" type.
>
> Could we have redefined "testAssertion" class as:
>
> class testAssertion {
> id : string (0..1)
> language : string (0..1)
> normativeSource : normativeSourceClass  (0..1) target : targetClass 
> (0..1) prerequisite : logExprClass (0..1) predicate : logExprClass 
> (0..1) prescription : prescriptionClass (0..1) description : 
> descriptionClass (0..1) tag : tagClass (0..*)
> var: varClass (0..*)
> }
>
> Of course, in the mark-up some of these will show as attributes, others as elements. But the model does not have to distinguish.
> The alternative is again just to use UML diagrams: that would be more standard.
>
> Regards,
> Jacques
>
>
>
> -----Original Message-----
> From: stephengreenubl@gmail.com [mailto:stephengreenubl@gmail.com] On 
> Behalf Of Stephen Green
> Sent: Saturday, November 21, 2009 10:50 AM
> To: Jacques R. Durand
> Cc: TAG TC List
> Subject: Re: [tag] General comments on the new split
>
> Jacques,
>
> I agree with these comments. It would mean we need a means of representing the model in a neutral way (i.e. without alluding to the XML).
>
> Maybe we could do this by very simply (I favour simplicity here) 
> removing 'angle brackets' from the representation in the markup spec. 
> We need to agree an appropriate mapping of datatypes, e.g. 
> normalizedString to string When the element is global (e.g. 
> testAssertion) it can be represented as an association to a class for 
> the complexType
>
> Replacing XML angle brackets with curly brackets {...} and replacing the 'Content' with "operations{one(), two(), ...}"
> and using an association to link an element in the markup with its 
> complexType - representing the global elements as classes which are 
> associated with other classes which represent the corresponding 
> complexTypes; something like
>
> <example
>    name: xsd:normalizedString
>    id: xsd:normalizedString>
>  Content: one ?, two +, three *
> </example>
>
> if the element 'example' is global, becomes something like:
>
>
> class: example
> associations: {
>   example_type
> }
>
> class: example_type
> attributes: {
>    name : string
>    id : string
> }
> operations: {
>   one : one_type
>   two : two_type
>   three : three_type
> }
> associations: {
>   one_type, 0..1
>   two_type, 1..*
>   three_type, 0..*
> }
>
> I'm not sure this does all we need, e.g. we need a way to distinguish a sequence from a choice or group.
>
> E.g. how do we represent the following?
>
> group:
> <example
>    name: xsd:normalizedString
>    id: xsd:normalizedString>
>  Content: one ?, (two, three) *
> </example>
>
> choice:
> <example
>    name: xsd:normalizedString
>    id: xsd:normalizedString>
>  Content: one ?, (two | three) *
> </example>
>
> Or do we perhaps not need the model to include such detail?
>
> Perhaps we only need to represent the attached model diagram and include the semantics we have in the markup spec.
>
> It would be nice if there were a standard way to do this but as with the markup we may just need to decide and declare/describe our own means of representation.
>
>
> Best regards
> ---
> Stephen D Green
>
>
>
>
> 2009/11/21 Jacques R. Durand <JDurand@us.fujitsu.com>:
>> Test Assertions Guidelines: (1.0.8.7)
>> ----------------------------------------
>>
>> - appears to me as almost ready to go.
>>
>> - need to refer explicitly to the new "TA Model" spec, both in the 
>> Intro and in the (dummy) Conformance section.
>>
>> - we might consider reformatting Appendix B so that instead of just 
>> repeating the TAs from main body, it formats them using the mark-up.
>>
>> Test Assertions Model: (0.2)
>> ----------------------------------------
>>
>> - probably the one that needs more work:
>>
>> - it appears to me that anything that is defined currently in the TA 
>> mark-up and that  actually can describe the TA model itself 
>> independently from XML representation, should now be in this doc.
>> (I.e. we currently have some semantic explanation in the mark-up that 
>> actually apply to the model itself, regardless of its 
>> representation.)
>>
>> - Fig 1 ("roles of TA in 2 examples of workflow") has its place in 
>> the Guidelines but probably not in this more formal reference doc?
>>
>> - The general diagram in Appendix A could be split into several diags 
>> that represent logical clusters, e.g. "testAssertion_set",
>>  "shared", "normativeSource_type". Would solve the editorial display 
>> issue too...
>>
>> - The Glossary could be merged into the definitions in 3.1 / 3.2 to 
>> make a more formal description (the definitions split in the 
>> Guidelines makes sense because we wanted just "intuitive" defs at 
>> beginning, and a more complete Glossary at the end. But in a ref model as here, split not justified).
>>
>> - Seection 2: could be renamed like "Definitions and Rationale", then 
>> we start right away with 2.2 content, then at the end we blend-in 2.1 
>> alleviated content , explaining the benefits.
>>
>> - Section 3 could be just: "Test Assertion"
>> then 3.1 "Test Assertion Structure and Elements", starting with the 
>> diagram, then would list the detail of each element along the format 
>> of the current mark-up doc (except no XML...) then 3.2 "Semantics"
>> would be current section 4.
>>
>> - Section 4 could be "Test Assertion Set", then go into details of 
>> the TA set model (along format used in the mark-up doc)
>>
>>
>>
>> Test Assertions Mark-up: (0.9.7)
>> ----------------------------------------
>>
>> - Overall content-complete, but now in need to undergo a "semantic 
>> reduction" by migrating most semantic definitions and bits that are 
>> not proper to the markup itself , back into the TA model. Needs then 
>> to refer to the new TA model. A bit of redundancy with TA model is 
>> probably acceptable though.
>>
>> -jacques
>
>