[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [xmile] Draft spec issues & recommendations
Hello folks, I realize I should have been keeping more up to date with this, but things have been quite busy at my new job, and it wasn't until now that I've gotten a chance to take a detailed look at the spec. There are a some serious high-level issues I'm concerned about, and I think the vote should be postponed 2 weeks to address them, with an interim check-in meeting next week. What I would like to see is limiting what is in the unprefixed std XML namespace, cleaning up the wording to be clear for implementers, an un-ambiguous definition of the modeling language used in equations, and clear conformance criteria. I still have a number of smaller specific issues (an example: section 2.8 allows the data type to be 'XML', but the XML format for data is not found anywhere), but these are the large ones that I think should be addressed before a Committee Spec for public review. Details follow. A) unprefixed XML namespace: As recently as August (which was before he joined isee), Bob's position was the same as mine, that the goal of the committee is to provide a spec that can represent 80-90% of SD models [ "My hope is that we could come up with something that would capture 80-90% of such models" http://www.systemdynamics.org/forum/viewtopic.php?f=21&t=351 ]. Karim has recently asserted that the goal is to be as inclusive as possible [ https://lists.oasis-open.org/archives/xmile/201406/msg00085.html ], but this isn't actually in the wording of the committee's charter. Being inclusive is a good goal, but that does not mean the TC's mandate is to include anything and everything in isee's current file-format in the (unprefixed) std XML namespace of XMILE. There are a number of parts (especially in the display section) that still relate to the long-tail of isee models. It is very good to have documentation for this, but I think it would be more appropriate in a vendor-specific appendix. Specifically Lamps, List Input Devices, Gauges, and almost all of the attributes for buttons. For example, a button's menu_action refers to specific Stella/iThink menu items. These do not belong in the std XML namespace, and I think it would help with readability if they were moved out of Chapter 6 into an isee specific appendix. B) Wording I think the language needs to be more precise across the board. This is important - it needs to be clear what is required to be implemented, what is recommended be implemented, and what is optional. I think this recent OASIS spec is a good example: http://docs.oasis-open.org/virtio/virtio/v1.0/csd02/virtio-v1.0-csd02.html They use RFC 2119 words MAY, MUST, SHOULD and friends in capital letters. It makes it very clear what is expected. An example of how this might look is modifying this: "XMILE implementations do not need to support macros, but if they do not, they cannot support model files that use vendor-specific functions. Macros can use all of the syntax of XMILE to achieve their result. The simplest kind of macro is a single expression using existing functions (including macros) and operators. In this regard, its value is specified in the same way as an auxiliary. The change of base formula above is a good example" to something like this: "Macros are a functionality to implement arbitrary, often vendor-specific, functions, using the syntax of XMILE. Implementations MAY implement macros to enable compatibility with the largest set of models possible. The simplest kind of macro is a single expression using existing functions and operators. An example is the change of base formula seen earlier:" There are also holdovers from when this was a more informal document that I don't think are appropriate for the tone of an industry-wide spec, for example "Additional data sources and sinks, such as databases and web servers, are desired, but not yet specified". I suggest lines like that are deleted - we are describing a file format to people implementing SD programs and libraries, and statements like that aren't useful in this context. I'm happy to take a pass at both using RFC 2119-like statements and cleaning up some of the informal language if others agree. In general, it is unclear what is required and what isn't. Chapter 3 defines macros as optional, but chapter 4 (section 8) does not have an opinion on the matter. C) modeling language I believe the modeling language is under defined. For starters, a BNF description of the grammar is necessary. This is not necessary for the first public draft, but should exist before a final spec happens. I'm happy to work on one over the next few weeks. D) Conformance This is maybe the smallest but most important part. The OASIS TC Process states: "(8a) For Standards Track Work Products: A specification that is approved by the TC at the Committee Specification Public Review Draft, Committee Specification or OASIS Standard level must include a separate section, listing a set of numbered conformance clauses, to which any implementation of the specification must adhere in order to claim conformance to the specification (or any optional portion thereof)." So even barring my other concerns above, we do not have a conformance section written, so I do not see how we can approve a public review draft today. If we edit the document to make use of RFC 2119 words, this could be pretty simple (again, see VIRTIO: http://docs.oasis-open.org/virtio/virtio/v1.0/csd02/virtio-v1.0-csd02.html#x1-2670007 ). Otherwise it gets a bit more complicated. Those are my concerns. I will happy go over them at the meeting during the 'discuss full draft specification' agenda item, but I wanted to give a heads up first. Talk to you folks in a little. yours, Bobby
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]