Skip to content

Commit cd3c11f

Browse files
ghobonaghobona
committed
converted chapters 1 to 8 to asciidoc
Next: * convert requirements classes to metanorma asciidoc * convert requirements to metanorma asciidoc * convert conformance classes to metanorma asciidoc * convert abstract tests to metanorma asciidoc * fix tables * fix image widths and captions * add anchors to headers * check cross references to headers * check cross references to figures * check cross references to tables
1 parent ccde78a commit cd3c11f

16 files changed

Lines changed: 21595 additions & 690 deletions

‎part1_core/document.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
= DRAFT OGC Geoscience Markup Language (GeoSciML) - Part 1: Core
1+
= Draft OGC Geoscience Markup Language (GeoSciML) - Part 1: Core
22
:doctype: standard
33
:encoding: utf-8
44
:lang: en
@@ -22,7 +22,7 @@
2222
:pdf-uri: ./document.pdf
2323
:xml-uri: ./document.xml
2424
:doc-uri: ./document.doc
25-
:edition: 1.0
25+
:edition: 5.0-draft
2626

2727
////
2828
Make sure to complete each included document

‎part1_core/document.asciidoc.log.txt‎

Lines changed: 3796 additions & 38 deletions
Large diffs are not rendered by default.

‎part1_core/document.err.html‎

Lines changed: 1340 additions & 82 deletions
Large diffs are not rendered by default.

‎part1_core/document.html‎

Lines changed: 3654 additions & 90 deletions
Large diffs are not rendered by default.

‎part1_core/document.presentation.xml‎

Lines changed: 4576 additions & 58 deletions
Large diffs are not rendered by default.

‎part1_core/document.xml.abort‎

Lines changed: 4433 additions & 384 deletions
Large diffs are not rendered by default.

‎part1_core/sections/clause_8_logical_model.adoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
== Logical Model
22

3+
This section describes requirements that must be met by all target implementations that claim conformance to this specification.  The target implementation of the logical model is generally an encoding specification or a schema (which could use technologies like XSD, for example) and not a data instance.  The logical model, expressed using UML, provides naming, structure and cardinality for any physical implementation.  The UML model is a normative artefact as the official representation of GeoSciML.  Rules that can be unambiguously inferred from the UML model will not be documented as explicit requirements.  Specific encoding idiosyncrasies shall be addressed in the requirement clauses pertaining to that encoding.
4+
5+
The logical model contains almost no semantic requirements (i.e., vocabularies, enumerations).  It is expected that users will employ controlled vocabularies of terms which are developed by user communities.  The model provides mechanisms for delivering concepts from controlled vocabularies via URI’s and linked data principles.
6+
37
include::./clause_8_logical_model_1_uml_model.adoc[]
48

59
include::./clause_8_logical_model_2_geosciml_core_rc.adoc[]

‎part1_core/sections/clause_8_logical_model_1_uml_model.adoc‎

Lines changed: 34 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,37 @@
1-
=== Logical Model
1+
=== UML Model
22

3-
Paragraph
3+
The UML model provides name, structure and cardinality for data elements composing various potential physical implementations of GeoSciML.  There are formal mappings between UML and GML (ISO-19136), UML and RDF (ISO-19150) and best practices exist for mapping UML to RDBMS.  Although it is assumed that UML is technologically neutral, in reality UML models always end up addressing some of the encoding specification details.  The current GeoSciML UML model has been designed as a GML application according to ISO 19109 and borrows some of artefacts of GML. Several design decisions were guided by limitations of UML (e.g. single inheritance) and XSD (package dependencies artefacts) and some constraints of GML delivery using ISO19142 WFS (for instance, some XSD encodings are not queryable easily with ISO19143 FES).  However, the UML model is detailed enough to constrain the main elements of any encoding; the names of entities and the cardinality of properties, the associations between entities and to some extent property types.  On the other hand, some UML features do not have equivalences in certain encoding (for instance, JSON does not have a native support for namespaces or even schema).
44

5-
==== Requirement Class A or Requirement A Example
5+
<<img_logical_model_req_dep>> shows requirements class dependencies:
66

7-
TBA
7+
[[img_logical_model_req_dep]]
8+
.Logical Model Requirements classes dependencies (external dependencies not shown)
9+
image::images/image8.png[width=601,height=357]
10+
11+
This section defines the minimum UML mapping requirements that shall be met by any target claiming compliance to this specification.
12+
13+
==== Property cardinality
14+
15+
All properties that could feasibly be made optional are optional in GeoSciML 4.1.  This is a reversal of the pattern used in GeoSciML version 3.2 where all properties were made mandatory, forcing the data provider to document why the property was missing using nillable properties.  This design attracted a lot of criticism (not only for GeoSciML but for other communities confronted with the same pattern) from application developers and data providers that consider filling the instance with nil properties is “unnecessarily verbose” and a waste of bandwidth.  It has been argued that nillable properties are just verbose absent values.  This issue is a real concern for mobile applications where payload has an impact on user experience.
16+
17+
Nillable properties actually carry useful or even required information in certain use cases, such as legally bounded data exchange scenarios.  Some communities using GeoSciML may still want to force usage of nillable properties and the SWG recognised that different communities might want to enforce the use of some properties for their particular needs.  To meet this requirement and to offer flexibility to various communities wanting to use (or extend) GeoSciML, properties are optional, but can still be nilled.  A data provider is offered two options when a value is missing:
18+
19+
* Omit the property
20+
* Deliver a nilled property with relevant justification.
21+
22+
Which option is most useful for a community is left to that community to decide.  Their decision can be enforced using Schematron.  The editors foresee the use of a) the GeoSciML data model as defined by this specification providing naming and structure and b) a series of community-defined rules to enforce the presence of certain properties relevant to their use cases.  For an XML implementation, this translates into a set of common XSD and SCH to govern conformance to GeoSciML, and community-specific SCH to enforce specific use cases, such as the INSPIRE geology specification ++[++8++]++.
23+
24+
===== Package shortcuts
25+
26+
The following shortcuts are used to refer to external (non GeoSciML) classifiers.
27+
28+
[width="100%",cols="16%,84%",options="header",]
29+
|===
30+
|*Shortcut* |*Full path (HollowWorld)*
31+
|*OM* |ISO TC211/ISO 19156 All/ISO 19156:2011 Observations and Measurements
32+
|*SWE* |OGC/Sensor Web Enablement 2.0/SWE Common Data Model 2.0
33+
|*GEO* |ISO TC211/ISO 19107 All/ISO 19107:2003 Spatial Schema
34+
|*Primitive* |ISO TC211/ISO 19103 All/ISO 19103:2005 Conceptual schema language
35+
|*Temporal* |ISO TC211/ISO 19108 All/ISO 19108:2006 Temporal Schema
36+
|*GML* |ISO TC211/ISO 19136:2007 GML
37+
|===

‎part1_core/sections/clause_8_logical_model_2_geosciml_core_rc.adoc‎

Lines changed: 127 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,130 @@
1-
=== Logical Model
1+
=== GeoSciML Core Abstract Requirements Class (Normative)
22

3-
Paragraph
3+
[width="100%",cols="10%,90%",options="header",]
4+
|===
5+
|*Abstract Requirements Class* |
6+
|/req/gsml4-core |
7+
|*Target type* |Encoding
8+
|*Dependency* |ISO19103:2005 Conceptual Schema Language
9+
|*Dependency* |ISO19107:2003 Spatial Schema
10+
|*Dependency* |ISO19109:2015 Rules for application schemas
11+
|*Dependency* |RFC 3986 Uniform Resource Identifier (URI): Generic Syntax
12+
|*Dependency* |ISO19115-3 Metadata
13+
|*Requirement* a|
14+
*/req/gsml4-core/uml-entity-name*
415

5-
==== Requirement Class A or Requirement A Example
16+
When the target implementation allows it, the exact name of the classifier SHALL be used.
617

7-
TBA
18+
|*Requirement* a|
19+
*/req/gsml4-core/uml-cardinality*
20+
21+
If the target implementation allows it, it SHALL implement the same cardinality of properties and associations as defined in the UML.
22+
23+
|*Requirement* a|
24+
*/req/gsml4-core/uml-abstract*
25+
26+
Abstract classes SHALL NOT be materialised.
27+
28+
|*Requirement* a|
29+
*/req/gsml4-core/uml-polymorphism*
30+
31+
A target implementation SHALL implement type substitutions inferred from the UML model.
32+
33+
|*Requirement* a|
34+
*/req/gsml4-core/quantities-uom*
35+
36+
Quantities and measurements SHALL have explicit units of measure from a governed ontology.
37+
38+
|*Requirement* a|
39+
*/req/gsml4-core/quantities-single-range*
40+
41+
QuantityRange properties that must report a single value SHALL assign both lower and upper value as equal to that single value.
42+
43+
|*Requirement* a|
44+
/req/gsml4-core/codelist
45+
46+
Empty classes with stereotype ++<<++CodeList++>>++ SHALL be implemented as externally governed vocabularies which terms are encoded as URI (RFC 3986).
47+
48+
|===
49+
50+
This section presents requirements to which all target encodings must conform in to order to claim compliance to GeoSciML 4.1.
51+
52+
==== Naming of entities
53+
54+
[width="100%",cols="100%",options="header",]
55+
|===
56+
|*Requirement /req/gsml4-core/uml-entity-name*
57+
|When the target implementation allows it, the exact name of the classifier SHALL be used.
58+
|===
59+
60+
If a target implementation is capable of encoding all the artefacts (classes and properties) using the same names used in UML, it shall do so.  Some target implementations might prevent it; for example, dBase (DBF files) column names are restricted to 10 characters or some RDBMS limits the use of camel case names.  But if the target allows it, the exact names shall be used.
61+
62+
==== Cardinality
63+
64+
[width="100%",cols="100%",options="header",]
65+
|===
66+
|*Requirement /req/gsml4-core/uml-cardinality*
67+
|If the target implementation allows it, it SHALL implement the same cardinality of properties and associations as defined in the UML.
68+
|===
69+
70+
Cardinality shall be the same as defined in UML model.  Since essentially all properties are optional, this clause addresses the upper bounds of cardinality: “1” or “many” in almost all cases.  Therefore, if the UML model limits a property’s maximum cardinality to “1”, then the target implementation cardinality cannot be “many”.
71+
72+
==== Abstract classes
73+
74+
[width="100%",cols="100%",options="header",]
75+
|===
76+
|*Requirement /req/gsml4-core/uml-abstract*
77+
|Abstract classes SHALL NOT be materialised.
78+
|===
79+
80+
 
81+
82+
Not all physical implementations support the concept of an abstract class, or even inheritance and polymorphism.  XSD does support that concept and all its implications, but JSON does not – although JavaScript can somewhat.  This requirement specifies that the encoding specification shall not allow materialisation of an instance of a class stereotyped as abstract.
83+
84+
==== Polymorphism
85+
86+
[width="100%",cols="100%",options="header",]
87+
|===
88+
|*Requirement /req/gsml4-core/uml-polymorphism*
89+
|A target implementation SHALL implement type substitutions inferred from the UML model.
90+
|===
91+
92+
The type hierarchy of the UML model implies type substitutions for property values.  For instance, a property value of type GeologicEvent can be substituted by a value of type DisplacementEvent because DisplacementEvent is a subtype of GeologicEvent.  Many property types are abstract types and only a concrete subtype may be materialised (as per /req/gsml4-core/uml-abstract).  A target implementation shall consider type substitutions using mechanisms available for this implementation.
93+
94+
==== Quantities
95+
96+
[width="100%",cols="100%",options="header",]
97+
|===
98+
|*Requirement /req/gsml4-core/quantities-uom*
99+
|Quantities and measurements SHALL have explicit units of measure from a governed ontology.
100+
|===
101+
102+
The quantities and measurements units of measure shall be taken from a standard vocabulary governed by an appropriate community, for example the Unified Code for Units of Measure (UCUM).
103+
104+
==== QuantityRange
105+
106+
A QuantityRange is a quantity formed of a lower and upper value forming a range of values.  If a single value needs to be represented as a QuantityRange, where the single value is assigned to both lower and upper properties.
107+
108+
[width="100%",cols="100%",options="header",]
109+
|===
110+
|*Requirement /req/gsml4-core/quantities-single-range*
111+
|
112+
|QuantityRange properties that must report a single value SHALL assign both lower and upper value as equal to that single value.
113+
|===
114+
115+
==== Code lists
116+
117+
[width="100%",cols="100%",options="header",]
118+
|===
119+
|*Requirement /req/gsml4-core/codelist*
120+
|Empty classes with stereotype ++<<++CodeList++>>++ SHALL be implemented as externally governed vocabularies which terms are encoded as URI (RFC 3986).
121+
|===
122+
123+
All properties that require formal vocabularies are modelled in the UML as classes having the stereotype ++<<++CodeList++>>++.  The list of valid terms is either prescribed by this specification, with a list of possible entries (Figure 9) or open (i.e., without any terms).
124+
125+
.Example CodeLists, with a) a prescribed list of terms (DescriptionPurpose) and b) 'open' with no prescribed terms (GeologicUnitHierarchyRoleTerm)
126+
image::images/image9.png[width=118,height=96]
127+
128+
When the list is open, the vocabulary is managed externally over the web where each vocabulary term should be encoded as a resource.  Vocabulary term identifiers are URIs representing concepts from a standard vocabulary governed by an appropriate community - for example, the IUGS CGI Geoscience Terminology Working Group (http://www.cgi-iugs.org/tech_collaboration/geoscience_terminology_working_group.html[[.underline]#http://www.cgi-iugs.org/tech++_++collaboration/geoscience++_++terminology++_++working++_++group.html#] and http://resource.geosciml.org/[[.underline]#http://resource.geosciml.org#]) or INSPIRE ++[++8++]++.
129+
130+
This requirement does not require that URIs be actually dereferenceable, but just that a vocabulary term is associated with a syntactically correct URI.

‎part1_core/sections/clause_8_logical_model_3_linked_open_data_rc.adoc‎

Lines changed: 74 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,77 @@
1-
=== Logical Model
1+
=== Linked Open Data Requirements Class (Normative)
22

3-
Paragraph
3+
[width="100%",cols="16%,84%",options="header",]
4+
|===
5+
|*Requirements Class* |
6+
|/req/gsml4-lob |
7+
|*Target type* |Encoding
8+
|*Dependency* |/req/gsml4-core
9+
|*Dependency* |URI
10+
|*Dependency* |HTTP
11+
|*Requirement* a|
12+
/req/gsml4-lod/codelistURI
413

5-
==== Requirement Class A or Requirement A Example
14+
URI used for vocabulary terms SHALL be dereferenceable to one or more representations of the vocabulary term.
615

7-
TBA
16+
|*Requirement* a|
17+
*/req/gsml4-lod/identifier*
18+
19+
HTTP URI used as entity identifiers SHALL be to one or more representations of that entity.
20+
21+
|*Recommendation* a|
22+
/req/gsml4-lod/gsml-representation
23+
24+
Dereferenceable HTTP URI used as identifiers SHOULD provide GeoSciML 4.1 as one of its representations.
25+
26+
|*Requirement* a|
27+
/req/gsml4-lod/byref
28+
29+
External references to an entity conforming to ++[++/req/gsml4-lod/identifier++]++ shall be expressed using this entity identifier.
30+
31+
|===
32+
33+
Although OGC standards are not restricted to a web environment, they are strongly influenced by this environment.  GeoSciML was originally developed specifically for XML, but many other encodings are suitable hypermedia formats (RDF/XML, JSON-LD, HTML).  This requirements class describes extra rules that shall be implemented to turn GeoSciML data instances into hypermedia compatible with Linked Open Data principles.
34+
35+
Linked Open Data is a method to publish structured data on the web.  It leverages existing web technologies such as HTTP (transfer protocol) and URI (addressing over the web) to connect structured resources.  The principle is similar to interconnected web pages through hyperlinks, except that pages are replace with structured information that can be processed by machines.
36+
37+
The following requirements essentially impose that URI used as vocabulary, identifiers and references can be “dereferenced”, which is “_The act of retrieving a representation of a resource identified by a URI_”https://docs.ogc.org/is/16-008/16-008.html#_ftnref2[[.underline]#++[++2++]++#] from the web.  A resource can have multiple representations (GML, XML, RDF, etc.) and this specification does not impose a particular one, although it is common sense in this context to provide a GeoSciML representation for geological features.
38+
39+
It is important to note that a HTTP URI in this context is [.underline]#both# an identifier and a location.  The same identifier is used to refer to any number of representations.  Therefore, different representations are selected through content negotiation with the server.
40+
41+
==== Code lists URI
42+
43+
[width="100%",cols="100%",options="header",]
44+
|===
45+
|*Requirement /req/gsml4-lod/codelistURI*
46+
|URI used for vocabulary terms SHALL be dereferenceable to one or more representations of the vocabulary term.
47+
|===
48+
49+
The requirement described at 8.2.7  in Abstract Requirements Class demand that a vocabulary reference be encoded as a URI, but does not require that the URI actually resolve to anything (it could, but it is not required).  In this class, the target must ensure that the URI used to identify vocabulary terms SHALL dereference to one or more representations of a definition of the term (eg, RDF/SKOS, HTML, GML Definition, etc.)
50+
51+
==== Identifier
52+
53+
[width="100%",cols="100%",options="header",]
54+
|===
55+
|*Requirement /req/gsml4-lod/identifier*
56+
|HTTP URI used as entity identifiers SHALL be to one or more representations of that entity.
57+
|===
58+
59+
This requirement demands that the target ensures that a data instance exposes a URI as a unique identifier for this feature and this identifier SHALL be dereferenceable to one or more representations of that feature.
60+
61+
[width="100%",cols="100%",options="header",]
62+
|===
63+
|*Requirement /req/gsml4-lod/gsml-representation*
64+
|Dereferenceable HTTP URI used as identifiers SHOULD provide GeoSciML 4.1 as one of its representations.
65+
|===
66+
67+
It is expected that one of the representations should be a XML (GML) or any GeoSciML compliant representations, including any profiles derived from this specification.
68+
69+
==== ByReference associations
70+
71+
[width="100%",cols="100%",options="header",]
72+
|===
73+
|*Requirement /req/gsml4-lod/byref*
74+
|External references to an entity conforming to ++[++/req/gsml4-lod/identifier++]++ shall be expressed using this entity identifier.
75+
|===
76+
77+
Serialization of a dataset will often omit the full description of a feature and replace the property value with an external reference.  A reference to this feature is formed by the dereferenceable identifier described in clause 8.3.2. A client ingesting the dataset can use this reference to extract a feature representation if need be.  Over the web, this reference shall be a HTTP URI that can be dereferenced to one or more representations of that feature.

0 commit comments

Comments
 (0)