Create conceptual model?

[jonblower]

It probably wouldn't be too hard to create a conceptual model of CoverageJSON (i.e. the major classes and the relationships between them), e.g. in UML.

A logical model (i.e. "a specific way to organize the information into classes and properties") might be a bit harder, particularly if we attempt to capture all the possible rules and relationships, but would be tractable at some level.

We might expect some conformance with CIS at the conceptual level, probably less at the logical level.

(The above was inspired by an email from @jerstlouis)

[jerstlouis]

@jonblower I think the priority for the mapping effort should be to define the CoverageJSON logical model, and demonstrating that it conforms to the CIS conceptual model, specifically at minimum for the following conformance classes:

• coverage
• grid-regular

(and if applicable)

• grid-irregular
• discrete-pointcloud

That should also allow to conform to the other-format-coverage conformance class (which is somewhat of an oddity that in my opinion would not be needed if conceptual and logical models were separated, as I pointed out in this issue).

So that primarily means:

• What CoverageJSON logical constructs provide the information required to populate the CIS DomainSet (e.g. the axes in both gridspace and spatio-temporal space, their bounds and resolution), and how to interpret them to correctly formulate that information according to the CIS concepts?
  • You can find an example DomainSet for a single value / ValueIsPoint coverage here or a multi-value / ValueIsArea coverage here (both regular GeneralGridCoverages)
• What CoverageJSON logical constructs provide the information required to populate the CIS RangeType (e.g. the description of the type of values found in each cell, the name of those values/bands, and their semantics), and how to interpret them to correctly formulate that information according to the CIS concepts?
  • You can find an example RangeType for a single value / ValueIsPoint coverage here or a multi-value / ValueIsArea coverage here (both regular GeneralGridCoverages)
• What CoverageJSON logical constructs provide the information required to populate the CIS RangeSet (the actual data values), and how to interpret them to correctly formulate that information according to the CIS concepts?
  • As far as I understand (the current published specification lacks description for the JSON encoding and the examples are conflicting / ambiguous), in CIS JSON the RangeSet for gridded coverages is a unidimensional JSON array of M x N x ... values where M is (high bound - low bound + 1) of the first gridspace axis, same for N for the second gridspace axis etc. Updated examples are found here, such as this one.

If CoverageJSON provides some richer constructs that do not correspond to anything found in the CIS conceptual model, we should review whether they correspond to any concepts in Abstract Topic 6, and perhaps consider them as potential extensions to the CIS conceptual model.

[chris-little]

@jonblower @jerstlouis I think we need to do some work at the conceptual model level, if only to confirm, or not, that CoverageJSON is a concrete implementation of the ISO19123-1 Abstract Model. I can produce a list of assertions from the Standard that can be checked. This forms part of the work of a producing a discussion paper on this topic, mentioned in the Business Justification work plan. @jerstlouis The CoverageJSON supporters agreed last week that we would initially fix some weaknesses/sloppiness in the existing CoverageJSON specification, hopefully without requiring any implementaton changes. This might be useful complementary work.

[jerstlouis]

@chris-little I think it needs to be clarified whether CIS has a conceptual aspect to it as well, or if it is purely logical and all conceptual aspects are covered by Abstract Topic 6 / ISO10123(-1).

My suggestion to establish the logical model in CoverageJSON is also precisely to confirm whether they are a concrete implementation of the concepts in CIS and/or ISO19123(-1), by starting to map those logical constructs to those concepts.

[chris-little]

The OGC Architecture Board at its review of CoverageJSON on 2022-07-12 suggested that a top level UML diagram might be helpful for some people and help progress the comparison work.

[jonblower]

This is just a rough cut using Mermaid, but could be a starting point for a proper conceptual model. @chris-little I guess we could version control this in the UML folder of this repo?

It seems that Safari's rendering of the diagram does not support the cardinality of the associations (but the renderer in VSCode does).

classDiagram
    CoverageCollection "0..1" o-- "1..*" Coverage

    Coverage "1" *-- "1" Domain
    Coverage "1" *-- "1..*" Parameter
    Coverage "1" *-- "*" ParameterGroup
    Coverage "1" *-- "1..*" Range

    Domain "1" *-- "1..*" Axis
    Domain "1" *-- "*" ReferenceSystem

    Range <|-- NdArray
    Range <|-- TiledNdArray
    TiledNdArray "0..1" *-- "1..*" NdArray

    ParameterGroup "0..1" *-- "1..*" Parameter

[chris-little]

@jonblower I think that this is good enough, but let us ask @samadammeek, as an OAB member, and @ghobona as OGC Staff what they think. This identifies the important CoverageJSON objects and their relationships, as requested by the OAB.
Using Mermaid or even SVG will be really useful.

[jonblower]

Great - if OGC staff are happy with this in principle I'd like to give it another proper pass before declaring it accurate. I did that version in a bit of a hurry.

[ogcscotts]

@jonblower I think that the diagram meets the OAB desire (and clearly illustrates the presence of a Domain and Range)

[chris-little]

@jonblower My only quibble would be whether a Coverage Collection could have zero coverages in it. Or whether an empty Parameter Group, with no Parameters, makes sense. And it shows that the diagram is useful!

[jonblower]

@chris-little sadly the cardinality doesn't appear on the rendered diagram, but the mermaid code defines that a ParameterGroup must have at least one parameter. Maybe it should have at least two? I can't think of a case where you would need fewer than two...

You're right about the CoverageCollection though - that should relate to Coverage with a "1..*" cardinality. I've taken the liberty of correcting that in the above draft diagram (although again it can't be seen in the rendered version).

Another point is whether a Domain needs at least one ReferenceSystem. I think it probably does to make it useful, but I could probably imagine a case of an "unreferenced" domain for certain purposes, although interoperability would be limited. Hence the cardinality of that association is currently "*".

[jonblower]

P.S. I've also updated the diagram to correct the relationships between Range, NdArray and TiledNdArray

[chris-little]

@jonblower I think I would allow a Parameter Group with one Parameter. In practice, people often use MultiPoint, etc for singletons, to simplify parsing and/or out of laziness. No Parameter is definitely an error.

When you are happy with the diagram, we could paste it into the README or somewhere more visible, then add it to the spec when the Public Comment period is finished, for the final pulblication.

[jonblower]

@letmaik what do you think of the UML above? (If you copy the Mermaid markdown code into VSCode or something you'll see a slightly fuller diagram with the cardinalities.) If you're happy then we could put it somewhere visible as Chris suggests.

[letmaik]

FYI: GitHub shows cardinalities now.

I think the conceptual model is overall fine. The logical model would be more involved.

I have two remarks:

1. Range doesn't contain NdArray/TiledNdArray but is one. Is it possible to show inheritance instead of composition?
2. Given that Domain and Range objects are valid top-level CoverageJSON objects, you could argue whether the diamond should be empty like for CoverageCollection and the upstream cardinalities *.

[jonblower]

Thanks @letmaik! Answering your remarks:

1. My first draft had NdArray inheriting from Range as you suggest. Then I realised that the Range is actually a mapping from parameter ids to either NdArray or TiledNdArray objects. So I thought it was more accurate to say that the Range is composed of (Tiled)NdArrays, rather than saying that the NdArray is a subtype of Range.
2. Yes, I wondered that too. The reason I used a composition here is that I think the lifecycle of the Domain is the same as that of the containing Coverage, so I thought it was a stronger association than an aggregation. Having said that, one can imagine using a Domain object independently of the Coverage.

[letmaik]

Regarding Range, kind of. The spec describes "ranges" as a range set object, which then contains range objects in the form of NdArray/TiledNdArray.

[jonblower]

OK, so in that case is it clearer to simply change the "Range" object to "RangeSet" and set the cardinality to 1:1 between Coverage and RangeSet? I've updated the diagram above to try that.

[letmaik]

I wouldn't make range set explicit in the conceptual model, otherwise you'd have to do the same for parameters and axes.

[jonblower]

Yeah OK - maybe I got it right first time then! I've updated it (and the invisible cardinalities)

[samadammeek]

@jonblower @chris-little apologies for missing this. We have a Sparx Cloud instance up and running for collaborative modeling. http://umltool.ogc.org/login.php We can get you a model up and running on there for folks to collaborate on if it's helpful?

[jonblower]

Thanks @samadammeek, much appreciated - I think that could be useful when we get to doing more detailed modelling, but for this top-level conceptual model I'm happy with the simple solution.

[chris-little]

@jonblower @letmaik I suggest that we put the agreed top level conceptual model UML diagram in section 10, just before the first example.

[jonblower]

@jonblower @letmaik I suggest that we put the agreed top level conceptual model UML diagram in section 10, just before the first example.

Agreed - I'll do a PR

[chris-little]

@jonblower I checked the Mermaid diagram above with Edge, Firefox and Chrome, and the cardinalities all seem to display correctly. But not on Safari on my phone running iOS15.6.1

[jonblower]

@chris-little Yeah, looks like Safari is the black sheep here

[jonblower]

@ghobona I can't figure out how to put a figure in the document. I know the PNG has to go in the figures directory but I can't find how to insert it into the text (I've had a look at the Metanorma authoring guide)

[chris-little]

@ghobona Further the @jonblower 's question, can Metanorma cope wth the raw Mermaid code, like Github, or do we have to create a PNG?

[chris-little]

@ghobona We have incorporated a top level conceptual UML diagram into the candidate spec. It may need converting into a PNG or JPG if Metanorma cannot render the Mermaid syntax. So closing this issue, as of 2022-11-30 meeting. May need further issues for Metanorma or logical models as raised by @jerstlouis .