Skip to content

Latest commit

 

History

History
71 lines (35 loc) · 4.55 KB

clause_5_conventions.adoc

File metadata and controls

71 lines (35 loc) · 4.55 KB
Raw

Conventions

This section provides details and examples for any conventions used in the document. Examples of conventions are symbols, abbreviations, use of XML schema, or special notes regarding how to read the document.

Identifiers

The normative provisions in this Standard are denoted by the URI

All requirements, permission, recommendations, and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.

APIs

This Standard is primarily concerned with defining the components of a Processes API. That is an API that enables the execution of computing processes, the retrieval of metadata describing their purpose and functionality and the retrieval of the results of the process execution. The reader, however, should be cogniscant of the fact that an implementation of the Processes API as defined in this Standard may be embeded as part of a broader API. For example, a single server may implement the Features and Processes APIs and so common elements (such as the landing page) will contain components of both standards. When the term "API" is encountered in this Standard, the term is in most cases referring only to the components of a Processes API even though an implementation of the Processes API may be part of a broader API implementation.

Schemas

Schemas defined in this Standard are defined using the JSON Schema standard and are encoded using YAML which is a human-friendly data serialization language.

Link relations

To express relationships between resources, RFC 8288 (Web Linking) is used.

The following link relation types are used in this document.

  • alternate: Refers to a substitute for the link’s context.

  • license: Refers to a license associated with the link’s context.

  • monitor: Identifies a resource that can use used to monitor changes in a resource.

  • service-desc: Identifies service description for the context that is primarily intended for consumption by machines.

    • API definitions are considered service descriptions.

    • In this Standard, OpenAPI 3.0 is used to provide a formal, machine readable, definition of the service but other API definition representations can also be used.

  • service-doc: Identifies service documentation for the context that is primarily intended for human consumption.

  • self: Conveys an identifier for the link’s context.

  • up: Refers to a parent document in a hierarchy of documents.

In addition, the following link relation types are used for which no applicable registered link relation type could be identified.

Each resource representation includes an array of links. Implementations are free to add additional links for all resources provided by an implementation of the Processes API.

Use of HTTPS

For simplicity, this Standard only refers to the HTTP protocol. This is not meant to exclude the use of HTTPS. This is simply a shorthand notation for "HTTP or HTTPS". In fact, most servers are expected to use HTTPS, not HTTP.

OGC Web API Standards do not prohibit the use of any valid HTTP option. However, implementers should be aware that optional capabilities which are not in common use could be an impediment to interoperability.

HTTP URIs

This Standard does not restrict the lexical space of URIs used in an implementation of the Processes API beyond the requirements of the HTTP and URI Syntax IETF RFCs. If URIs include reserved characters that are delimiters in the URI subcomponent, these must be percent-encoded. See Clause 2 of RFC 3986 (URI Syntax) for details.