Issues for GEMS 1.5 Revision Task Force

List of issues (green=resolved, yellow=pending Board vote, red=unresolved)

List options: All ; Open Issues only; or Closed Issues only

Jira Issues

Issue 12755: Section 7.3.2.5.1 Jira Issue GEMS11-1
Issue 13132: The time format is closer to POSIX than UTC and does not allow for unambiguous leap second resolution Jira Issue GEMS-23
Issue 14111: Escape characters Jira Issue GEMS11-2
Issue 14112: We suggest leaving the old time type (based on POSIX) Jira Issue GEMS11-3
Issue 14113: Hex value arrays in ASCII Jira Issue GEMS11-4
Issue 14850: RFP Mandatory Requirment 6.5.1.9 Not Implemented Jira Issue GEMS11-5
Issue 15486: Need a better example for XML Get Request Jira Issue GEMS14-1
Issue 15487: ASCII Set Response description has a valid_state Jira Issue GEMS12-1
Issue 15488: Mapping of XML and ASCII versions is not consistent Jira Issue GEMS12-2
Issue 15489: Incorrect message types in ASCII GetConfigMessage/Response Jira Issue GEMS12-3
Issue 15490: No PingMessage/Response defined in XML schema Jira Issue GEMS12-4
Issue 15491: ASCII Save response has extra field in the example Jira Issue GEMS12-5
Issue 15492: GEMS does not define a message type for a generic malformed message Jira Issue GEMS12-6
Issue 15493: Defining a zero length hex_value is ambiguous Jira Issue GEMS12-7
Issue 15494: The comment regarding multiplicity in section 6.3.1.13 is no longer needed Jira Issue GEMS12-8
Issue 15495: There is no unambiguous way to tell if a value is a scalar or an array of one in the XML Jira Issue GEMS12-9
Issue 15496: The XML schema calls out an 'array' attribute (vs multiplicity) in the ParameterSet Jira Issue GEMS12-10
Issue 15497: Defining arrays of ParameterSets in GEMS-XML is unclear Jira Issue GEMS12-11
Issue 15498: Network messages containing GEMS-XML are difficult to parse without a header containing the message length Jira Issue GEMS12-12
Issue 16017: Typos Jira Issue GEMS12-13
Issue 16091: The schema dtc/11-02-02 has 6 errors found by running an XML Schema validator Jira Issue GEMS12-14
Issue 16950: GEMS-XML hex_value length Issue Jira Issue GEMS13-1
Issue 16952: GEMS-XML ParameterSet Order Jira Issue GEMS13-2
Issue 18313: clarify GEMS authentication Jira Issue GEMS13-3
Issue 18314: Extend GEMS-ASCII message length Jira Issue GEMS13-4
Issue 18315: obtained only changed parameters Jira Issue GEMS14-2
Issue 18535: GEMS-XML schema (GEMS 1.2) for MessageSequenceType does not support elements for DirectiveMessage Jira Issue GEMS13-5
Issue 18723: GEMS TCP socket close behavior is not obvious Jira Issue GEMS13-6
Issue 18733: Confusing comments Jira Issue GEMS13-7
Issue 18813: GEMS Device Definition does not include a multiplicity for ParameterSetDefType Jira Issue GEMS14-3
Issue 18814: Unbounded Lists In Device Definitions Jira Issue GEMS13-8
Issue 19513: GEMS HTTP POST example is incorrect Jira Issue GEMS14-4
Issue 19563: wrong type of quote used Jira Issue GEMS14-5
Issue 19596: Bug link URL is invalid Jira Issue GEMS14-6
Issue 19597: Numerous small errata and inconsistencies Jira Issue GEMS14-7
Issue 19615: Multiple issues with ASCII PSM examples Jira Issue GEMS14-8
Issue 19616: Figures without figure numbers Jira Issue GEMS14-9
Issue 19617: Acronym not defined correctly Jira Issue GEMS14-10
Issue 19618: Links in XML examples are broken Jira Issue GEMS14-11
Issue 19619: SetConfigResponse defined with two parameters in PIM Jira Issue GEMS14-12
Issue 19620: Arrays defined ambiguously for ASCII PSM Jira Issue GEMS14-13
Issue 19622: HTTP header on GEMS XML example malformed Jira Issue GEMS14-14
Issue 19625: Arrays of parameters sets not defined for ASCII PSM Jira Issue GEMS14-15
Issue 19626: Mixed parameter set example has extra delimiter Jira Issue GEMS14-16
Issue 19627: Extend PIM to allow "leaf" values to be referenced directly Jira Issue GEMS14-17
Issue 19629: Standard message trailer in ASCII PSM has extra pipe Jira Issue GEMS14-18
Issue 19647: Extra Attribute in GEMS 1.3 Directive Schema Jira Issue GEMS14-19
Issue 19661: Directives require arguments Jira Issue GEMS14-20
Issue 19662: DisconnectMessage doesn't have a response Jira Issue GEMS14-21
Issue 19737: Add 'Units' to Device Description parameter definitions Jira Issue GEMS14-22
Issue 19739: "Range of Values" specified for "Message Length" is incorrect Jira Issue GEMS14-23
Issue 19740: Add read-only as a parameter attribute Jira Issue GEMS14-24

Issue 12755: Section 7.3.2.5.1 (gems-rtf)

Need to describe what a GET message returns when targeted to a proxy. There is no description of what is returned when a GetMessage is sent to a proxy.  Options:  * Return information on the proxy such as an array of target names available ''behind'' the proxy.  * Return all parameters for all devices behind the proxy  * Defined standard parameters for the proxy which would then be returned

It is suggested that this be deferred to the RTF.  Disposition:	Deferred  

1) The time format is closer to POSIX than UTC and does not allow for unambiguous leap second resolution.   A. This new issue was raised during the FTF.  B. Reported by David Overeem at Boeing

It is suggested that this be deferred to a future RTF.

Escape characters: To make parsing quite a bit easier (enabling the use of string tokenizer tools found in most modern programming languages) we suggest changing the current escape character implementation with a mechanism similar to the one used for HTML / XML. This would mean identifying all special characters ('|', ',', ';' . . .) and creating character sequences for them ('&p', '&c', . . .). Doing this would simplify parsing code significantly. The initial message could then be easily split using the '|' as the token. Array members could easily be split using a ',' etc...  

UTC Time as a new type Create a new time type that uses the UTC time format. This would allow for times that are human readable and that also support leap seconds. Unfortunately the current time type cannot be replaced because the XML schema for it wouldn't easily support this new format for time. We suggest leaving the old time type (based on POSIX) which we admit is useful under many circumstances.  

Hex value arrays in ASCII This was already differed as an issue during the FTF to be fixed later. Some additional feedback received was to use a format like 'FAF320/20' instead of notation like 'FAF320.20'. The later matches the notation used for the current time type but might cause too much confusion with floats.  

The device definition return that is specified in the original RFP at section 6.5.1.9 does not appear to be implemented in the released specification 1.0.

Section 7.2.6.1 only provides a simple example of a GetConfigResponse with no parameters. A better example would provide parameters possibly with multiplicity so implementers have a clearer understanding of how it should be done. Replace current example with:    <?xml version="1.0" encoding="UTF-8"?><GetConfigResponse gems_version="1.1" target="device1"	timestamp="1234.98765" token="ABCD" transaction_id="1" xmlns="https://www.omg.org/gems"    	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"	xsi:schemaLocation="https://www.omg.org/gems GEMS_base_types.xsd">    	<Result>SUCCESS</Result>	<description>Get config was successful</description>	<Parameter name="name">		<string>Device One</string>	</Parameter>    	<Parameter name="hex">		<hex_value bit_length="16">DEADBEEF</hex_value>	</Parameter></GetConfigResponse>  

The valid_state was removed from the PIM however the message table in 8.1.8.2 still has a valid state field.   Proposed Resolution: Remove this from the table  

The mapping of XML to ASCII versions is inconsistent in the PSMs. GEMS-ASCII uses an integer (01, 02, 03...), and GEMS XML uses decimal numbers (1.1, 1.2 and so forth)  Proposed Resolution: Need to discuss  

The GEMS-ASCII message types are not correct in section 8.1.10.1.  Appears to be a copy-n-paste error in GetConfigListMessage, GetConfigListResponse.  

The XML PSM sections and attached schema do not define a ping response message  Proposed Resolution: Potential XML Ping & PingResponse messages      <?xml version="1.0" encoding="UTF-8"?><PingMessage gems_version="1.1" target="testDevice1" timestamp="1234.98765"    	token="ABCD" transaction_id="1" xmlns="https://www.omg.org/gems"	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    	xsi:schemaLocation="https://www.omg.org/gems GEMS_base_types.xsd" />  <?xml version="1.0" encoding="UTF-8"?><PingResponse gems_version="1.1" target="testDevice1"    	timestamp="1234.98765" token="ABCD" transaction_id="1"	xmlns="https://www.omg.org/gems" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    	xsi:schemaLocation="https://www.omg.org/gems GEMS_base_types.xsd">	<Result>SUCCESS</Result>	<description>I'm Here!</description></PingResponse>    

The example for the GEMS-ASCII SaveConfigResponse in section 8.2.5 contains an extra field  Proposed Resolution: Fix  

The GEMS PIM & PSMs do not define a generic message for a response to an unreadable or completely malformed message. This can occur if the server receives a message that is either not a GEMS message (i.e. junk) or a GEMS message with a malformed header. Currently the only response messages are tied to specific message types and it is unclear what a server should return in this more general case.  Proposed Resolution: Utilize the base response message class for this. The specific type in ASCII could be UNK-R and in XML UnknownResponse.  

There is no clear example of how to define a zero length hex_value in GEMS-ASCII. Possibilities include name:hex_value=/0 or name:hex_value=0/0  Proposed Resolution: name:hex_value=0/0 to make parsing simpler.  

The way hex_value arrays are handled in GEMS 1.1 solves this problem. The comment relates to the old way of doing hex_values  Proposed Resolution: Remove the comment  

The GEMS-XML schema defines a default value for multiplicity (default of 1). The result is that parsers using the schema are unable to tell if a parameter is a scalar or an array of length one.   Proposed Resolution: Recommend removing the default multiplicity in the xml schema and the spec should state 'no multiplicity == scalar'  

The attribute should be multiplicity to match the PIM/PSM  Proposed Resolution: Fix  

Unlike a normal Parameter with multiplicity greater than 1, a ParameterSet array contains ParameterSet elements. These each have a name and multiplicity with then that need to be ignored.  Proposed Resolution: Add the following comment to the XSD for a ParameterSet:          NOTE: If the multiplicity is set, then the contained ParameterSet's are entries in the                array and the name & multiplicity (if specified) are ignored.  

Parsing a GEMS-XML message as it arrives on a TCP socket is difficult since you must first parse the stream (i.e. with SAX) and then likely validate it with a DOM.   Proposed Resolution: Add a statement indicating that the if a transport protocol is used (e.g. smart sockets etc) that includes the length, then nothing needs to be done. Otherwise, if TCP sockets are used, a HTTP header is pre-pended.      

6.3.1.4:  but -- bit  6.3.2: update supported versions  (1 becomes 1.0, 1.1 and 1.2)  6.5: 3rd sentence, change 'contents' to 'content' (there is only one token field, so I think this is the better fix)  7.1.1.1: in the Unsigned Short Integer, change fixed="time" to fixed="ushort".  (the XML schema is correct.. just a typo in the document)  8.1.2: first sentence after the escape sequence table, change 'chosed' to 'chosen'  

The schema dtc/11-02-02 has 6 errors found by running an XML Schema validator.    Various types extending MessageType give the following error: derived by restriction complex type has content while base type is empty    

The GEMS-XML XSD bases the HexParameter on the xsd:hexBinary type. This type expects an even number of characters (two for each octet). The GEMS-XML specification should mention this and explain how it needs to be handled.      Recommend always providing an even number of hex characters and using the bit length to specify the actual length.      Example of an invalid 4 bit field:  E/4      Example of a valid 4 bit field:  E0/4  

The current GEMS-XML schema requires that Parameters and ParameterSets are always listed in that order. (i.e. ParameterSets cannot precede Parameters). It seems that these should be order independent.      Reported to AMERGINT by Raytheon  

Authentication of a GEMS user is loosely defined in the specification.  This should be clarified and include a better definition of how  credentials are passed in, what is the roll (if any) of SSL and  similar transports, and how do proxies handle authentication. In  particular, how does a GEMS user grab control of a system without  creating a race condition.  

Currently the message length is limited to 999999 characters. This can  cause problems translating from GEMS-XML to GEMS-ASCII. It also limits  the utility of message sets  

Received a request for either an asynchronous push or a new message  type that provides changes only. This was an optional requirement in  the original RFP  

This requires more discussion. A preliminary prototype has been made, but needs to be reviewed before anything is accepted into the specification.   Disposition:	Deferred  

GEMS-XML schema (GEMS 1.2) for MessageSequenceType does not support elements for DirectiveMessage, even though DirectiveMessageType shares the same base (MessageType) as the other supported elements defined in MessageSequenceType.    

GEMS VERSION 1.2      It is not obvious what happens to a client using either GEMS-ASCII or GEMS-XML across TCP when the TCP socket is closed. If the client has successfully connected to a GEMS Device, is that GEMS connection (and resulting token) still active or does it automatically disconnect?  Section 6.5 indicates that it should be disconnected, but this is not an obvious place for this behavior to be described.        Also, GEMS-XML states that the HTTP header should be added. When using client-side HTTP libraries, the default behavior is to disconnect often. This is an internet-style approach.  The GEMS specification should state that persistent socket connection are required

The comments about the GEMS Version field in Table 8.2 are confusing. Is the example trying to imply that starting with GEMS version 1.2 the GEMS Version field digits matches the actual GEMS version number, or what?

The ParameterSetDefType needs a multiplicity attribute similar to ParameterDefType. This allows for lists of Parameter Sets.

It is not clear how to define the multiplicity of a list of Parameters or ParameterSets when the list is unbounded or can vary in length. For example, if the multiplicity is set to 5, it is assumed this means the list must contain 5 parameters.  How does one specify "up to 5" or "unbounded"?      

The example HTTP POST header is incorrectly listed in section 7.4. The first line of the header should be:      POST /target HTTP/1.1  

<Parameter name=�telemetry_ports�>      should be       <Parameter name="telemetry_ports">    I copy and pasted that example into a file and it took me a couple of hours to realize there was invalid quotes.

The link on page iv for reporting bugs is an invalid page. The link should be https://www.omg.org/report_issue.htm

6.3.1.13 hex_value - Add: The length in bits is specified by following the hex data with a forward slash and the number of bits. E.g. /22.6.3.1.13 hex_value - Add: The length in bits is specified by following the hex data with a forward slash and the number of bits. E.g. /22.      Many of the XML examples: The gems_version attribute type should be xsd:decimal not xsd:int      Many of the XML examples: The XML examples shoudl all include the standard xml version segment like:  <?xml version="1.0" encoding="UTF-8"?>  This is missing from most of the examples      Many of the examples: The gems_version is shown as an integer value like: "1". It should be shown as a decimal value like: "1.3"      7.3.4.1 SetConfigMessage Example - this has a superfluous line: </SetConfigMessage> about half way down that needs to be deleted.      7.3.7.1 PingMessage Example - The version number should be changed from 1.1 to 1.3      7.3.7.2 PingResponse Example - The version number should be changed from 1.1 to 1.3      7.3.8.1 ConnectionRequestMessage without Authentication - The version number should be changed from 1.2 to 1.3      7.3.8.3 ConnectionRequestMessage with Authentication - The version number should be changed from 1.2 to 1.3      7.3.8.4 Failed ConnectionRequestResponse - add the version number as 1.3      7.3.8.5 Successful ConnectionRequestResponse - add the version number as 1.3      7.3.8.3 ConnectionRequestMessage with Authentication - The token filed text should be: "up:john:secret"      7.5.1 Example Device Definition File - replace 'bool' with 'boolean' 4 places      Table 8.1 boolean type: example should be: param:boolean=true      8.3.3 GetConfigMessage Example - change example sync_pattern to be: sync_pattern:hex_value=FAF320/22      8.3.4 SetConfigMessage Example - change example sync_pattern to be: sync_pattern:hex_value=FAF320/22      8.3.7 DirectiveMessage Example (response) - change accepted:bool=true to accepted:boolean=true

The message examples for the ASCII PSM have the following issues.  This is in addition to a handful of issue reported under Issue 19597.      1.  The hex value examples have type "hexvalue".  This should be "hex_value" (with underscore).      2.  All examples have an extra space after the first pipe, e.g. "| GEMS|01|...".  We should be able to use the examples literally.      3.  The SetConfigMessage example still contains the long-removed "valid state" field.  The "2" should be removed from the example, i.e.  SET-R|SUCCESS| The SET request was successful.||TRUE  instead of  SET-R|SUCCESS| The SET request was successful.|2|TRUE      4.  The GEMS version in all examples should be updated to the latest ("14").  Right now it's using "01".      5.  There is no ASCII example for the PING message.  It should be:  Message: |GEMS|14|000122|123|CS123|111111111.222000000|FrameSync1|PING|END  Response: |GEMS|14|000122|123|CS123|111111111.222000000|FrameSync1|PING-R|SUCCESS|The PING request was successful.|END

There are six figures in the specification that do not have figure numbers.  These occur in sections 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.3.2.2, 8.2.3.

The SCPI acronym definition in section 4 should read "Standard Commands", not "General Command".

All XML examples need to update the embedded URL.  The "https://www.omg.org/gems" link is broken, it should be "https://www.omg.org/spec/GEMS" or "https://www.omg.org/spec/GEMS/current".

Under "SetConfigResponse", it says "the message has 2 parameters", but only one parameter is described ("parameters_set").  This is probably a holdover from when the "valid state" parameter was removed back in v1.1. This should simply be changed to "the message has 1 parameter".

Representation of arrays in the ASCII PSM is ambiguous. In 8.2.1 it says that arrays look like this:      parameter_name[3]:type=value1,value2,value3      The multiplicity is appended to the parameter name, there is a single type, and the values are comma separated.  But in 8.2.1.2, it says arrays look like this:      param:int[3]:int=1,int=2,int=3      There are two colons, the multiplicity is appended to the type, and the type is repeated for each value within the comma separated list.  Presumably there is a goal of unifying the way arrays and parameter sets are represented, where an array of scalars is just a homogeneous parameter set.  Suggest we abandon this goal, as it will make representation of arrays of parameter sets very difficult.  Suggest we represent arrays as follows:    name:type[multiplicity]=val1,val2,val3

The HTTP header for GEMS XML in section 7.4 has the following issues:      1. First line contains "HTTP 1.0", which should be "HTTP/1.0"    2. There should be an additional endline between the header and the body

There is no definition for arrays of parameter sets in the ASCII PSM.  Section 7.1.1.3 suggests that these are supported by the PIM, and we need a mapping for all PSMs.  Currently, a single parameter set (not an array of sets) is defined with commas as the delimiter between members of the set.  The comma is also used as the delimiter between array elements.  This makes it very difficult to deserialize an array of parameter sets, since the same delimiter character is used for two purposes.  It became even more difficult after Issue 18814 was resolved by redefining the multiplicity to be a maximum array size (with -1 as a valid value), instead of the actual array size in the message.  Suggest we use semicolons as the delimiter between parameter set members, and continue using commas as the delimiter between array elements.

The mixed parameter set example in 8.2.1.2 has an extra delimiter at the end of the message body:      mixed_param_set:set_type=param_1:int=1,param_2:boolean=true,param_3:string=a short string,    Delimiters should only be between the members of the set.  This keeps them consistent with arrays (which, by the way, must NOT have delimiters at the end, since they have to be able to represent string arrays that end with an empty string element).

The spec currently allows arrays, parameters sets, and arrays of parameter sets.  These compound types can make for an API that's difficult to use.  Specifically, if you want to modify a single member of a parameter set, you have to read it, deserialize it, modify part of it, re-serialize it, and write it back.  This isn't wildly difficult, but I believe it's enough for a customer to complain about usability.  This operation is particularly annoying in the case of arrays of parameter sets.  Furthermore, the read/modify/write operation isn't atomic, and could result in race conditions that revert a simultaneous change.      I'd like to suggest that we extend the PIM to allow "leaf" values of compound types to be referenced directly.  E.g., array elements and parameter set members could be referenced under the ASCII PSM using the following parameter names:      Array element:  myArray/3  Set member:     myParamSet/memberName  Array of sets:  myArrayOfSets/5/memberName    ...with a corresponding scheme for the XML PSM.  This would require adding the forward slash as a reserved word that should not be used in parameter names, along with "|GEMS" and "|END".

The ASCII PSM defines the standard message trailer as "|END", but every single message type also ends with a "|" followed by "standard trailer".  Strictly speaking, this results in every single message having a pair of pipes at the end with nothing between.  We should remove the pipe from the standard trailer table (8.4).

The GEMS XML schema for a directive message has an extra, optional, attribute that should not be there. This was never caught until code generation was used and the attribute showed up.      Incorrect:      <!--    GEMS Directive    -->    <xsd:complexType name="ArgumentsType">    <xsd:sequence>    <xsd:element maxOccurs="unbounded" minOccurs="0" name="Parameter" type="Parameter"/>    </xsd:sequence>    <xsd:attribute name="directive_name" type="xsd:string" use="optional"/>    </xsd:complexType>            Correct:      <!--    GEMS Directive    -->    <xsd:complexType name="ArgumentsType">    <xsd:sequence>    <xsd:element maxOccurs="unbounded" minOccurs="0" name="Parameter" type="Parameter"/>    </xsd:sequence>    </xsd:complexType>      

The .xsd file requires parameters of a directive be with in <arguments> </arguments> but the example of page 37 doesn't do that.

It would be very useful for the DisconnectMessage to have a response of success or failure.

Add 'units' as a parameter constraint (not really a constraint bu that's the section in the doc).  Units are a string containing the unit of measurement such as mm, inch, bps

In Table 8.2  "Message Length" has a "Range of Values" specified as "000074-999999". We took this as the minimum possible message length to the maximum possible message length. Which, given our experience, is not true. We have encountered several instances with production hardware (Amergint & RTLogic) where the message length was fewer than 74 bytes.     I personally don�t care if OMG decides to list a minimum length; I just want the documented "Range of Values" to reflect reality. In the case OMG doesn�t want to specify a minimum length I would suggest the range value would be listed as "000000-999999" in the spec. Listing a range of "000000" could be problematic/confusing as well, "000000" would never be a valid either... So... I will let you standards people work this one out.

Some GEMS target parameters are not writable. It would be useful to know which ones are read-only when using GEMS to construct a GUI.