Re: [xmile] Draft spec issues & recommendations

[Karim Chichakly <kchichakly@iseesystems.com>]

Hi Billy,

Fair point, but we did not have that to vote on the 0.1 version either.  Also, though we hoped we could be ready, we are not voting for public review yet.  I would point you to section 3.1 of the OASIS regulations. (bobby quoted 2.18.8a in case you can't find 8).  Although we have discussed conformance on many occasions, we have not made it formal yet and so do not have a complete draft.

Also Bobby, the charter specifically allows "technical refinements" not wholesale rewriting or gutting of the draft spec.  This was at the advice of OASIS to make sure we don't spend 2 or more years going through this process.  We have spent a year at this and were at a rough consensus at the meeting a few weeks ago, talking only about clarifications and fixing gaps before the vote today.

Should be an interesting meeting.

Karim

On Fri, Jun 13, 2014 at 10:39 AM, Billy Schoenberg <bschoenberg@iseesystems.com> wrote:

Hi Steve,

I don't know how we can vote today on making this a draft for public release as defined by OASIS if what Bobby says is true in section D) conformance.  That is unless today's vote isn't related to the actual standardization at OASIS, but is instead a vote targeted for the System Dynamics community, and is outside the actual standardization process specified by OASIS.

I think it is worth confirming Bobby's statement in section D), but otherwise I can't see how we can vote to approve a draft (as OASIS defines it) which clearly doesn't meet the stated definition for a draft.

Best,

Billy

On Fri, Jun 13, 2014 at 10:32 AM, Steven Adler <adler1@us.ibm.com> wrote:

Bobby,

Thanks for the heads up.  We are voting today.

Best Regards,

Steve

Motto: "Do First, Think, Do it Again"

From:	Bobby Powers <bobbypowers@gmail.com>
To:	xmile <xmile@lists.oasis-open.org>
Date:	06/13/2014 10:21 AM
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

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php