Publication Date: YYYY-MM-DD

Approval Date: YYYY-MM-DD

Submission Date: YYYY-MM-DD

Reference number of this document: OGC XX-XXX

Reference URL for this document: http://www.opengis.net/doc/PER/t14-ID

Category: OGC Public Document

Editor: Jonathan Pritchard IIC technologies

Title: Guide to USe of Marine Geospatial Standards in the Marine Domain

OGC Public Document

COPYRIGHT

Copyright © 2019 Open Geospatial Consortium. To obtain additional rights of use, visit http://www.opengeospatial.org/

WARNING

This document is not an OGC Standard. This document is an OGC Public Document created as a deliverable in an OGC Interoperability Initiative and is not an official position of the OGC membership. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an OGC Standard. Further, any OGC Public Document should not be referenced as required or mandatory technology in procurements. However, the discussions in this document could very well lead to the definition of an OGC Standard.

LICENSE AGREEMENT

Permission is hereby granted by the Open Geospatial Consortium, ("Licensor"), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement.

If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.

THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD. THE INTELLECTUAL PROPERTY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.

This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.

Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications.

This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.

None of the Intellectual Property or underlying information or technology may be downloaded or otherwise exported or reexported in violation of U.S. export laws and regulations. In addition, you are responsible for complying with any local laws in your jurisdiction which may impact your right to import, export or use the Intellectual Property, and you represent that you have complied with any regulations or registration procedures required by applicable law to make this license enforceable.

1. Introduction and Background

Introduction to project, goals aims and objectives.

  • what this report is for

  • objectives of project - overview

  • groups involved at a high level

  • the part OGC plays in development of the standard

  • this is the first project to have been run in this way

2. Background

2.1. Maritime Limits and Boundaries

  • development of UNCLOS

  • background and links for more information

  • relevance to spatial data etc…​

2.2. IHO S-121

  • Background to development of IHO S-121

  • its authorship, development

  • Current status

3. Executive Summary

The Executive Summary clause shall contain the key findings and results in a concise form. A more detailed description of the findings should be in the body of the report.

The Executive Summary shall contain a business value statement that should describe the value of this Engineering Report to improve interoperability, advance location-based technologies or realize innovations.

This section shall include precise descriptions of the requirements that have been addressed by the work documented in this Engineering Report; together with the research motivation that answers the fundamental question: What motivated us to address this topic in this report?

This section provides an overview of recommendations on how to further proceed with the achievements documented in this ER.

This section shall be between 1-3 pages.

3.1. Document contributor contact points

All questions regarding this document should be directed to the editor or the contributors:

Contacts

Name Organization Role

Jonathan Pritchard

IIC Technologies

Editor

3.2. Foreword

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

4. Intro and Summary

5. This Document

6. Background

  • Short history of the relevant parts of UNCLOS, the parts relevant to this project

  • Wider applicability, e.g. MSP and other marine uses. How OGC can fit into that, MSDI as the broad term for these uses of data

6.1. IHO / OGC History

  • Short history of each organisation

  • S-100 for the unitiated, how PS development works, registry, feature catalogue etc.

  • OGC, description of architectural baseline

  • Why do we need this document?

  • The User Perspective

6.2. Structure of Document

7. Specific Topics

7.1. Interoperability

7.2. Encodings

7.3. Topology

7.4. Terms, Definitions and the Registry

7.5. Document contributor contact points

All questions regarding this document should be directed to the editor or the contributors:

Contacts

Name Organization Role

Jonathan Pritchard

IIC Technologies

Editor

8. Example Clause

Note
Instructions

This section explains some concepts frequently required by Asciidoc novices. Please use this file as a template for your own clauses.

8.1. Headlines

All headlines are marked by "=" signs. The top level in each each file starts with level 2 ("=="). Important: For whatever strange reason, headings in annexes are marked differently.

8.2. Figures

If you want to reference a figure by using a figure number, it is important to use the following syntax. The figure identifier for Figure 1 is the first statement of the header. Please adapt the width as appropriate, but generally a width of 800 is good for landscape-shaped figures and 400 is good for portrait-shaped ones.

placeholder
Figure 1. This is an example figure

It is important that you use the same syntax for all images, otherwise the automatic numbering is corrupted!

8.3. Tables

Tables are easy to deal with as long as you keep them simple! To add a table, please use the following syntax.

Table 1. Countries in Europe
Country Population Size

Monaco

36371

1.98

Gibraltar

29431

6.8

The first line is used for referencing. You can reference Table 1 in your text. The only thing you should change in that line is the table id, which is "table_countries" in this case. Please do not remove the "#", please do not change anything else in that line.

You can define the style and width of each column. In our example, the first column takes 50% of the entire width, the second and third column take 25% each. The total width of the table is 75% of the text width.

The letters after the width percentage indicate if the column is e=emphasis, m=monospaced, a=asciidoc, s=strong. The d=default does not need to be set.

Cell alignment: If you need to align a column, you may indicate this by setting ^,<, or >. Examples:

  • ^25m = centered, 25% width, monospaced.

  • >25e = aligned right, 25% width, emphasised

  • <25 = aligned left, 25% width, asciidoc

In any case, please make sure that your table fit on a piece of A4 or letter-size paper!!

8.4. Recommended Asciidoc Environment

We recommend to use asciidoctor and asciidoctor-pdf in combination with the Atom editor.

8.4.1. Installation on MacOS and Linux

  1. Please follow the steps on https://asciidoctor.org/#installation.

  2. Install the bibtex extension: gem install asciidoctor-bibtex

8.4.2. Installation on Windows

We have made best experiences with the following steps:

  1. Install ruby for windows: https://rubyinstaller.org/downloads/. If you experience any issues, the following link may help: stackoverflow

  2. Open command prompt and install two gems:

    1. Execute: "gem install asciidoctor"

    2. Execute: "gem install asciidoctor-bibtex"

  3. Text your installation

    1. Open a folder that contains your Engineering Report asciidoc source files, including the er.adoc file.

    2. Execute the following command: asciidoctor -r asciidoctor-bibtex er.adoc

8.4.3. Using Asciidoctor with Atom

In Atom, you should install the following packages:

  • asciidoc-preview

  • autocomplete-asciidoc

  • language-asciidoc

  • markdown-writer: requires changing of key-map to allow for keyboard shortcuts such as e.g. bold

  • platformio-IDE-terminal

This environment allows you to use keyboard shortcuts, autocomplete, syntax highlighting and a rendered preview for asciidoc; and provides you an terminal window within the editor to convert your asciidoc to html and pdf.

8.5. Asciidoc Conversion

In order to achieve a uniform look-and-feel of all ERs in both HTML and PDF, we have provided a css and theme file. The following commands can be used to convert the ER:

Command for PDF output: asciidoctor-pdf -r asciidoctor-bibtex -a pdf-stylesdir=resources -a pdf-style=ogc -a pdf-fontsdir=resources/fonts er.adoc

Command for HTML output: asciidoctor -r asciidoctor-bibtex -a linkcss -a stylesheet=rocket-panda.css -a stylesdir=./stylesheets er.adoc

8.6. Source Code

You can add code snippets using the following syntax:

Code Example XML
<section>
  <title>Section Title</title> (1)
</section>

  1. This notation allows to reference particular sections within the code.

You can alternatively use line numbers to reference a specific section in your code.

Code Example JSON

  
1
2
3
4
5
6
7
8
9
10
11


  
{"menu": {
  "id": "file",
  "value": "File",
  "popup": {
    "menuitem": [
      {"value": "New", "onclick": "CreateNewDoc()"},
      {"value": "Open", "onclick": "OpenDoc()"},
      {"value": "Close", "onclick": "CloseDoc()"}
    ]
  }
}}

As shown in line 2, the value of "id" is "File".

8.7. Asciidoc(tor) Syntax Help

Is available e.g. here: http://asciidoctor.org/docs/

8.8. Citations

Please use the following syntax to insert citations anywhere in the text:

cite:[VanZyl2009]

or, if it is more than one citation that should be added at the same location, use

cite:[Pross2018,OGCTechTrends2018]

which will create links in the compiled HTML/PDF that look as follows: [1], of for the second example given above, it results in [2, 3]

Then you need to provide all citation information in the file resources/bibtex-file.bib. This file uses the bibtex file format, which is defined in full detail here. The bibtex-style file shall remain untouched.

The conversion of cite:[] takes place at the time of asciidoc-to-pdf/html conversion and requires two things:

  1. The definition of the bibtex-file and the bibtex-style attributes. This is done in this template in file er.adoc. Please make sure that both files are available at their defined locations.

Examples of bibtex attributes as set in file er.adoc

:bibtex-file: resources/bibtex-file.bib
:bibtex-style: resources/lncs.csl

  1. Adding a flag to the asciidoctor conversion command

asciidoctor -r asciidoctor-bibtex er.adoc

A full conversion command could look as in the following example:

asciidoctor -r asciidoctor-bibtex -a linkcss -a s tylesheet=rocket-panda.css -a stylesdir=./resources/stylesheets er.adoc

For further information, please consult https://github.com/asciidoctor/asciidoctor-bibtex.

9. Example using equations in asciidoc

You need to define the equation either as an asciimath inline macro:

\$$\frac{32\ 881\ \ 581.700504}{2^{n + 8}}$\$meters/pixels

as a delimited block:

\$[$\frac{Tsble4at60}{Table4at90} = \frac{4214.27}{4516.57} = 0.933069.$]\$

or use the compact '\' notation

alternative

\[ e^{2\pi \sqrt{-1}} = 1, \]

For the macross, you can use either asciimath or latexmath macro identifiers:

\(\frac{Tsble4at60}{Table4at90} = \frac{4214.27}{4516.57} = 0.933069.\)

Unfortunately, the preview in most tools will not display the equation correctly, see the screenshot from Atom as an example:

mathAtom
Figure 2. Screenshot from Atom editor: the preview shows the raw formular

…​but once compiled with the stem "latexmath" being set, it works well in the html (reason is that the code is actually interpreted by the Javascript engine of the browser).

mathBrowser
Figure 3. Screenshot from Browser: the formular is correctly displayed

That means that the stem is not supported by the asciidoctor-pdf engine, i.e. you cannot produce pdf documents that way. We recommend that you rather use screenshots from the rendered html version for your pdf.

9.1. Compiling AsciiDoc with Equations

To compile this example, you would use

asciidoctor -a stem=latexmath 6-math_example.adoc

9.2. Generate Equations

If you need some help generating equations, http://asciimath.org offers a great equation building and compiling tool and provides further information.

asciiMath
Figure 4. Screenshot AsciiMath equation tool

Appendix A: Abstract Test Suite

An Abstract Test Suite may be relevant to an Engineering Report.

An Abstract Test Suite is specified in Clause 9 and Annex A of ISO 19105. That Clause and Annex specify the ISO/TC 211 requirements for Abstract Test Suites. Examples of Abstract Test Suites are available in an annex of most ISO 191XX documents, one of the more useful is in ISO 19136. Note that this guidance may be more abstract than needed in an OGC® Implementation Standard.

Note
 We skip level 2 headers so that asciidoc correctly numbers the subsections in the appendix.

A.1. Test module for conformance level 1

A.1.1. Conformance level 1

Test identifier

/test/case/id

Test purpose:

Confirm that the IUT satisfies all applicable requirements for conformance level 1.

Test method:

Functional testing performed in an automated and/or manual manner. Verify the behaviour of the IUT for the following operations:

  • GetCapabilities (mandatory)

  • DescribeRecord (mandatory)

  • GetRecords (mandatory)

  • GetRecordById (mandatory)

  • GetRepositoryItem (mandatory)

  • GetDomain (optional)

Requirement:

OGC 07-110: cl. 2.2

Test type:

Capability

A.1.2. Test case for validity of XML response entity

Test identifier

http://www.opengis.net/spec/xxx/conf/WRS.General-ValidResponse

Test purpose:

The XML response entity is valid.

Test method:

Validate content of response entity against corresponding element declaration.

Requirement:

OGC 07-006r1: cl. 10.2.5.1, p. 118

Test type:

Capability

A.2. Test module for conformance level 2

A.2.1. Conformance level 2

Test identifier

/test/case/id

Test purpose:

Confirm that the IUT satisfies all applicable requirements for conformance level 1.

Test method:

Functional testing performed in an automated and/or manual manner. Verify the behaviour of the IUT for the following operations:

  • GetCapabilities (mandatory)

  • DescribeRecord (mandatory)

  • GetRecords (mandatory)

  • GetRecordById (mandatory)

  • GetRepositoryItem (mandatory)

  • GetDomain (optional)

Requirement:

OGC 07-110: cl. 2.2

Test type:

Capability

A.2.2. Test case for validity of XML response entity

Test identifier

http://www.opengis.net/spec/xxx/conf/WRS.General-ValidResponse

Test purpose:

The XML response entity is valid.

Test method:

Validate content of response entity against corresponding element declaration.

Requirement:

OGC 07-006r1: cl. 10.2.5.1, p. 118

Test type:

Capability

Appendix B: XML Schema Documents

XML Schema Documents may be relevant to an Engineering Report.

The term “XML schema“ means all the XML schema parts having the same XML namespace, usually separated into multiple XML Schema Document files (with the file type “.xsd“. The XML schema parts in one XML namespace are usually separated into multiple XML Schema Documents to ease human understanding.

In addition to this document, this report includes several XML Schema Documents. These XML Schema Documents are bundled in a zip file with the present document.

The TBD abilities now specified in this document use TBD specified XML Schema Documents included in the zip file with this document. These XML Schema Documents combine the XML schema fragments listed in various subclauses of this document, eliminating duplications.

These XML Schema Documents roughly match the TBD UML packages described in Annex B, and are named:

TBD.xsd
TBD.xsd

These XML Schema Documents use and build on the OWS common XML Schema Documents specified [OGC 06-121r3], named:

ows19115subset.xsd
owsCommon.xsd
owsDataIdentification.xsd
owsExceptionReport.xsd
owsGetCapabilities.xsd
owsOperationsMetadata.xsd
owsServiceIdentification.xsd
owsServiceProvider.xsd

All these XML Schema Documents contain documentation of the meaning of each element and attribute, and this documentation shall be considered normative as specified in Subclause 11.6.3 of [OGC 06-121r9].

GetCapabilities.xsd
<ows:Operation name="GetCapabilities">
  <ows:DCP>
    <ows:HTTP>
      <ows:Post xlink:href="http://www.opengis.net/?">
        <ows:Constraint name="PostEncoding">
          <allowedValues>
            <ows:Value>SOAP</ows:Value>
          </ows:AllowedValues>
        </ows:Constraint>
      </ows:Post>
    </ows:HTTP>
  </ows:DCP>
</ows:Operation>
<ows:Operation name="GetTile">
  <ows:DCP>
    <ows:HTTP>
      <ows:Post xlink:href="http://www.opengis.net/?">
        <ows:Constraint name="PostEncoding">
          <ows:AllowedValues>
            <ows:Value>SOAP</ows:Value>
          </ows:AllowedValues>
        </ows:Constraint>
      </ows:Post>
    </ows:HTTP>
  </ows:DCP>
</ows:Operation>

Appendix C: UML model

A UML model may be relevant to an Engineering Report. This template thus includes this annex as the place for recording this UML model.

Instructions and guidelines on the usage of UML models are provided in OGC document OGC-121r9.

Appendix D: Revision History

Note
Example History (Delete this note).

replace below entries as needed
Table 2. Revision History
Date Editor Release Primary clauses modified Descriptions

June 15, 2016

I. Simonis

.1

all

initial version

July 22, 2016

I. Simonis

.9

all

comments integrate

September 7, 2016

S. Simmons

1.0

various

preparation for publication

March 23, 2017

I. Simonis

2.0

all

template simplified

January 18, 2018

S. Serich

2.1

all

additional guidance to Editors; clean up headings in appendices

Appendix E: Bibliography

  1. Zyl, T. van, Simonis, I., McFerren, G.: The Sensor Web: Systems of Sensor Systems. International Journal of Digital Earth. 2, 16–30 (2009).

  2. Pross, B., Stasch, C.: OGC Testbed-13: Workflows Engineering Report. Open Geospatial Consortium, http://docs.opengeospatial.org/per/17-029r1.html (2018).

  3. Open Geospatial Consortium: OGC Technology Trends, https://github.com/opengeospatial/OGC-Technology-Trends, (2018).