Writing OGC documents using Metanorma

Document type and stage

Note

Document attributes listed below are unique to the processing of OGC documents in Metanorma.

For common document attributes, see Document attributes reference in general Metanorma author’s documentation. That page describes attributes that apply to all Metanorma flavors, not just OGC.

For an introduction to Metanorma AsciiDoc document attributes and how Metanorma uses them, see the corresponding topic.

:abbrev:

The standard abbreviation of the document, used e.g. in URIs

:doctype:

Mandatory. Document type. Choices:

  • standard: Standard (a document subtype is necessary, see [ogc-docsubtype]) (default)

  • abstract-specification-topic: Abstract Specification

  • best-practice: Best Practice (a document subtype is necessary, see [ogc-docsubtype])

  • change-request-supporting-document: Change Request Supporting Document

  • community-practice: Community Practice

  • community-standard: Community Standard

  • discussion-paper: Discussion Paper

  • engineering-report: Engineering Report

  • other: Note, Primer, etc.

  • policy: Policy, Policy — Name Type Specification

  • reference-model: Reference Model

  • release-notes: Release Notes

  • test-suite: Test Suite

  • user-guide: User Guide

  • white-paper: White Paper

:docsubtype:

Document subtype. Choices:

  • For doctype set to standard:

    • implementation: Implementation (default)

    • conceptual-model: Conceptual model

    • conceptual-model-and-encoding: Conceptual model and encoding

    • conceptual-model-and-implementation: Conceptual model and implementation

    • encoding: Encoding

    • extension: Extension

    • profile: Profile

    • profile-with-extension: Profile with extension

  • For doctype set to best-practice:

    • general: General (default)

    • encoding: Encoding

    • extension: Extension

    • profile: Profile

    • profile-with-extension: Profile with extension

:status:

Document status/stage. Synonym: :docstage:. Choices:

  • swg-draft: SWG Draft. This is the draft created after the TC approval and PC approval votes.

  • oab-review: OAB Review. This is the intended draft for the “OAB + OGC-NA Review”.

  • public-rfc: Public RFC. This is the draft for the (30 days) public comment period.

  • tc-vote: TC Vote. This is the intended draft for the TC adoption and PC adoption votes.

  • published: Published. This is the document intended to be published, after comments are handled with the TC chair (after tc-vote).

  • deprecated: Deprecated. This document has been deprecated.

  • retired: Retired. This document has been retired and no longer considered normative.

:edition:

The version number of the document. Dot-delimited, consists of a major version number, a minor version number, and an optional patch version number; e.g. 2.3.1: major version 2, minor version 3, patch version 1.

:keywords:

Comma-delimited list of the keywords associated with the document.

Note

Abbreviations are sometimes used to designate that a document has a certain document type, document subtype and document stage. This is a mapping from legacy OGC document values to the current normalized list:

“AS” Abstract Specification

Now :doctype: abstract-specification-topic.

“BP” Best Practice

Now :doctype: best-practice.

“CAN” Candidate Standard

Now :doctype: standard and :docstage: swg-draft.

“CC” Conformance Class

Not a standalone document, but a part of a document with :doctype: standard. No longer exists.

“CR” Change Request

Now :doctype: change-request-supporting-document; the actual Change Request is a database entry.

“CS” Community Standard

Now :doctype: community-standard.

“CP” Community Practice

Now :doctype: community-practice.

“DP” Discussion Paper

Now :doctype: discussion-paper.

“DP-Draft” Draft Discussion Paper

Now :doctype: discussion-paper with :docstage: swg-draft.

“IPR” Interoperability Program Report — Engineering Specification

Now :doctype: engineering-report.

“IS” Implementation Standard

Now :doctype: standard, :docsubtype: implementation.

“ISC” Implementation Standard Corrigendum

Now :doctype: standard, :docsubtype: implementation (TBD to indicate corrigendum).

“ISx” Extension Package Standard

Now :doctype: standard, :docsubtype: extension.

“Notes” Notes

Now :doctype: other, there is no specific type for “Notes”.

“ORM” OGC Reference Model

Now :doctype: reference-model.

“PC” Profile Corrigendum

Now :doctype: standard, :docsubtype: profile (TBD to indicate corrigendum).

“PER” Public Engineering Report

Now :doctype: engineering-report.

“POL” Policy

Now :doctype: policy.

“POL-NTS” Policy — Name Type Specification

Now :doctype: engineering-report, there is no specific indication for “NTS”.

“Primer” Primer

Now :doctype: other, there is no specific type for “Primer”.

“Profile” Profile

Now :doctype: standard, :docsubtype: profile.

“RFC” Request for Comment

Now :doctype: standard and :docstage: public-rfc.

“Retired” Retired document

This is a document stage indicated :docstage: retired.

“SAP” Standard Application Profile

Now :doctype: standard, :docsubtype: profile.

“TS”

Test Suite (TBD)

“WhitePaper” Whitepaper

Now :doctype: white-paper.

Author info

:committee:

Mandatory. Name of relevant committee producing the document. Use one of:

  • technical: Technical Committee

  • planning: Planning Committee

  • strategic-member-advisory: Strategic Member Advisory Committee

:subcommittee-type:

The type of the relevant subcommittee producing the document.

:subcommittee-number:

The number of the relevant subcommittee producing the document.

:workingGroup:

Mandatory. Name of relevant working group producing the document.

:workgroup-type:

Type of the relevant workgroup producing the document.

:workgroup-number:

Number of the relevant workgroup producing the document.

:submitting-organizations:

Semicolon-delimited list of the submitting organizations for this document. The organization names themselves may contain commas.

EXAMPLE: University of Calgary, Canada; National Central University, Taiwan

:editor:

Same as :fullname: alongside :role: specified as editor.

URIs and IDs

:external-id:

External identifier referring to this document. If not supplied, a default value is generated: http://www.opengis.net/doc/{abbrevation of doctype}/{abbrev}/{version}. (Version is omitted if not provided. If :abbrev: and :doctype: are not provided, the default value is not generated.

:referenceURLID:

Identifier embedded into a document type-specific external URL.

:previous-uri:

URI of previous version of the document.

Mapping to OGC legacy AsciiDoc

Metanorma-OGC permits legacy OGC AsciiDoc template attributes, and are treated as synonyms of the corresponding Metanorma attributes:

OGC Metanorma AsciiDoc OGC legacy AsciiDoc

:copyright-year:

:copyrightYear

:workgroup:

:workingGroup:

:published-date:

:publicationDate:

:issued-date:

:approvalDate:

:received-date:

:submissionDate:

:docnumber:

:docReference:

:fullname:, with :role: = editor

:editor:

:edition:

:version:

Markup

General

The rendering of OGC documents has changed over the years. Metanorma formats OGC documents following current practice:

  • All body text is left justified, with no exceptions allowed.

  • Where section obligations are named (i.e. in annex names), they are only given as "normative" or "informative"; the alternate text of "non-normative" is disallowed.

  • Ordered lists follow ISO style numbering, i.e. "a), b), c) …​", with no exceptions allowed.

Sections

The Normative References section may be named just “References”, reflecting OGC practice.

Preliminary elements

General

The following clauses are preliminary elements, and are moved into the frontispiece of the document (in Metanorma, the document preface):

  • Abstract

  • Keywords

  • Preface

  • Submitting Organizations

  • Submitters

Note that in OGC documents, all these elements are MANDATORY.

The Foreword and Introduction are not recognised as part of the document preface by default [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.2].

Abstract

The abstract is recognized as the first clause with an abstract style attribute:

[abstract]
== Abstract

This standard describes a conceptual and logical model for the exchange
of groundwater data, as well as a GML/XML encoding with examples.

Preface

General

The “Preface” can be specified in two ways, depending on whether it is a “simple clause”, or a “full clause”.

Simple preface clause

If the “Preface” does not contain subclauses, it is considered a simple preface clause.

A simple preface clause is entered as text after the .Preface label, placed between the AsciiDoc document attributes and the first AsciiDoc section title. It should not be given a section title of its own.

:received-date: 2019-01-01

.Preface

Your preface text...

More preface text...
Full preface clause

If the “Preface” contains subclauses, it needs to be encoded as a full preface clause.

A full preface clause is recognized as a full Metanorma AsciiDoc section, with the title “Preface”. Simple preface content can also be encoded this way. \[added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.1]

:received-date: 2019-01-01

== Preface

Your preface text...

=== Preface sub-clause

More preface text...

Keywords

“Keywords” are entered as document attributes as :keywords:, with the value as a comma-delimited list.

Prefatory text is generated automatically.

EXAMPLE:

:keywords: ogcdoc, OGC document, groundwater, hydrogeology, GWML2

Submitting Organizations

“Submitting Organizations” are entered using the :submitting-organizations: document attribute. The values are entered using a semi-colon delimited list.

Prefatory text is generated automatically.

EXAMPLE:

:submitting-organizations: Geological Survey of Canada (GSC), Canada; U.S. Geological Survey (USGS), United States of America

Submitters

“Submitters” are entered using a table, contained in a section with the title Submitters.

EXAMPLE:

== Submitters

|===
|Name |Affiliation |OGC member

|Steve Liang | University of Calgary, Canada / SensorUp Inc. | Yes
|===

EXAMPLE:

== Submitters

All questions regarding this submission should be directed to the editor or the submitters:

|===
|Name |Affiliation

|Boyan Brodaric |GSC
|Alexander Kmoch |U Salzburg
|===

Examples

Unlike the normal case in Metanorma, examples can have captions:

[example]
.Example caption
====
Text
====

Recommendations, requirements, and permissions

In this clause we will use the term “requirement” to refer to the generic class of recommendations, requirements and permissions.

Note
This subsection supplements Requirement, Recommendation, and Permission blocks in general Metanorma documentation.

Requirement verifications (tests)

A requirement with type=verification is cross-referenced and captioned as a “{Requirement} Test”. It is rendered differently from the actual requirement itself.

Note
Verifications for Recommendations will be captioned as Recommendation Tests, similarly for Requirement Tests and Permission Tests.

Requirement verifications are excluded from the “Table of Requirements” in Word output [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v0.2.10].

A requirement with type=abstracttest is cross-referenced and captioned as an "Abstract Test", and is otherwise rendered identically to a Requirement Verification [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.4].

Requirement classes

A requirement with type=class is cross-referenced and captioned as a “{Requirement} Class”, and is rendered differently to the actual requirement itself [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v0.2.11].

Note
Classes for Recommendations will be captioned as Recommendation Classes, similarly for Requirement Classes and Permission Classes.

Requirement Classes must use the following Metanorma Requirement attributes:

  • Target Type. Specified in the subject attribute.

  • Name. Specified as the requirement’s title.

  • Dependencies (optional). Specified with the inherit attribute (which can take multiple semicolon-delimited values).

  • Nesting (optional). Requirements contained in a class are presented as nested requirements.

A requirement with type=conformanceclass is cross-referenced and captioned as a "Conformance Class", and is otherwise rendered identically to a Requirement Class [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.4].

[requirement,type="class",label="http://www.opengis.net/spec/waterml/2.0/req/xsd-xml-rules[*req/core*]",obligation="requirement",subject="Encoding of logical models",inherit="urn:iso:dis:iso:19156:clause:7.2.2;urn:iso:dis:iso:19156:clause:8;http://www.opengis.net/doc/IS/GML/3.2/clause/2.4;O&M Abstract model, OGC 10-004r3, clause D.3.4;http://www.opengis.net/spec/SWE/2.0/req/core/core-concepts-used"]
.GWML2 core logical model
====

[requirement,type="general",label="/req/core/encoding"]
======
======

[requirement,type="general",label="/req/core/quantities-uom"]
======
======

[recommendation,type="general",label="/req/core/codelist"]
======
======

[requirement,type="general",label="/req/core/codelistURI"]
======
======

[requirement,type="general",label="/req/core/identifier"]
======
======

[requirement,type="general",label="/req/core/feature"]
======
======

====

Legacy Metanorma AsciiDoc syntax

For legacy reasons, a second Metanorma AsciiDoc syntax is permitted for recommendations, requirements and permissions.

In this syntax, Metanorma AsciiDoc tables are used to express the data needed for requirements:

  • Type of requirement. Specified in the first table cell, one of Recommendation, Requirement or Permission. Optionally followed by a number (which is ignored in parsing; the elements are renumbered automatically in rendering.)

  • Internal label. First paragraph of the second table cell.

  • Body of requirement. Second and subsequent paragraphs of the second table cell.

[[recommendation1]]
|===
|Recommendation |/ogc/recommendation/wfs/2 +

If the API definition document uses the OpenAPI Specification 3.0,
the document SHOULD conform to the
<<rc_oas30,OpenAPI Specification 3.0 requirements class>>.
|===