Supporting the inclusion of multiple CIM Objects in a CIM Document

[rupert]

On Bryan's suggestion, this ticket has been created to summarise the discussion so far and to allow us to pass this discussion on to Simon Cox, or someone else suitably qualified, for comment.

Currently the CIM does not support the concept of an aggregation of CIM Objects within a CIM document. If one creates N CIM Objects then there must be N CIM documents (unless some of the CIM Objects are embedded within other CIM Objects but that is a different issue).

I have called for the CIM to be modified to support an aggregation. Hans supported this idea and Allyn has stated that he will do this unless anyone says otherwise.

Stephen Pascoe provided clarity by introducing some definitions. Applying his definitions to the CIM as it stands gives

1. CIM Document: An artifact manifesting a CIM Record instance. The

file format of a CIM Document is XML.

2. CIM Record: A container for a single CIM Object.

3. CIM Object: One of the addressable CIM classes (i.e. simulationRun, modelComponent, dataObject, etc)

Phil Bentley suggested we add a new aggregation concept rather than simply allowing a CIM Record to contain more than one CIM Object. He suggested we call this a CIM RecordSet?. This is what Allyn is planning to add i.e. the new rules will look like ...

1. CIM Document: An artifact manifesting a CIM RecordSet? instance. The file format of a CIM Document is XML.

2. CIM RecordSet?: An aggregation of CIM Records [1..n]

3. CIM Record: A container for a single CIM Object.

4. CIM Object: One of the addressable CIM classes (i.e. simulationRun, modelComponent, dataObject, etc)

One could also optionally allow a CIM Document to contain a CIM Record so that there would be two types of CIM Document. I suspect Allyn is not planning to do this.

Bryan asked how GML deals with this issue as we should follow their approach. Phil Bentley gave the following reply

Unfortunately, I don't think GML provides us with much of a steer in
this regard. Not because GML doesn't do object collections (it does of
course), but because the CIM, in its current form, doesn't really have
the same feature-based world view.

So in GML I think much of the handling of geometry and feature
collections is based upon the AbstractGeometricAttributeType data type
and the AggregationAttributeGroup attribute group (please excuse the
tautologies).

A quick skim through the GML schemas didn't immediately suggest an
obvious analogue to what is being asked for here. In GML speak I suspect
we'd need to start describing  our model data as FeatureCollections of
grid objects derived from the DiscreteCoverageType data type. (The CIM
Grid package partially adopts this approach.)

FWIW, my current mental model is that a CIM document represents the
artifact (file, web page, ...) produced by serialising one of the
entities stereotyped <<document>> in the CIM logical model. Such a
serialised CIM entity can of, course, _refer_ to other CIM documents via
its various URL-type properties.

However, if we need the ability to output CIM documents that contain the
definitions of 2+ CIM entities then presumably we'd need either to i)
modify the definition of a CIM document to allow this; or ii) introduce
a new CIM collection entity such as the CIMRecordSet or CIMContainer as
proposed in previous emails. This mirrors GML's feature collection
approach ... I think!

Personally I don't have a strong preference, but my understanding has
always been that the Metafor group wanted to adopt the
one-document-one-entity idiom, so this would tend to suggest option ii)
above.

I think that's pretty much it - at least from my perspective. If I've missed anything out, apologies and feel free to add in your views.

Actually for completeness here is Allyn's proposed modified CIM xml structure (quoting Allyn's email) ...

I suggest having new root element, <CIMRecordSet>, that can contains 1 or more <CIMRecords>.  A <CIMRecord> still has only one object.
 
<CIMRecordSet>
  <CIMRecord>
    <ModelComponent>
    ...foo foo foo...
    </ModelComponent>
  </CIMRecord>
  <CIMRecord>
    <ModelComponent>
    ...bar bar bar...
    </ModelComponent>
  </CIMRecord>
</CIMRecordSet>

[allyn]

Updated code to include a top-level CIMRecordSet element [1199]. This allows a CIM Document to include a single CIM Record (as before) or a single CIM RecordSet?. A CIM Record includes a single CIM Object (as before). A CIM RecordSet? includes one or many CIM Records.

As it stands right now nested Records can be separate documents, so they have been implemented as references. This means the structure of a RecordSet? is a _bit_ convoluted:

<CIMRecordSet>
    <id>myId</id>
  <CIMRecord>
    <reference href="blah.blah.blah/someID/>
  </CIMRecord>
  <CIMRecord>
    <!-- here's the counter-intuitive bit; note the repetition of the "CIMRecord" element" -->
    <CIMRecord>
      <id>someOtherID</id>
      <modelComponent>
        ...
      </modelComponent>
    </CIMRecord>
  </CIMRecord>
</CIMRecordSet>

[phil]

I'd agree with what's being proposed here. It seems like a sufficiently generic and flexible solution, one that will allow as to combine CIM entities in different ways.

I'd also reinforce the proposal to constrain CIMRecords to only containing a single CIM Object and not nested CIMRecords. In this situation the outer CIMRecord would simply be a CIMRecordSet. The implication being that CIMRecordSets can be nested, but not CIMRecords. Allyn's example would then become:

<CIMRecordSet>
    <id>myId</id>
  <CIMRecord>
    <reference href="blah.blah.blah/someID/>
  </CIMRecord>
  <CIMRecordSet>
    <CIMRecord>
      <id>someOtherID</id>
      <modelComponent>
        ...
      </modelComponent>
    </CIMRecord>
  </CIMRecordSet>
</CIMRecordSet>

[allyn]

This feature has been modified slightly.  It turned out that the CIMRecord class was not being used - It simply wrapped a CIM Object and added no value of its own.  Therefore, this has been removed.  The CIMRecordSet has been kept as a container for multiple objects (but renamed to CIMDocumentSet).  This was all done in response to ticket #901