Open Geospatial Consortium

Submission Date: 2020-07-15

Approval Date:   2020-10-19

Publication Date:   2021-01-28

External identifier of this OGC® document: http://www.opengis.net/doc/pol/ogcapi-naming/1.0

Internal reference number of this OGC® document:    20-059r4

Version: 1.0

Category: OGC® Policy

Editor:   Gobe Hobona

Naming of OGC API Standards, Repositories & Specification Elements

Copyright notice

Copyright © 2020 Open Geospatial Consortium

To obtain additional rights of use, visit http://www.opengeospatial.org/legal/

Warning

This document defines a OGC Policy. It is subject to change without notice. This document is an official position of the OGC membership on this particular topic.

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

Document type:    OGC® Policy

Document subtype:    Name Type Spec

Document stage:    Approved for public release

Document language:  English

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.

i. Abstract

This document is a policy of the OGC Naming Authority (OGC-NA), a sub-committee of the OGC Technical Committee. The document defines a series of policy requirements for OGC API standards, repositories, definitions, and specification elements. The policy document is intended to be a specialization of the OGC-NA policy on naming specification elements (OGC 10-103).

Upon approval of this policy, OGC staff shall proceed to change the names of the Git repositories to conform to the policy.

ii. Keywords

The following are keywords to be used by search engines and document catalogues.

ogcdoc, OGC document, policy, naming authority, OGC API

iii. Preface

This document defines a series of policy requirements for OGC API standards, repositories and specification elements. It is subject to change without notice.

iv. Submitting organizations

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

Organization name(s)

Open Geospatial Consortium

v. Submitters

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

Table 1. Contacts
Name Affiliation

Gobe Hobona

OGC

Scott Simmons

OGC

Clemens Portele

interactive instruments

1. Scope

This policy document applies to OGC API standards, repositories, definitions, and specification elements. Within the context of this policy, the term 'specification elements' refers to:

  • Requirements Classes

  • Requirements

  • Conformance Classes

  • Conformance Tests

2. Conformance

This policy defines a series of policy requirements for OGC API standards.

Conformance with this policy shall be checked manually through review, or through automation where possible.

3. References

OGC: OGC 05-020r25, Technical Committee Policies and Procedures, http://docs.opengeospatial.org/pol/05-020r25/05-020r25.html (2017)

OGC: OGC 09-046r5, OGC Naming Authority – Procedures, http://www.opengeospatial.org/standards/na (2018)

4. Terms and Definitions

This document uses the terms defined in Sub-clause 5.3 of [OGC 06-121r8], which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this standard.

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the 'ModSpec'.

For the purposes of this document, the following additional terms and definitions apply.

4.1. conformance test

test, abstract or real, of one or more requirements contained within a standard, or set of standards (source: OGC 08-131r3)

4.2. conformance test class

set of conformance test modules that must be applied to receive a single certificate of conformance (source: OGC 08-131r3)

Note
When no ambiguity is possible, the word "test" may be left out, so conformance test class maybe called a conformance class.

4.3. requirement

expression in the content of a document conveying criteria to be fulfilled if compliance with the document is to be claimed and from which no deviation is permitted (source: ISO/IEC Directives Part 2)

4.4. requirements class

aggregate of all requirement modules that must all be satisfied to satisfy a conformance test class (source: OGC 08-131r3)

Note
There is some confusion possible here, since the testing of indirect dependencies seems to violate this definition. But the existence of an indirect dependency implies that the test is actually a test of the existence of the relationship from the original target to something that has a property (satisfies a condition or requirement from another requirements class).

4.5. specification

document containing recommendations, requirements and conformance tests for those requirements (source: OGC 08-131r3)

Note
This definition is included for completeness. See Clause 5.3 of The Specification Model — A Standard for Modular specifications (OGC 08-131r3). This does not restrict what else a standard may contain, as long as it does contain the three types of element cited.

4.6. standard

specification that has been approved by a legitimate Standards Body (source: OGC 08-131r3)

Note
This definition is included for completeness. Standard and specification can apply to the same document. While specification is always valid, standard only applies after the adoption of the document by a legitimate standards organization. The legitimate Standards Bodies for OGC consist of OGC, ISO and any of the other standards bodies accepted and used as a source of normative references by OGC or ISO in their standards. In the normal meaning of the word "standard", there are other conditions that may be required, but this standard has chosen to ignore them in the process of abstraction.

4.7. standardization target

entity to which some requirements of a standard apply (source: OGC 08-131r3)

Note
The standardization target is the entity which may receive a certificate of conformance for a requirements class.

4.8. Web API

API using an architectural style that is founded on the technologies of the Web (source: DWBP)

5. Conventions

This document uses the normative terms (SHALL, SHOULD, etc) defined in Subclause 5.3 of [OGC 06-121r3], which is based on the ISO/IEC Directives, Part 2: Rules for the structure and drafting of International Standards. In particular, the word 'shall' (not 'must') is the verb form used to indicate a requirement to be strictly followed to comply with this specification.

6. Naming of OGC API Standards, Repositories & Specification Elements

6.1. Introduction

This section presents the normative clauses of this policy. Please note that the clauses relating to specification elements maintain consistency with the OGC-NA Name type specification - specification elements (10-103) policy.

6.1.1. Resource Name Exception

The following clauses make use of a parameter {resourceName}. Except in the case of OGC API - Common and the Environmental Data Retrieval API, the parameter {resourceName} shall be the plural of the name of the type of resource.

6.2. Repositories

This policy document acknowledges that SWGs will create one or more Git repositories on GitHub, Gitlab or other service. To ensure consistency in the naming of Git repositories, SWGs shall be required to name the repositories as follows:

A reference to the previous name or names of the repository shall be clearly recorded on the overview of the repository (typically a file named README.md).

6.3. Standards

Many of the emerging and existing OGC API standards are multi-part standards. This policy document acknowledges that the SWGs will have to plan to accommodate future extensions into their naming of standards. To ensure consistency in the naming of standards and their extensions, SWGs shall be required to name the standards as follows:

  • OGC API - {resourceName} - Part n: {Topic}

'n' refers to the position of the document in the multi-part standard and shall always be greater than zero, whereas {Topic} refers to the topic or theme of the standard. For example, OGC API - Coverages - Part 1: Core

The first in the sequence of parts shall always be reserved for the 'Core' standard and therefore Part 1 is reserved for the 'Core' standard.

6.4. Requirements Classes

The base namespace of Requirements Classes shall indicate the Part number {n} and Version number {v} of the standard as follows. The requirements class shall be indicated by the {reqClass} segment(s) to the right of the '/req' segment.

6.5. Requirements

The base namespace of Requirements shall indicate the Part number {n} and Version number {v} of the standard as follows. The requirement shall be indicated by the {req} segment(s) to the right of the '/req' segment.

6.6. Conformance Classes

The base namespace of Conformance Classes shall indicate the Part number {n} and Version number {v} of the standard as follows. The conformance class shall be indicated by the {confClass} segment(s) to the right of the '/conf' segment.

6.7. Conformance Tests

The base namespace of Conformance Tests shall indicate the Part number {n} and Version number {v} of the standard as follows. The conformance test shall be indicated by the {test} segment(s) to the right of the '/conf' segment.

6.8. Definitions of the standards

The OGC-NA maintains URIs for definitions of several standards, for example OGC API - Features, Sensor Observation Service (SOS) and so forth. To formalize the namespace used for the definitions, this policy states that the URIs of definitions of OGC API standards shall be of the form:

Note that this clause maintains consistency with the OGC Name Type Specification - definitions - part 1 – basic name (09-048r5) policy.

The OGC-NA maintains a register for link relation types at http://www.opengis.net/def/rel. The register shall be used as a look-up and also to track OGC’s submissions to the Internet Assigned Numbers Authority (IANA).

Every link relation type used in an OGC standard shall be registered in the OGC link relation type register.

For link relation types registered outside of the authority "iana", the definition URI shall be used as the value of the rel property of the link. For example, http://www.opengis.net/def/rel/ogc/1.0/conformance.

6.10. Media Types

The OGC-NA maintains a register for media types at http://www.opengis.net/def/media-type.

Every media type used in an OGC standard

  • shall be registered in the OGC media type register,

  • shall include a notation property, and

  • should be registered in the IANA register.

Annex A: Revision History

Date Release Editor Primary clauses modified Description

2020-06-03

0.1

Gobe Hobona

all

Initial text

2020-06-19

0.2

Clemens Portele

multiple

Added sections on registers and fixed sections on URIs

2020-06-20

0.3

Gobe Hobona

6.8, 6.9

Update to registers section

2020-06-23

0.4

Gobe Hobona

6.10

Removed abbreviations section, as per TC decision on 2020-06-22

2020-07-15

0.5

Gobe Hobona

4,6.1,6.2

Addressing comments received from OGC-NA vote.