cts2 / cts2-specification

The CTS2 OMG Specification
http://informatics.mayo.edu/cts2
11 stars 2 forks source link

OMG Issue 18541: Filter PropertyReference documentation needs clarification #151

Open hsolbrig opened 11 years ago

hsolbrig commented 11 years ago

The PropertyReference class in Filter, and corresponding elements in the query signatures doesn't specify exactly how one should create a referenceTarget for references of type Attribute. As an example, how would one go about specifying the uri attribute in the source component of a sourceAndRole element? The behavior is underspecified if the reference not to a leaf (e.g. "sourceAndRole") Recommend it should specify match anything except href. If it is going to require URIAndEntityName (vs. 'or'), we need to clearly state what URI is used in the CTS2 spec. Otherwise we need to change the signature to allow just a name (preferred).

http://www.omg.org/issues/cts2-rtf#Issue18541

kevinpeterson commented 11 years ago

Need to add a new element to the Filter - 'ComponentReference' - that allows either a Name or URI. This way, non-property filters (such as SPECIAL filters) don't need to specify a URI.

hsolbrig commented 11 years ago

Proposed Resolution: 1) FiltersAndSorting - Rename "PropertyReference" to "ComponentReference" 2) ComponentReference - pull reference type and referenceTarget and replace with referenceAttribute: LocalName - the name of a model attribute referenceProperty: PredicateReference - the name of a predicate in the Property field referenceSpecial: LocalName - the name of a computed or aggregate element such as matchStrength, TextFields, etc.

cendle commented 11 years ago

Reason For Change

The PropertyReference class in Filter, and corresponding elements in the query signatures doesn't specify exactly how one should create a referenceTarget for references of type Attribute. As an example, how would one go about specifying the uri attribute in the source component of a sourceAndRole element? The behavior is underspecified if the reference not to a leaf (e.g. "sourceAndRole") Recommend it should specify match anything except href. If it is going to require URIAndEntityName (vs. 'or'), we need to clearly state what URI is used in the CTS2 spec. Otherwise we need to change the signature to allow just a name (preferred).

Need to add a new element to the Filter - 'ComponentReference' - that allows either a Name or URI. This way, non-property filters (such as SPECIAL filters) don't need to specify a URI.

Severity: Minor

Proposed Resolution (PIM)

* Change Location 1
 Document "CTS2 - Core Model Elements, v1.0"
 Section 2.5
 Page 27
 Figure 2.12
* Change Description 1
 Updated diagram in Figure 2.12
 Old Diagram:

skitch

 New Diagram:
 Change "filterComponent :PropertyReference [0..*]" to
 "filterComponent :ComponentReference [0..*]".
* Change Location 2
 Document "CTS2 - Core Model Elements, v1.0"
 Section 2.5
 Page 27
 Figure 2.12
* Change Description 2
Updated diagram in Figure 2.12
 Old Diagram:

skitch

 New Diagram:
 Change "sortElement :PropertyReference" to
 "filterComponent :ComponentReference".
* Change Location 3
 Document "CTS2 - Core Model Elements, v1.0"
 Section 2.5
 Page 27
 Figure 2.12
* Change Description 3
Updated diagram in Figure 2.12
 Old Diagram:

skitch

 New Diagram:
 Remove class PropertyReference.
 Remove enumeration TargetReferenceType.

 Add class ComponentReference.
 Add "attributeReference :LocalIdentifier [0..1]" to class ComponentReference.
 Add "propertyReference :URIAndEntityName [0..1]" class ComponentReference.
 Add "specialReference :LocalIdentifier [0..1]" class ComponentReference.
* Change Location 4
 Document "CTS2 - Core Model Elements, v1.0"
 Section 2.5.1
 Page 28
* Change Description 4
 Old text:
 Remove entire section: 2.5.1.2 Class PropertyReference.

 New text:

Add class ComponentReference to section 2.5.1 (replaces 2.5.1.2) A reference to a CTS2 model element. ComponentReference may reference a model attribute, a Property or a special element such as match strength.

Attributes

attributeReference - a reference to an attribute in a CTS2 model such as formalName, designation, etc.

propertyReference - a reference to a model Property. The reference target carries the URI and, optionally, namespace and name of the property predicate.

specialReference - the target of the reference is a special element such as the match strength of a search.

* Change Location 5
 Document "CTS2 - Core Model Elements, v1.0"
 Section 2.5.1
 Page 29
* Change Description 5
 Old text:
 Remove entire section: 2.5.1.7 Enum TargetReferenceType.
* Change Location 6
 Document "CTS2 - Value Set Services, v1.0"
 Section 5.4
 Page 39
 Figure 5.4
* Change Description 6
 Updated diagram in Figure 5.4
 Old Diagram:

skitch

 New Diagram:

Add operation addPropertyQueryReference [changeSet :ChangeSetURI, valueSetDefinition :DocumentURI, operator :SetOperator, codeSystem :NameOrURI, codeSystemVersion :NameOrURI, component: ComponentReference, matchAlgorithm :NameOrURI, matchValue :String] to class ValueSetDefinitionMaintenance.

* Change Location 7
 Document "CTS2 - Value Set Services, v1.0"
 Section 5.4.1.8
 Page 44
* Change Description 7
 Remove text:

referenceType - the type of property reference - attribute or property (Type: ReferenceType). property - the entity name or URI of the specific referenced property (Type: EntityNameOrURI).

 Add text to the Input Parameters:

component - A reference to a CTS2 model element. ComponentReference may reference a model attribute, a Property or a special element such as match strength (Type: ComponentReference).

* Change Location 8
 Document "CTS2 - Value Set Services, v1.0"
 Section 5.4.1.7
 Page 43
* Change Description 8
 Remove text:

referenceType - the type of property reference - attribute or property (Type: ReferenceType). property - the entity name or URI of the specific referenced property (Type: EntityNameOrURI).

 Add text to the Input Parameters:

component - A reference to a CTS2 model element. ComponentReference may reference a model attribute, a Property or a special element such as match strength (Type: ComponentReference).

Proposed Resolution (PSM)

* Change Location

Core.xsd CoreService.xsd ValueSetDefinitionMaintenanceServiceTypes.xsd

* Change Description

View Changes: https://github.com/cts2/cts2-specification/commit/aa55cdd244f6435dfdbcb8823b25bc281bffa66e View Changes: https://github.com/cts2/cts2-specification/commit/339cd9b9cb3a4187546a759f68dfe4c960e6f7d6

Due to number of changes, please review the PDF. http://informatics.mayo.edu/svn/trunk/cts2/spec/submission/RTF_1.1/RTF_Issues/CTS2_RTF_1.1_18541.pdf

Proposed Revised Text

NA