To be completed.

This entire document is a work in progress, and very little work has yet begun to implement the standards described herein. Detail discussed may be removed or superseded without warning; you are advised to follow issues relevant to your work in this list until this document is stable.

Motivation and background

Networks of urban sensors are increasingly prevalent. There are many uses for these devices connected to the Internet of Things, such as sharing car park occupancy, pollution management, weather forecasting, public safety, and reactive traffic systems.

There is a need for a standard that focuses on extensibility, reuse of established standards, and is comparatively trivial to implement as a layer on top of existing software and services. The ontologies and vocabularies recommended are selected because of their relevance to real-time sensor networks, and their ability to be used alongside related standards such as PAS 180 and ISO/IEC 30182:2017, descriptions of the built environment in [[IFC]], or [[CityGML]], or elements of JSON Schema and OpenAPI to create services and web applications.

This document presents a proposed standard for publishing federated networks of sensors and services, focusing on mechanisms for discovery, obtaining real-time and historic data, and contextual data. It does this primarily by clarifying the use of existing standards, resolving ambiguity and omissions for implementation detail, and providing detailed examples. These combined create a linked federation of [[REST]] APIs, enabled by standardised hypermedia.

Maturity

The maturity model comprises different levels that ultimately facilitate data integration across different domains, systems and data models. The aim of this standard is to achieve level six and move closer towards seven.

  1. Data only available through propreitary interfaces
  2. Data available using a single data model and domain-specific interface (e.g. SIRI)
  3. Data available using an HTTP(S) API with developer-focused documentation
  4. Data available using a publish-subcribe model or real-time stream
  5. Data available using a [[REST]] API with a recognised hypermedia suitable for generating user interfaces and client-side validation
  6. Data accompanied by relevant context, such as links to geographic entities in other systems
  7. Data is fully discoverable by automated means
  8. Data is fully filterable, searchable and traversable and comprehensible by automated means

Principles

This standard has been prepared to satisfy the following general principles.

  1. It MUST be possible to discover sensors in different cities and disparate systems by following sequential links from a single national or international entrypoint.
  2. Data SHOULD be accompanied by links to relevant contextual information, through machine-readable hypermedia, and appropriate ontologies and vocabularies.
  3. Options for extensibility SHOULD be maintained and able to coexist within a single system, such as provision for controllers and actuation, data provenance, and the use of non-sensor but otherwise related ontologies.
  4. Implementation MAY take any form (i.e. any sensors, any database, any underlying communications protocols), provided the output and interface conforms to the standards herein.
  5. Entities including sensors MAY be partitioned across multiple APIs, with two-way links.
  6. This standard SHOULD be reuse existing standards, except where no viable option exists, or two standards are incompatible. It SHOULD be possible to integrate data published with this standard with a wide range of other systems and practices.

Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, NOT RECOMMENDED, OPTIONAL, RECOMMENDED, REQUIRED, SHALL, SHALL NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [[!RFC2119]] [[!RFC8174]] when, and only when, they appear in all capitals, as shown here.

Data SHOULD be provided under a licence compatible with the Open Definition unless there are overriding reasons, such as personal data or the IPR resides elsewhere.

Architecture

A federated approach is adopted.

The figure below shows the generalised architecture for a federated network of sensors and services. Implementation details such as the choice of database, sensor hardware, and communications networks shown in blue are outside the scope of this document; implementations are free to choose these details and use any appropriate technology or codebase.

Architecture for an (inter)national network of observatories, linked through shared standards and registration of sensors against shared geographies
Architecture for an (inter)national network, linked through shared standards and registration of sensors against shared geographies

Implementations MAY poll data directly from sensors and transform data in real-time, provided the eventual output is conformant to this standard. Implementations MAY also provide eventual consistency, or separate the archival of historic observations from the access to the latest observations.

Application programming interface (API)

Transport

Serialisation

Hypermedia controls

Use of query parameters

Collections and filtering

TODO: Write some text here.

Spatial selectors

TODO: Write some text here.

Parameter Description

proximityCentre

MUST be used in combination with proximityRadius. Sets the centre of a circular or spherical bounding area depending on whether height is specified. Only resources within the spatial area are returned.

Uses the format: longitude,latitude,height. Height is optional. Longitude and latitude use WGS84. Height is in metres.

proximityRadius

 MUST be used in combination with proximityCentre. Sets the distance from the proximityCentre in metres.
Sub-selectors

TODO: Write some text here.

Condition modifiers

TODO: Write some text here.

Possibility of additional modifiers __in and __begins still under discussion.

Pagination

TODO: Write some text here.

Authentication

Structures, ontologies and properties

Sensor networks and observations

Platform

Sensor

Observation

Sampling

Result

Deployment

System

Feature of interest

Procedures and provenance

The [[vocab-ssn]] ontology provides alignment to the PROV ontology. Should we provide an example of how to do that?

Geography

Alignment to GeoJSON

Creating a valid GeoJSON output will require a properties key in the object. This should be an optional approach for APIs that want to produce valid GeoJSON, by using JSON-LD nesting?

Collections

Observation collection

Response metadata

Pagination

Vocabulary

Classes

Handling of collections and views on collections is yet to be finalised.

Disciplines

List is yet to be finalised.

Observed properties

List is yet to be finalised.

Units

List is yet to be finalised.

Discvovery

Shared geography

The proposal here is to have a national geography API and delegate authority to each city to be able to register sensors against.

Linked data fragments

This is a way of allowing complex queries such as SPARQL against the data, without having to run a full-blown SPARQL database and exposing it to the world. The problem with exposing SPARQL endpoints and hitting them with POST queries for example, is the response cannot be cached. It does not work well with HTTP. Linked data fragments don't have this problem.