[Moims-mp] Updated MPS Documents

[roger.rocketbrain at btinternet.com]

Dear Peter and all,
 
I have uploaded Draft H4 of the MPS BB to the Google Drive:
https://docs.google.com/document/d/1QT1MwJHm2apO75NFysftI93r6T1Fc0iv/edit?us
p=share_link
<https://docs.google.com/document/d/1QT1MwJHm2apO75NFysftI93r6T1Fc0iv/edit?u
sp=share_link&ouid=106200809466753231515&rtpof=true&sd=true>
&ouid=106200809466753231515&rtpof=true&sd=true
Updates include:
1.	A couple of minor inconsistencies (cut-paste and format errors) in
service tables discovered while working on the XML Specification Export
macro
2.	Changes to Error numbers to be consistent with the numbering policy
defined by the SM&C WG for MALv3.  It was agreed not to apply the proposed
MAL change to assign SFPs to Abstract data types – this was only required to
transfer additional type information on the wire, and it was concluded that
this is not required for the standard.
3.	Change to the representation of Error References for service
operations.  These were represented as a simple bullet list.  I have
replaced these with tables that specify the name and area of relevant errors
– this is more consistent with other MO services, although I have omitted
the ExtraInfo field, as we have defined this once for all MPS Errors in the
table in section 5.  As well as being more consistent, it was easier for the
XML export macro to process these tables.  I also updated the convention
section to add the new normative style of table.
4.	In the table of MPS service errors in section 5, I have split the
comment column into two – one for the Error and one to describe the
ExtraInfo.  This fits better with where the comments are put into the XML
specification (and César’s tool).
5.	I also updated the Open Issues to remove the reference to the
historical XML Specification – as we will be able to provide an updated
version.
 
I have also now addressed all normative aspects of the XML Specification in
the export macro and generated the MPS XML Specification uploaded to the
Google Drive at:
https://drive.google.com/file/d/1TVkfZnDSjSJldR6zrS3uK71yp6lSmAuU/view?usp=s
hare_link
@César – this is more complete than the last version I gave you.
This includes:
1.	Services
a.	High-Level and Functional Requirements Documentation associated with
each Service
b.	Capability Sets
c.	Operations
d.	Messages for each Operation
e.	Error References for each Operation
2.	Data Structures
a.	MO Objects
b.	Composites
c.	Enumerations
3.	Errors
4.	Comments are included for:
a.	Services
b.	Operations
c.	Error References and associated ExtraInfo
d.	Data Structures
e.	Data Structure fields
f.	Errors
 
The XML specification appears to parse correctly and the structure can be
displayed/interrogated using standard tools.
Comments for Data Structure Fields, Errors and Error ExtraInfo are extracted
from the corresponding normative tables in the Blue Book.
Comments for Services, Operations, Error References and Data Structures are
extracted from the document body and correspond to the text that appears
above the corresponding table and after the associated heading.  This text
may be multi-paragraph and so appears in the XML over several lines
(unindented) – also formatting information (such as bold/italics and list
numbering/bullets) is lost.
It may be possible to include additional comment text, but it is less clear
what this should be attached to in the XML Specification, and as it is
non-normative is not high priority.
 
I did not include the “Structure” requirements sections at Operation level –
I was not certain that the MAL:Documentation element was valid here, but in
any case these are only used to represent the subscription keys for PubSub
operations.  I had already discussed with César how these should be
represented in the Operation tables and as a Message in the XML
specification – so the normative information is present in the XML
Specification.
 
I discussed with the SM&C group whether the ExtraInfo should be defined in
the XML Specification together with the Errors themselves, rather than with
the ErrorReferences on Service Operations.  It was agreed not to change the
current MAL approach, as this allows for the possibility of specifying
service level ExtraInfo for a MAL Error.  This does result in some
repetition in the XML – but within our Blue Book, we specify the ExtraInfo
data type and Comment with the Errors in Section 5.  The exported XML is
consistent with the MAL approach of defining ExtraInfo with the Error
References.
 
Our standard does not currently reference MAL Errors directly – but makes
the general statement that any applicable MAL Errors may also be received
for MPS Service Operations.  I would be reluctant to list MAL Error
References for every service operation for two reasons:  it is highly
repetitive; and it introduces tight coupling between the MPS and MAL
documents which it would be best to avoid.
 
I have created the XML Export macro as a separate Word Template file.  This
needs to be opened as an Add-In and adds a single button to the Developer
toolbar that invokes a custom Form from which two operations are possible:
Load the service model from the Book, and Generate the XML Specification.
It is “success oriented” – in other words it will crash if a normative table
is badly formed.  It does rely on some metadata entered into the tables’
alternate text title field that indicates the type of table and the item it
relates to.  This can be viewed and edited in Word on the Table Properties
dialog.  The macro is not MPS specific – it picks up the Area information
from custom Word Document Properties – also editable using standard Word
dialogs and saved with the document.  It can therefore be re-used for future
MO specifications for the initial document > XML transition.
 
Cheers,
 
Roger
 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.ccsds.org/pipermail/moims-mp/attachments/20230317/24ea8355/attachment-0001.htm>