4.1. Application Programming Interface (API)

4.2. Actuator

4.3. Connected Systems

4.4. Deployment

4.5. Feature

4.6. Feature Collection

4.7. Feature of Interest

4.8. Observation

4.9. Platform

4.10. Procedure

4.11. Property

4.12. Sample

4.13. Sampler

4.14. Sampling Feature

4.15. Sensor

4.16. Sensor Network

4.17. System

6.1.  Identifiers

The normative provisions in this standard are denoted by the URI

http://www.opengis.net/spec/ogcapi-connectedsystems-1/1.0

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

6.2.  URL Templates

URL template notation is used in various places in this document.

Fixed parts of the URL are written as plain string while the variable parts of the URL (i.e., the parameters) are surrounded by curly brackets { }.

In particular, the following parameters are used in various places:

6.3.  Abbreviated terms

In this document the following abbreviations and acronyms are used or introduced:

7.1.  General

OGC Web API Standards enable access to resources using the HTTP protocol and its associated operations (GET, PUT, POST, DELETE, etc.).

OGC API — Connected Systems Standard — Part 1 (aka “this Standard” or “CS API”) defines resource types that allow the provision of metadata about all kinds of devices, hardware components or processes that can transmit and/or receive data via communication networks (a.k.a. connected systems), including sensors, platforms, robots, human observers, forecast models, computer simulations, etc.

This Standard is an extension of the OGC API — Features Standard and defines specific feature collections, feature types and filtering mechanisms that are also dependent on building blocks from the OGC API — Common Standard. Therefore, an implementation of this Standard shall first satisfy the appropriate Requirements Classes from these two Standards. In addition, this Standard has dependencies on some OGC and non-OGC encoding standards. All dependencies are clearly identified in each Requirements Class.

7.2.  Design Considerations

While this is the first version of the OGC API — Connected Systems series, the fine-grained access to sensor related data, including sensor metadata, observations and tasking over the Web has been supported by the OGC Sensor Observation Service (SOS), OGC Sensor Planning Service (SPS) and SensorThings API Standards and their various implementations for many years.

SOS and SPS were designed in the early 2000s and use a Remote-Procedure-Call-over-HTTP architectural style and XML for any payloads, while the SensorThings API Standard is a newer OGC Standard that was the first to adopt the REST architecture style with JSON payloads.

Requirements in the OGC API — Connected Systems Standard (CS API) support all capabilities from these previous Standards, but using a modernized approach that follows the current Web architecture and in particular the W3C/OGC best practices for sharing Spatial Data on the Web as well as the latest OGC API guidelines.

The CS API is designed as an extension of the OGC API — Features Standard which makes it entirely compatible with Features API clients, while still allowing more advanced functionality to access dynamic data associated to features. A clear goal of this approach is to better integrate the GIS and sensor/IoT communities.

Another key design decision was to allow linking to implementations of other OGC API Standards whenever possible, thus allowing a much better integration with the rest of the OGC API ecosystem.

Models from the Semantic Sensor Network Ontology (SOSA/SSN) are the basis for the design of the CS API, and the SensorML language is used as an implementation model to provide concrete implementations of the SOSA/SSN concepts. An alternative GeoJSON encoding of these concepts is also defined.

The CS API defines several resource/feature types in separate requirements classes, any combination of which can be implemented by the server. This allows resources to be distributed across several servers (potentially different implementations of the CS API) and connected via hyperlinks. For example, a given implementation can choose to implement only System and Deployment features and rely on other servers to host complementary metadata such as Procedures, Property Definitions and Features of Interest (i.e., domain features). This is a common use cases since procedure descriptions (i.e., system datasheets) and domain features (e.g., geographical or hydrological features) can typically be shared by many different organizations.

The CS API also help solve several issues for application running in Denied, Disrupted, Intermittent, and Limited (DDIL) environments, e.g., under tactical implementation conditions. This includes:

7.3.  Resource Types

Figure 1 shows a UML class diagram of the Connected Systems API resources (Part 2 resources are shown with a dashed outline).

Figure 1 — Class diagram of API resources

All resources defined in Part 1 of this Standard are feature types, except for the Property Definition resource. Each resource type is defined in its own requirements class. The table below provides an overview of these resource types:

Table 1 — Overview of resource types defined by this Standard

7.4.  Resource Encodings

This Standard also defines encodings that can be used to encode the resource types listed above. Support for these encodings is not required as each encoding is specified in its own requirements class.

Encodings are specified in Clause 19 of this Standard. Each encoding requirements class provides schemas and examples for the supported resource types.

7.5.  Resource Collections

The CS API Standard defines several resource types that are intended to be offered by the server via separate collections. These resource collections are governed by requirements from OGC API — Features — Part 1: Core. Such collections will be referred to as OGC API Collections in the rest of this document.

The CS API makes use of this collection mechanism to allow a server to provide a more organized view of its content, by grouping them into logical collections according to any criteria.

Note that a given resource can be made available through more than one collection endpoints (i.e., collections can overlap). This provides great flexibility for a server to organize resources according to multiple criteria and thus provide different view points to the client simultaneously. See the requirements classes of the different resource types for examples.

When exposing resources via a collection endpoint, the server must indicate the type of the items contained in the collection. This is done using the itemType attribute of the collection. For feature collections, the itemType is always set to feature, so this Standard defines the featureType attribute to further specify the type of features contained in the collection.

Heterogeneous feature collections (i.e., collections containing a mix of feature types) are allowed but this Standard does not define the behavior of such collections.

7.6.  API Endpoints

As described in the previous clause, all resources defined in the CS API Standard are available through collection endpoints.

However, the CS API also defines different types of endpoints that are useful for the following use cases:

{
  "type": "Feature",
  "id": "123",
  ...
  "links": [
    {
      "rel" : "self",
      "title" : "this document",
      "href" : "https://data.example.org/api/collections/uav_systems/123?f=json",
      "type" : "application/geo+json"
    }, {
      "rel" : "canonical",
      "title" : "this resource canonical URL",
      "href" : "https://data.example.org/api/systems/123?f=json",
      "type" : "application/geo+json"
    }
  ]
}

7.7.  Paged Responses

All resource collections support paging via the limit query parameter and the next link, as specified by the OGC API — Features — Part 1: Core Standard.

7.8.  Search & Filtering

The core search capability is based on the OGC API — Features — Part 1: Core Standard and thus supports:

The CS API Standard extends these core search capabilities to include:

Additional filters are defined on a per resource type basis, as shown in the following table:

Table 2 — Query Parameters

See Clause 16, Requirements Class “Advanced Filtering” for more details.

7.9.  Link Relation Types

The following link relation types are defined and used in this Standard:

Table 3 — Link Relation Types

7.10.  Security Considerations

8.1.  Overview

This requirements class regroups core dependencies that all other requirements class inherit. It also provides clarifications on the use of the OGC API — Common Standard constructs.

8.2.  API Landing Page

The landing page provides links to start exploration of the resources offered by an OGC API implementation instance. The OGC API — Common Standard already requires some common links, sufficient for this Standard.

8.3.  API Definition

Every OGC API implementation instance is required to provide a definition document that describes the capabilities of that instance. This definition document can be used by developers to understand the API capabilities, by software clients to connect to the server, or by development tools to support the implementation of servers and clients.

Implementation must comply with requirements defined in the OGC API — Common Standard when generating the API definition document.

8.4.  Resource IDs

Resource IDs are typically generated by the server and are not guaranteed to be globally unique. However, the server must ensure that IDs are unique within a given resource type and/or feature type.

8.5.  Unique Identifiers (UID)

This Standard mandates that some resource types (e.g., feature resources) have a globally unique identifier that is independent of the resource URL. This is needed to carry the identity of the real-world object that a resource represents across services, as multiple servers may host different representations/descriptions of the same object.

Example

8.6.  Coordinate Reference Systems

As the CS API Standard extends OGC API — Features — Part 1: Core, the server is only required to implement support for CRS:84 (longitude, latitude) and CRS:84h (longitude, latitude, height). However, if support for a CRS other than CRS:84 or CRS:84h is needed, the server can also implement requirements from the OGC API — Features — Part 2: Coordinate Reference Systems by Reference Standard.

8.7.  Date/Time Query Parameter

9.1.  Overview

The “System Features” requirements class specifies how system descriptions are provided using the CS API.

The System resource implements the System concept defined in the Semantic Sensor Network Ontology (SOSA/SSN). System resources are used to expose metadata about several kinds of systems and their components, including sensors, actuators, samplers, processes, platforms, etc.

Example

9.2.  System Resource

9.3.  System Canonical URL

The CS API Standard requires that every System resource has a canonical URL.

9.4.  System Resources Endpoints

9.5.  System Feature Collections

Any number of feature collections containing System features can be available at a CS API endpoint, but the server must at least expose one. Members of System feature collections are identified with the feature type sosa:System.

System resources can be grouped into collections according to any arbitrary criteria, as shown in the following examples.

Example

10.1.  Overview

Describing complex systems in terms of a hierarchy of components (or subsystems) is often useful. The “Subsystems” requirements class specifies how such hierarchical systems are described and made discoverable in an implementation of the CS API Standard.

Subsystems (i.e., system components) are regular System features that are made available through a sub-collection of a parent System resource. Subsystems can be any kind of System and can be indefinitely nested.

10.2.  Types of System/Subsystem Associations

Subsystems can be associated to their parent system either by Composition or Aggregation.

Composition means that a subsystem is an integral part of a parent system (i.e., the subsystem cannot or is not usually taken apart from its parent system during its lifetime, except for maintenance). Composition is implemented in the API by creating subsystems as nested resources under their parent system.

Aggregation means that a subsystem is not permanently attached to its parent system (i.e., it can be taken apart and can be attached to different parent systems at different times). Aggregation is implemented in the API using Deployment resources that describe what subsystems are mounted on a parent system at any given time.

Example

10.3.  Subsystem Resource

10.4.  Subsystem Canonical URL

Since subsystems are also System resources, they are required to have a canonical URL as specified by Requirement 5: /req/system/canonical-url.

10.5.  Subsystem Resources Endpoint

Subsystems are accessible as sub-resources of their parent System.

Some systems have interchangeable components that are often called “payloads” (e.g., UAV platform carrying different sensors at different times). Although such payloads can be listed as subsystems by the server, the best way to describe this is by creating a new Deployment resource every time the payloads are changed (the deployment description allows one to explicitly list which payloads are mounted on a platform during a given time period).

10.6.  System Recursive Search

By default, the canonical System resources endpoint only exposes top-level systems (i.e., subsystems are not visible).

Likewise, Subsystem resources endpoints only expose the direct subsystems, but not subsystems nested at deeper levels (i.e., the subsystems of the subsystems and so on).

The recursive query parameter changes the default behavior by instructing the server to process all subsystems recursively (at all levels below the current level).

name: recursive
in: query
required: false
schema:
  type: boolean

10.7.  System Associations

If a System has subsystems, the associations listed below must reference a resource set that includes resources associated to the main system, as well as all its subsystems.

Table 9 — System Associations

11.1.  Overview

The “Deployment Features” requirements class specifies how Deployment descriptions are provided using the CS API.

The Deployment resource implements the Deployment concept defined in the Semantic Sensor Network Ontology (SOSA/SSN) and is used to provide information about the deployment of one or more Systems (with or without payloads) for a specific purpose (often at a specific location and time).

Example

11.2.  Deployment Resource

11.3.  Deployment Canonical URL

The CS API Standard requires that every Deployment resource has a canonical URL.

11.4.  Deployment Resources Endpoints

11.5.  Deployment Feature Collections

Any number of feature collections containing Deployment features can be available at a CS API endpoint, but the server must at least expose one. Members of Deployment feature collections are identified with the feature type sosa:Deployment.

Deployment resources can be grouped into collections according to any arbitrary criteria, as shown in the following examples.

Example

12.1.  Overview

Describing complex deployments in terms of a hierarchy of deployments is often useful. This requirements class specifies how such hierarchical deployments are described and made discoverable using the CS API Standard.

Subdeployments are regular Deployment features that are made available through a sub-collection of a parent Deployment resource.

Example

12.2.  Subdeployment Resource

12.3.  Subdeployment Canonical URL

Since subdeployments are also Deployment resources, they are required to have a canonical URL as specified by Requirement 14: /req/deployment/canonical-url.

12.4.  Subdeployment Resources Endpoint

Subdeployments are accessible as sub-resources of their parent Deployment.

12.5.  Deployment Recursive Search

By default, the canonical Deployment resources endpoint only exposes top-level deployments (i.e., subdeployments are not visible).

Likewise, Subdeployment resources endpoints only expose the direct subdeployments, but not subdeployments nested at deeper levels.

The recursive query parameter changes the default behavior by instructing the server to process all subdeployments recursively (at all levels below the current level).

name: recursive
in: query
required: false
schema:
  type: boolean

12.6.  Deployment Associations

If a Deployment has subdeployments, the associations listed below must reference a resource set that includes resources associated to the main deployment, as well as all its subdeployments.

Table 13 — Deployment Associations

13.1.  Overview

The “Procedure Features” requirements class specifies how Procedure descriptions are provided using the CS API.

A Procedure resource implements the Procedure concept defined in the Semantic Sensor Network Ontology (SOSA/SSN). Procedure resources are used to provide the specifications or methodology implemented by a System to accomplish its task(s).

Example

13.2.  Procedure Resource

13.3.  Procedure Canonical URL

The CS API Standard requires that every Procedure resource has a canonical URL.

13.4.  Procedure Resources Endpoints

13.5.  Procedure Feature Collections

Any number of feature collections containing Procedure features can be available at a CS API endpoint, but the server must at least expose one. Members of Procedure feature collections are identified with the feature type sosa:Procedure.

Procedure resources can be grouped into collections according to any arbitrary criteria, as shown in the following examples.

Example

14.1.  Overview

The “Sampling Features” requirements class specifies how Sampling Feature descriptions are provided using the CS API.

A Sampling Feature resource implements the Sample concept defined in the SSN Ontology. Sampling Features provide information about the sampling strategy used when observing the property of a larger feature (the Feature of Interest).

By analogy, this Standard also uses the concept of Sampling Feature to more precisely identify the part of a Feature of Interest that is being affected by an actuator or process in response to a command.

While Features of Interest exist independently from any system observing or controlling them, Sampling Features are always associated to a specific System resource (which can be either a Sensor, an Actuator or a Sampler) because they define this particular system’s sampling strategy.

Example

14.2.  Features of Interest

In the CS API Standard, the term Feature of Interest is used to specifically mean the Ultimate Feature of Interest whose properties are observed by a sensing system or changed by a controlling system. Features of interest are real-world features from an application domain and they exist independently from any sampling strategy.

While many features of interest represent physical entities or are geospatial in nature, they can also be used to model more abstract concepts.

Example

The sampling feature model used in the CS API also supports “sampling chains”, where several samples are linked via sub-sampling relationships. This is often done when analyzing specimens (or material samples) in a lab, but can also be applied to other types of sampling features. A few examples are provided below.

Example

In this API, observations and commands are always associated to a Sampling Feature, never directly to the ultimate Feature of Interest. Each Sampling Feature resource has an association to the sampled feature (i.e., the feature being sampled) which can be the ultimate Feature of Interest or another (larger) Sampling Feature in the case of a sampling chain.

14.3.  Sampling Feature Resource

In the CS API Standard, Sampling Feature resources are a special kind of feature resource that implements the sosa:Sample concept.

This section defines the attributes and associations that are common to all Sampling Feature resources, but the exact way attributes and associations are encoded in the payload is defined by each encoding. For encodings defined in this document, please see:

Future parts of this Standard will define concrete types of Sampling Features that can be used to document different sampling strategies.

14.4.  Sampling Feature Canonical URL

The CS API Standard requires that every Sampling Feature resource has a canonical URL.

14.5.  Sampling Feature Resources Endpoints

14.6.  Sampling Feature Collections

Any number of feature collections containing Sampling Features can be available at a CS API endpoint, but the server must at least expose one. Members of Sampling Feature collections are identified with the feature type sosa:Sample.

Sampling Feature resources can be grouped into collections according to any arbitrary criteria, as shown in the following examples.

Example

14.7.  Dynamic properties

When some of the sampling feature properties are dynamic, they are also modeled as observations (just like any other property observed on the feature of interest). An association with the datastream containing these observations can optionally be provided along with the sampling feature resource. The way this association is provided is encoding specific.

When the datetime parameter is included in the request, it is also possible to include a “snapshot” of these dynamic properties (i.e., the value of the property that is valid at the requested time) in the feature resource.

15.1.  Overview

The “Property Definitions” requirements class specifies how property definitions are provided using the CS API.

The Property resource implements the Property concept defined in the SSN Ontology. Properties in the scope of the CS API are features of interest properties, including:

The definition is provided by deriving the property from a well known entity referenced in an ontology such as QUDT Quantity Kinds.

Example

15.2.  Property Resource

15.3.  Property Canonical URL

The CS API Standard requires that every Property resource has a canonical URL.

15.4.  Property Resources Endpoints

15.5.  Property Collections

Any number of resource collections containing Property resources can be available at a CS API endpoint, but the server must at least expose one. Members of Property resource collections are identified with the item type sosa:Property.

Property resources can be grouped into collections according to any arbitrary criteria, as shown in the following examples.

Example

16.1.  Overview

The “Advanced Filtering” requirements class specifies additional filtering options that may be used to select only a subset of the resources in a collection.

All filters defined in this section are implemented using URL query parameters and can be used in addition to the ones required by Clause 8.

16.2.  Definitions

description: List of resource local IDs or unique identifiers (URIs).
oneOf:
  - type: array
    title: Local IDs 
    minItems: 1
    items:
      type: string
      minLength: 1
  - type: array
    title: Unique IDs
    minItems: 1
    items:
      type: string
      format: uri

16.3.  Common Resource Query Parameters

name: q
in: query
description: |-
  Comma separated list of keywords used for full-text search.
  Only resources that have textual fields that contain one of the specified keywords are selected.
  The resource `name` and `description` properties are always searched.
  It is up to the server to decide which other textual fields are searched.
required: false
schema:
  type: array
  items:
    type: string
    minLength: 1
    maxLength: 50
explode: false

examples:
  case1:
    summary: One keyword
    value: 'temp'
  case2:
    summary: Several keywords
    value: 'gps,imu'

16.4.  Common Feature Query Parameters

name: geom
in: query
description: |-
  WKT geometry and operator to filter resources on their location or geometry.
  Only features that have a geometry that intersects the value of `geom` are selected.
required: false
schema:
  type: string
examples:
  point:
    value: 'LINESTRING((-86.53 12.45), (-86.54 12.46), (-86.55 12.47))'
  polygon:
    value: 'POLYGON((0 0,4 0,4 4,0 4,0 0))'

16.5.  System Resources Endpoint Query Parameters

16.6.  Deployment Resources Endpoint Query Parameters

16.7.  Procedure Resources Endpoint Query Parameters

16.8.  Sampling Feature Resources Endpoint Query Parameters

16.9.  Property Resources Endpoint Query Parameters

16.10.  Combination of Filter Parameters

Example

16.11.  Indirect Associations

It is recommended that servers implement certain filtering capabilities in a way that does not require a “direct association” to exist between resources.

17.1.  Overview

The “Create/Replace/Delete” requirements class specifies how instances of the resource types defined in this Standard are created, replaced and deleted via a CS API endpoint.

All resources are created, replaced and deleted using CREATE (HTTP POST), REPLACE (HTTP PUT) and DELETE (HTTP DELETE) operations, respectively, as defined by the OGC API — Features — Part 4: Create, Replace, Update and Delete Standard.

OGC API — Features — Part 4: Create, Replace, Update and Delete uses the terms “resources endpoint” and “resource endpoint” to identify the paths where these operations are supported by the server. The following sections provide these endpoints for each resource type defined by the CS API Standard.

17.2.  Systems

The following constraints must be implemented by the server.

17.3.  Subsystems

Subsystems (i.e., system components) can only be created as sub-resources of a parent system, but are updated/deleted at their canonical URL just like any other System resource.

17.4.  Deployments

17.5.  Subdeployments

Subdeployments can only be created as sub-resources of a parent deployment, but are updated/deleted at their canonical URL just like any other Deployment resource.

17.6.  Procedures

17.7.  Sampling Features

Sampling Features are created as sub-resources of a parent system.

17.8.  Property Definitions

Property resources are created, replaced and deleted using HTTP POST, PUT and DELETE operations, respectively.

17.9.  Custom Collections

This clause defines the expected behavior of the server when Resource Collections other than the root collections are exposed by the server (this causes the same resource to be accessible via multiple collections simultaneously).

Adding existing resources to one or more custom collections is done by posting a list of resource URIs to the collection endpoint.

18.1.  Overview

The “Update” requirements class specifies how instances of the feature types defined previously are updated via a CS API endpoint.

All resources are updated using the UPDATE (HTTP PATCH) operation, as defined by the OGC API — Features — Part 4: Create, Replace, Update and Delete Standard.

OGC API — Features — Part 4: Create, Replace, Update and Delete uses the terms “resource endpoint” to identify the paths where the UPDATE operation is supported by the server. The following sections provide these endpoints for each resource type defined by the CS API Standard.

18.2.  Systems

18.3.  Deployments

18.4.  Procedures

18.5.  Sampling Features

18.6.  Derived Properties

19.1.  Requirements Class “GeoJSON Format”

{
  "type": "Feature",
  "id": "123",
  "geometry": {
    "type": "Point",
    "coordinates": [41.8781, -87.6298]
  },
  "properties": {
    "uid": "urn:x-ogc:systems:001",
    "name": "Outdoor Thermometer 001",
    "description": "Digital thermometer located on first floor window 1",
    "featureType": "http://www.w3.org/ns/sosa/Sensor",
    "assetType": "Equipment",
    "systemKind@link": {
      "href": "https://data.example.org/api/procedures/TP60S?f=json",
      "uid": "urn:x-myorg:datasheets:ThermoPro:TP60S:v001",
      "title": "Thermo Pro TP60S",
      "type" : "application/geo+json"
    }
  },
  "links": [
    {
      "rel" : "self",
      "title" : "this document",
      "href" : "https://data.example.org/api/systems/123?f=json",
      "type" : "application/geo+json"
    }, {
      "rel" : "alternate",
      "title" : "this resource as SensorML",
      "href" : "https://data.example.org/api/systems/123?f=sml",
      "type" : "application/sml+json"
    }
  ]
}