OGC API — Moving Features

Open Geospatial Consortium

Submission Date: <2023-05-19>

Approval Date: <yyyy-mm-dd>

Publication Date: <yyyy-mm-dd>

External identifier of this OGC® document: http://www.opengis.net/doc/IS/ogcapi-movingfeatures-1/1.0.draft

Internal reference number of this OGC® document: 22-003

Version: 1.0.draft

Category: OGC® Implementation Specification

Editor: Taehoon Kim, Kyoung-Sook Kim, Mahmoud SAKR, Martin Desruisseaux

OGC API — Moving Features — Part 1: Core

Copyright notice

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

Warning

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

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® Implementation Specification

Document stage: Draft

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.

Table of Contents

1. Scope
2. Conformance
3. References
4. Terms and Definitions
5. Conventions
- 5.1. Identifiers
- 5.2. Use of HTTPS
6. Overview
7. Requirements Class "Moving Feature Collection Catalog"
8. Requirements Class "MovingFeatures"
9. Common Requirements
Annex A: Conformance Class Abstract Test Suite (Normative)
Annex B: Relationship with other OGC/ISO Standards (Informative)
- B.1. Static geometries, features and accesses
- B.2. Temporal Geometries and Moving Features
Annex C: Revision History
Annex D: Bibliography

i. Abstract

Moving feature data can represent various phenomena, including vehicles, people, animals, weather patterns, etc. The OGC API — Moving Features (OGC API — MF) is a Draft Standard defines a standard interface for querying and accessing geospatial data that changes over time, such as the location and attributes of moving objects like vehicles, vessels, or pedestrians. The OGC API — MF provides a standard way to manage these data, which can be helpful for applications such as transportation management, disaster response, and environmental monitoring. OGC API — MF also includes operations for filtering, sorting, and aggregating moving feature data based on location, time, and other properties.

The OGC API — Moving Features — Part 1: Core specifies a set of RESTful web service interfaces and data formats for querying and updating moving feature data over the web. OGC API Standards define modular API building blocks to spatially enable Web APIs in a consistent way. OpenAPI is used to define the reusable API building blocks with responses in JSON and HTML.

The OGC API family of standards is organized by resource type.

Table 1. Overview of Resources
Resource	Path	HTTP Method	Document Reference
Collections metadata	`/collections`	GET, POST	Resource Collections
Collection instance metadata	`/collections/{collectionId}`	GET, DELETE, PUT	Resource Collection
MovingFeatures	`/collections/{collectionId}/items`	GET, POST	Resource MovingFeatures
MovingFeature instance	`/collections/{collectionId}/items /{mFeatureId}`	GET, DELETE	Resource MovingFeature
TemporalGeometrySequence	`/collections/{collectionId}/items /{mFeatureId}/tgsequence`	GET, POST	Resource TemporalGeometrySequence
TemporalPrimitiveGeometry instance	`/collections/{collectionId}/items /{mFeatureId}/tgsequence/{tGeometryId}`	DELETE	Resource TemporalPrimitiveGeometry
Queries for TemporalPrimitiveGeometry	`collections/{collectionId}/items /{mFeatureId}/tgsequence/{tGeometryId}/{queryType}`	GET	TemporalGeometry Query Resources
TemporalProperties instance	`/collections/{collectionId}/items /{mFeatureId}/tproperties`	GET, POST	Resource TemporalProperties
TemporalProperty instance	`/collections/{collectionId}/items /{mFeatureId}/tproperties/{tPropertyId}`	GET, POST	Resource TemporalProperty

ii.Keywords

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

ogcdoc, OGC document, OGC Moving Features, OGC Moving Features JSON, Moving Features Access, API, OpenAPI, REST, trajectory

iii. Preface

OGC Declaration

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

iv. Security Considerations

The OGC API — Moving Features — Part 1: Core Draft Standard does not mandate any specific security controls. However, it was constructed to add security controls without impacting conformance, the same as the OGC API — Common — Part 1: Core.

This document applied the Requirement /req/oas30/security for OpenAPI 3.0 Security support.

v. Submitting organizations

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

Artificial Intelligence Research Center, National Institute of Advanced Industrial Science and Technology
Université libre de Bruxelles
Geomatys
Central Research Laboratory, Hitachi Ltd.
Feng Chia University

vi. Submitters

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

Name

Organization

Kyoung-Sook KIM

Artificial Intelligence Research Center, National Institute of Advanced Industrial Science and Technology

Taehoon KIM

Artificial Intelligence Research Center, National Institute of Advanced Industrial Science and Technology

Mahmoud SAKR

Université libre de Bruxelles

Esteban Zimanyi

Université libre de Bruxelles

Martin Desruisseaux

Geomatys

Akinori Asahara

Central Research Laboratory, Hitachi Ltd.

Chen-Yu Hao

Feng Chia University

1. Scope

The scope of the OGC API — Moving Features — Part 1:Core is to provide a uniform way to access, communicate, and manage data about moving features across different applications, data providers, and data consumers. The OGC API — MF defines a set of API building blocks that enable clients to discover, retrieve, and update information about moving features, as well as a data model for describing moving features and their trajectories.

The OGC API — Moving Features — Part 1:Core Draft Standard defines an API with two goals. First, to provide access to representations of Moving Features that conform to the OGC Moving Features JSON Encoding Standard. Second, to provide functionality comparable to that of the OGC Moving Features Access Standard. The OGC API — Moving Features Draft Standard is an extension of the OGC API — Common and the OGC API — Features Standards.

2. Conformance

This Standard defines two requirements / conformance classes that describe different levels of compliance with the Standard. These requirements / conformance classes help to ensure interoperability between other implementations of the Standard and allow data providers to specify which parts of the Standard they support. The standardization target is "Web APIs".

The conformance classes for OGC API — Moving Features are:

Collection Catalog
Moving Features

The conformance class defines the minimum requirements for an API to be compliant with the OGC API — Moving Features Draft Standard. This includes support for querying and retrieving information about moving features using HTTP GET requests. Also, the conformance class enables clients to add, modify, or delete features from the server using HTTP POST, PUT, and DELETE requests. Lastly, the conformance class adds support for querying and retrieving features based on their temporal characteristics, such as their position at a specific time or their velocity over a given time interval.

Implementers of the OGC API — MF can choose which conformance classes they want to support based on the specific needs of their use case and the capabilities of their software. However, to be considered compliant with the Standard, an implementation shall support at least the Core conformance class.

The URIs of the associated conformance classes are:

Table 2. Conformance class URIs
Conformance class	URI
MovingFeatures Collection Catalog	http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/mf-collection
MovingFeatures	http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/movingfeatures

Conformance with this Standard shall be checked using all the relevant tests specified in Annex A of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing website.

3. References

The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.

Note

OGC 08-131r3: — The Specification Model — A Standard for Modular Specifications (2009). https://portal.opengeospatial.org/files/?artifact_id=34762
OGC 16-120r3: OGC Moving Features Access (2017). https://docs.ogc.org/is/16-120r3/16-120r3.html
OGC 19-045r3: OGC Moving Features Encoding Extension - JSON (2020). https://docs.ogc.org/is/19-045r3/19-045r3.html
OGC 17-069r4: OGC API — Features — Part 1: Core (2022). https://docs.opengeospatial.org/is/17-069r4/17-069r4.html
OGC 20-002: OGC API — Features — Part 4: Create, Replace, Update and Delete (Draft). http://docs.ogc.org/DRAFTS/20-002.html
OGC 19-072: OGC API — Common — Part 1: Core (2023). https://docs.ogc.org/is/19-072/19-072.html
OGC 20-024: OGC API — Common — Part 2: Geospatial Data (Draft). http://docs.ogc.org/DRAFTS/20-024.html
IETF RFC 2387: The MIME Multipart/Related Content-type. https://datatracker.ietf.org/doc/html/rfc2387
IETF RFC 2818: HTTP Over TLS. https://datatracker.ietf.org/doc/html/rfc2818
IETF RFC 3339: Date and Time on the Internet: Timestamps. https://datatracker.ietf.org/doc/html/rfc3339
IETF RFC 3986: Uniform Resource Identifier (URI): Generic Syntax. https://datatracker.ietf.org/doc/html/rfc3986
IETF RFC 7230 to TFC 7235: Hypertext Transfer Protocol (HTTP/1.1). https://datatracker.ietf.org/doc/html/rfc7230, https://datatracker.ietf.org/doc/html/rfc7231, https://datatracker.ietf.org/doc/html/rfc7232, https://datatracker.ietf.org/doc/html/rfc7233, https://datatracker.ietf.org/doc/html/rfc7234, and https://datatracker.ietf.org/doc/html/rfc7235
IETF RFC 7946: The GeoJSON Format. https://datatracker.ietf.org/doc/html/rfc7946
IETF RFC 8288: Web Linking. https://datatracker.ietf.org/doc/html/rfc8288
IETF RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format. https://datatracker.ietf.org/doc/html/rfc8259
Open API Initiative: OpenAPI Specification, Version 3.0. The latest patch version at the time of publication of this standard was 3.1.0. https://spec.openapis.org/oas/v3.1.0.

4. Terms and Definitions

This document used the terms defined in OGC Policy Directive 49, 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 and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the 'ModSpec'. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

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

application programming interface (API): An interface that is defined in terms of a set of functions and procedures, and enables a program to gain access to facilities within an application.
[source: Dictionary of Computer Science - Oxford Quick Reference, 2016]
coordinate: one of a sequence of numbers designating the position of a point
Note 1 to entry: In a spatial coordinate reference system, the coordinate values are qualified by units.
[source: ISO 19111]
coordinate reference system (CRS): coordinate system that is related to an object by a datum
Note 1 to entry: Geodetic and vertical datums are referred to as reference frames.
Note 2 to entry: For geodetic and vertical reference frames, the object will be the Earth. In planetary applications, geodetic and vertical reference frames may be applied to other celestial bodies.
[source: ISO 19111]
dataset: collection of data, published or curated by a single agent, and available for access or download in one or more formats
[source: DCAT]
datatype: specification of a value domain with operations allowed on values in this domain
Examples: Integer, Real, Boolean, String and Date.
Note 1 to entry: Data types include primitive predefined types and user definable types.
[source: ISO 19103]
distribution: represents an accessible form of a dataset
Note 1 to entry: EXAMPLE: a downloadable file, an RSS feed or a web service that provides the data.
[source: DCAT]
dynamic attribute: characteristic of a feature in which its value varies with time
[source: OGC 19-045r3]
feature: abstraction of a real-world phenomena
Note 1 to entry: A feature can occur as a type or an instance. Feature type or feature instance should be used when only one is meant.
[source: ISO 19109]
feature attribute: characteristic of a feature
Note 1 to entry: A feature attribute can occur as a type or an instance. Feature attribute type or feature attribute instance is used when only one is meant.
[source: ISO 19109]
feature table: table where the columns represent feature attributes, and the rows represent features
[source: OGC 06-104r4]
geographic feature: representation of real-world phenomenon associated with a location relative to the Earth
[source: ISO 19101-2]
geometric object: spatial object representing a geometric set
[source: ISO 19107:2003]
leaf: <one parameter set of geometries>
geometry at a particular value of the parameter
[source: ISO 19141]
moving feature: feature whose position changes over time
Note 1 to entry: Its base representation uses a local origin and local coordinate vectors of a geometric object at a given reference time. [source: ISO 19141]
Note 2 to entry: The local origin and ordinate vectors establish an engineering coordinate reference system (ISO 19111), also called a local frame or a local Euclidean coordinate system.[source: ISO 19141]
[source: OGC 19-045r3]
property: facet or attribute of an object referenced by a name
[source: ISO 19143]
resource: entity that might be identified
Note 1 to entry: The term “resource”, when used in the context of an OGC Web API standard, should be understood to mean a web resource unless otherwise indicated.
[source: Dublin Core Metadata Initiative — DCMI Metadata Terms]
resource type: a type of resource
Note 1 to entry: Resource types are re-usable components that are independent of where the resource resides in the API.
[source: OGC 19-072]
trajectory: path of a moving point described by a one parameter set of points
[source: ISO 19141]
web API: API using an architectural style that is founded on the technologies of the Web
[source: W3C Data on the Web Best Practices]
web resource: a resource that is identified by a URI.
[source: OGC 17-069r4]

5. 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.

5.1. Identifiers

The normative provisions in this Standard are denoted by the URI

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

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

5.2. Use of HTTPS

For simplicity, this OGC 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 and not HTTP.

6. Overview

6.1. General

The OGC API — Features Standard enable access to resources using the HTTP protocol and its associated operations (GET, PUT, POST, DELETE, etc.) The OGC API — Common Standard defines a set of features which are applicable to all OGC APIs. Other OGC Standards extend OGC API — Common with features specific to a resource type.

This OGC API — Moving Features — Part1: Core Draft Standard defines an API with the goal to:

Provide a standard interface for creating (HTTP POST), retrieving (HTTP GET), updating (HTTP PUT), and deleting (HTTP DELETE) Moving Features, with conformance to the OGC Moving Features JSON Encoding Standard

Resources exposed through an OGC API may be accessed via a Universal Resource Identifier (URI). The URI representation in this Draft Standard is composed of three sections:

Dataset distribution API: The endpoint corresponding to a dataset distribution, where the landing page resource as defined in OGC API — Common — Part 1: Core is available (subsequently referred to as Base URI or {root}).
Access Paths: Unique paths to Resources.
Query Parameters: Parameters to adjust the representation of a Resource or Resources like encoding format or sub-setting.

Access Paths are used to build resource identifiers. This approach is recommended, but not required. Most resources are also accessible through links to previously accessed resources. Unique relation types are used for each resource.

Table 3 summarizes the access paths and relation types defined in this Standard.

Table 3. Moving Features API Paths
Path Template	Relation	Resource
Collections
{root}/collections	`data`	Metadata describing the Collection Catalog of data available from this API.
{root}/collections/{collectionId}		Metadata describing the Collection Catalog of data which has the unique identifier `{collectionId}`
MovingFeatures
{root}/collections/{collectionId} /items	`items`	Static information of MovingFeature about available items in the specified Collection
{root}/collections/{collectionId} /items/{mFeatureId}	`item`	Static information describing the MovingFeature of data which has the unique identifier `{mFeatureId}`
{root}/collections/{collectionId} /items/{mFeatureId}/tgsequence	`items`	Sequence of TemporalPrimitiveGeometry about available items in the specified MovingFeature
{root}/collections/{collectionId} /items/{mFeatureId}/tgsequence /{tGeometryId}	`item`	Temporal object describing the TemporalPrimitiveGeometry of data which has the unique identifier `{tGeometryId}`
{root}/collections/{collectionId} /items/{mFeatureId}/tgsequence /{tGeometryId}/{queryType}		Identifies an Information Resource of type `{queryType}` associated with the TemporalPrimitiveGeometry instance
{root}/collections/{collectionId} /items/{mFeatureId}/tproperties	`items`	Temporal object information of TemporalProperties about available items in the specified MovingFeature
{root}/collections/{collectionId} /items/{mFeatureId}/tproperties /{tPropertyName}	`item`	Temporal object describing the TemporalProperty of data which has the unique identifier `{tPropertyName}`

Where:

{root} = Base URI for the API server
{collectionId} = An identifier for a specific Collection of data
{mFeatureId} = An identifier for a specific MovingFeature of a specific Collection of data
{tGeometryId} = An identifier for a specific TemporalPrimitiveGeometry of a specific MovingFeature of data
{tPropertyName} = An identifier for a specific TemporalProperty of a specific MovingFeatures of data

Figure 1 shows a UML class diagram for OGC API — Moving Features (OGC API — MF) which represents the basic resources of this Standard, such as Collections, Collection, MovingFeatures, MovingFeature, TemporalGeometrySequence, TemporalPrimitiveGeometry, TemporalProperties, and TemporalProperty. In this Standard, a single moving feature can have temporal geometries, such as a set of trajectories. Also, the moving feature can have multiple temporal properties, and each property can have a set of parametric values.

Figure 1. Class diagram for OGC API — Moving Features

6.2. Search

The core search capability is based on OGC API — Common and thus supports:

bounding box searches,
time instant or time period searches, and
equality predicates (i.e. property=value).

OGC API — Moving Features extends these core search capabilities to include:

spatiotemporal queries for accessing TemporalGeometry resources.

6.3. Dependencies

The OGC API — Moving Features (OGC API — MF) Draft Standard is an extension of the OGC API — Common and the OGC API — Features Standards. Therefore, an implementation of OGC API — MF shall first satisfy the appropriate Requirements Classes from OGC API — Common and OGC API — Features. Also, the OGC API — MF Standard is based on the OGC Moving Features Encoding Extension for JSON (OGC MF-JSON) Standards. Therefore, an implementation of OGC API — MF shall satisfy the appropriate Requirements Classes from OGC MF-JSON. Table 4, Identifies the OGC API — Common and OGC API — Features Requirements Classes which are applicable to each section of this Standard. Instructions on when and how to apply these Requirement Classes are provided in each section.

Table 4. Mapping OGC API — MF Sections to OGC API — Common, OGC API — Features, and OGC MF-JSON Requirements Classes
API — MF Section	API — MF Requirements Class	API — Common, API — Features, MF-JSON Requirements Class
Collections	/req/mf-collection	http://www.opengis.net/spec/ogcapi-common-2/1.0/req/collections, http://www.opengis.net/spec/ogcapi-features-4/1.0/req/create-replace-delete
MovingFeatures	/req/movingfeatures	http://www.opengis.net/spec/ogcapi-features-1/1.0/req/core, http://www.opengis.net/spec/ogcapi-features-4/1.0/req/create-replace-delete, http://www.opengis.net/spec/movingfeatures/json/1.0/req/trajectory, http://www.opengis.net/spec/movingfeatures/json/1.0/req/prism
HTML	inherit all requirement (no modification)	http://www.opengis.net/spec/ogcapi-common-1/1.0/req/html
JSON	inherit all requirement (no modification)	http://www.opengis.net/spec/ogcapi-common-1/1.0/req/json
GeoJSON	inherit all requirement (no modification)	http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson
OpenAPI 3.0	inherit all requirement (no modification)	http://www.opengis.net/spec/ogcapi-common-1/1.0/req/oas30

7. Requirements Class "Moving Feature Collection Catalog"

7.1. Overview

Requirements Class
http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/req/mf-collection
Target type	Web API
Dependency	http://www.opengis.net/spec/ogcapi-common-2/1.0/req/collections
Dependency	http://www.opengis.net/spec/ogcapi-features-4/1.0/req/create-replace-delete

Requirements Class

http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/req/mf-collection

Target type

Web API

Dependency

http://www.opengis.net/spec/ogcapi-common-2/1.0/req/collections

Dependency

http://www.opengis.net/spec/ogcapi-features-4/1.0/req/create-replace-delete

The Moving Feature Collection Catalog requirements class defines the requirements for a moving feature collection. A moving feature collection is an object that provides information about and access to a set of related Moving Features.

7.2. Information Resources

The two resources defined in this Requirement Class are summarized in Table 5.

Table 5. Moving Feature Collection Catalog Resources
Resource	URI	HTTP Method	Description
Collections	`{root}/collections`	GET	Get information which describes the set of available Collections resource
Collections	`{root}/collections`	POST	Add a new resource (Collection) instance to a Collections resource
Collection	`{root}/collections/{collectionId}`	GET	Get information about a specific Collection resource ({collectionId}) of geospatial data
		PUT	Update information about a specific Collection resource ({collectionId})
		DELETE	Delete a specific Collection resource ({collectionId})

7.3. Resource Collections

7.3.1. Overview

The Collections resource supports retrieving and creating operations via GET and POST HTTP methods respectively.

A retrieve operation returns a set of metadata which describes the collections available from this API.
A create operation posts a new Collection resource instance to the collections with this API.

7.3.2. Operation

Retrieve

The retrieve operation is defined in the Collections conformance class of OGC API — Common. No modifications are needed to support MovingFeature resources.

Issue a GET request on {root}/collections path

Support for the HTTP GET method on the {root}/collections path is specified as a requirement in OGC API — Common.

Requirement 1	/req/mf-collection/collections-get
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Common Collections operation requirement `/req/collections/rc-md-op`.

Create

The create operation is defined in the CREATE conformance class of OGC API — Features. This operation targeted Collection resource.

Issue a POST request on {root}/collections path

Support for the HTTP POST method is specified as a requirement in OGC API — Features.

Requirement 2 /req/mf-collection/collections-post

Requirement 2	/req/mf-collection/collections-post
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `CREATE` operation requirement `/req/create-replace-delete/insert-post-op`.
B	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `CREATE` request body requirements `/req/create-replace-delete/insert-body` and `/req/create-replace-delete/insert-content-type`.
C	The content of the request body SHALL be based upon the Collection request body schema.

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature CREATE operation requirement /req/create-replace-delete/insert-post-op.

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature CREATE request body requirements /req/create-replace-delete/insert-body and /req/create-replace-delete/insert-content-type.

The content of the request body SHALL be based upon the Collection request body schema.

Collection Request Body Schema:

type: object
required:
  - itemType
properties:
  title:
    description: human readable title of the collection
    type: string
  updateFrequency:
    description: a time interval of sampling location. The unit is millisecond.
    type: number
  description:
    description: any description
    type: string
  itemType:
    description: indicator about the type of the items in the moving features collection (the default value is 'movingfeature').
    type: string
    default: "movingfeature"

The following example adds a new feature (collection information object) to the feature collections. The feature is encoded as JSON. A pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server.

An Example of Creating a New Collection:

   Client                                                              Server
     |                                                                   |
     | POST /collections   HTTP/1.1                                      |
     | Content-Type: application/json                                    |
     |                                                                   |
     | {                                                                 |
     |   "title": "MovingFeatureCollection_1",                           |
     |   "updateFrequency": 1000,                                        |
     |   "description": "a collection of moving features to manage data  |
     |                   in a distinct (physical or logical) space",     |
     |   "itemType": "movingfeature"                                     |
     | }                                                                 |
     |------------------------------------------------------------------>|
     |                                                                   |
     | HTTP/1.1 201 Created                                              |
     | Location: /collections/mfc_1                                      |
     |<------------------------------------------------------------------|

7.3.3. Response

Retrieve

A successful response to the Collections GET operation is a document that contains summary metadata for each collection accessible through an instance of an API implementation. In a typical deployment of the OGF API — MF, the Collections GET response will list collections of all offered resource types. The collections where the value of the itemType property is MovingFeature are collections of moving features.

Requirement 3 /req/mf-collection/collections-get-success

Requirement 3	/req/mf-collection/collections-get-success
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Common Collections response requirement `/req/collections/rc-md-success`.
B	The content of that response SHALL be based upon the Collections response schema.
C	The `itemType` property of the response schema SHALL be MovingFeature.

An implementation of the OGC API — MF SHALL comply with the OGC API — Common Collections response requirement /req/collections/rc-md-success.

The content of that response SHALL be based upon the Collections response schema.

The itemType property of the response schema SHALL be MovingFeature.

Note	The usage of the `itemType` property is referred from the OGC API — Common item Type section.

Collections GET Response Schema (collections.yaml):

type: object
required:
  - collections
  - links
properties:
  collections:
    type: array
    items:
      $ref: 'collection.yaml'
  links:
    type: array
    items:
      $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml'

The following JSON payload is an example of a response to an OGC API — Moving Features Collections GET operation.

An Example of Collections JSON Payload:

{
  "collections": [
    {
      "id": "mfc-1",
      "title": "MovingFeatureCollection_1",
      "description": "a collection of moving features to manage data in a distinct (physical or logical) space",
      "itemType": "movingfeature",
      "updateFrequency": 1000,
      "extent": {
        "spatial": {
          "bbox": [
            -180, -90, 190, 90
          ],
          "crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
        },
        "temporal": {
          "interval": [
            "2011-11-11T12:22:11Z","2012-11-24T12:32:43Z"
          ],
          "trs": "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"
        }
      },
      "links": [
        {
          "href": "https://data.example.org/collections/mfc-1",
          "rel": "self",
          "type": "application/json"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://data.example.org/collections",
      "rel": "self",
      "type": "application/json"
    }
  ]
}

Create

A successful response to the Collections POST operation is an HTTP status code.

Requirement 4	/req/mf-collection/collections-post-success
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `CREATE` response requirement `/req/create-replace-delete/insert-response` and `/req/create-replace-delete/insert-response-rid`.

7.3.4. Error situations

The requirements for handling unsuccessful requests are provided in the HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP Status Codes.

7.4. Resource Collection

7.4.1. Overview

A Collection information object is the set of metadata that describes a single collection. An abbreviated copy of this information is returned for each Collection in the {root}/collections GET response.

The schema for the collection information object presented in this clause is an extension of the collection schema defined in OGC API — Common and OGC API — Features.

Table 6 defines the set of properties that may be used to describe a collection.

Table 6. Table of collection properties
Property	Requirement	Description
id	M	A unique identifier to the collection.
title	O	A human-readable name given to the collection.
description	O	A free-text description of the collection.
links	M	A list of links for navigating the API (e.g. link to previous or next pages; links to alternative representations, etc.)
extent	O	The spatiotemporal coverage of the collection.
*itemType*	M	Fixed to the value "movingfeature".
*updateFrequency*	O	A time interval of sampling location. The time unit of this property is millisecond.

Note	The id, title, description, links, extent, and itemsType properties were inherited from OGC API — Common and OGC API — Features.

Note	An update frequency is one of the most important properties of moving feature collection. The update frequency can be used to handle the continuity of the moving feature’s trajectory.

Requirement 5	/req/mf-collection/mandatory-collection
A	A collection object SHALL contain all the mandatory properties listed in Table 6.

7.4.2. Operation

Retrieve

The retrieve operation is defined in the OGC API — Common Collection conformance class. No modifications are required to support MovingFeature resources.

Issue a GET request on the {root}/collections/{collectionId} path

The {collectionId} path parameter is the unique identifier for a single collection offered by an API implementation instance. The list of valid values for {collectionId} is provided in the /collections response.

Support for the {root}/collections/{collectionId} path is required by OGC API — Common.

Requirement 6	/req/mf-collection/collection-get
A	An implementation of OGC API — MF SHALL comply with the OGC API — Common Collection operation requirement `http://www.opengis.net/spec/ogcapi-common-2/1.0/req/collections/src-md-op`.

Replace

The replace operation is defined in the REPLACE conformance class of OGC API — Features. This operation targeted Collection resource.

Issue a PUT request on {root}/collections/{collectionId} path

Support for the HTTP PUT method is specified as a requirement in OGC API — Features.

Requirement 7 /req/mf-collection/collection-put

Requirement 7	/req/mf-collection/collection-put
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `PUT` operation requirement `/req/create-replace-delete/update-put-op`.
B	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `PUT` request body requirements `/req/create-replace-delete/update-put-body` and `/req/create-replace-delete/update-put-content-type`.
C	The content of the request body SHALL be based upon the Collection request body schema, except `updateFrequency`. If the `updateFrequency` is included in the request body, the server SHALL ignore it.

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature PUT operation requirement /req/create-replace-delete/update-put-op.

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature PUT request body requirements /req/create-replace-delete/update-put-body and /req/create-replace-delete/update-put-content-type.

The content of the request body SHALL be based upon the Collection request body schema, except updateFrequency.
If the updateFrequency is included in the request body, the server SHALL ignore it.

Note	Once set, the update frequency cannot be changed.

The following example replaces the feature created by the Create Example with a new feature (collection metadata without an update frequency). Once again, the replacement feature is represented as a JSON payload. A pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server.

An Example of Replacing an Existing Collection:

   Client                                                              Server
     |                                                                   |
     | PUT /collections/mfc_1   HTTP/1.1                                 |
     | Content-Type: application/json                                    |
     |                                                                   |
     | {                                                                 |
     |   "title": "MovingFeatureCollection_2",                           |
     |   "description": "Title is changed"                               |
     | }                                                                 |
     |------------------------------------------------------------------>|
     |                                                                   |
     | HTTP/1.1 204 OK                                                   |
     |<------------------------------------------------------------------|

Delete

The delete operation is defined in the DELETE conformance class of OGC API — Features.

Issue a DELETE request on {root}/collections/{collectionId} path

Support for the HTTP DELETE method is specified as a requirement in OGC API — Features.

Requirement 8	/req/mf-collection/collection-delete
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `DELETE` operation requirement `/req/create-replace-delete/delete/delete-op`.

The following example deletes the feature created by the Create Example and replaced with a new feature in the Replace Example. A pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server.

An Example of Deleting an Existing Collection:

   Client                                                              Server
     |                                                                   |
     | DELETE /collections/mfc_1   HTTP/1.1                              |
     |------------------------------------------------------------------>|
     |                                                                   |
     | HTTP/1.1 204 OK                                                   |
     |<------------------------------------------------------------------|

7.4.3. Response

Retrieve

A successful response to the Collection GET operation is a set of metadata that describes the collection identified by the {collectionId} parameter.

Requirement 9 /req/mf-collection/collection-get-success

Requirement 9	/req/mf-collection/collection-get-success
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Common Collection response requirement `/req/collections`.
B	The response SHALL only include collection metadata selected by the request.
C	The content of that response SHALL be based upon the Collection response schema.
D	The `itemType` property of the response schema SHALL be 'movingfeature'.

An implementation of the OGC API — MF SHALL comply with the OGC API — Common Collection response requirement /req/collections.

The response SHALL only include collection metadata selected by the request.

The content of that response SHALL be based upon the Collection response schema.

The itemType property of the response schema SHALL be 'movingfeature'.

Collection GET Response Schema (collection.yaml)

type: object
required:
  - id
  - links
  - itemType
properties:
  id:
    description: identifier of the collection used, for example, in URIs
    type: string
    example: 'address'
  title:
    description: human readable title of the collection
    type: string
    example: 'address'
  description:
    description: a description of the features in the collection
    type: string
    example: 'An address.'
  links:
    type: array
    items:
      $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml'
    example:
      - href: https://data.example.com/buildings
        rel: item
      - href: https://example.com/concepts/buildings.html
        rel: describedby
        type: text/html
  extent:
    $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/extent.yaml'
  itemType:
    description: indicator about the type of the items in the collection
    type: string
    default: 'movingfeature'
  crs:
    description: the list of coordinate reference systems supported by the service
    type: array
    items:
      type: string
    default:
      - 'https://www.opengis.net/def/crs/OGC/1.3/CRS84'
    example:
      - 'https://www.opengis.net/def/crs/OGC/1.3/CRS84'
      - 'https://www.opengis.net/def/crs/EPSG/0/4326'
  updateFrequency:
    description: a time interval of sampling location. The unit is millisecond.
    type: number

The following JSON payload is an example of a response to an OGC API — Moving Features Collection GET operation.

An Example of Collection GET Operation:

{
  "id": "mfc-1",
  "title": "moving_feature_collection_sample",
  "itemType": "movingfeature",
  "updateFrequency": 1000,
  "extent": {
    "spatial": {
      "bbox": [
        -180, -90, 190, 90
      ],
      "crs": [
        "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
      ]
    },
    "temporal": {
      "interval": [
        "2011-11-11T12:22:11Z","2012-11-24T12:32:43Z"
      ],
      "trs": [
        "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"
      ]
    }
  },
  "links": [
    {
      "href": "https://data.example.org/collections/mfc-1",
      "rel": "self",
      "type": "application/json"
    }
  ]
}

Replace

A successful response to the Collection PUT operation is an HTTP status code.

Requirement 10 /req/mf-collection/collection-put-success

Requirement 10	/req/mf-collection/collection-put-success
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `PUT` response requirement `/req/create-replace-delete/update-put-response`.
B	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `PUT` exception requirement `/req/create-replace-delete/update-put-rid-exception`.

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature PUT response requirement /req/create-replace-delete/update-put-response.

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature PUT exception requirement /req/create-replace-delete/update-put-rid-exception.

Delete

A successful response to the Collection DELETE operation is an HTTP status code.

Requirement 11 /req/mf-collection/collection-delete-success

Requirement 11	/req/mf-collection/collection-delete-success
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `DELETE` response requirement `/req/create-replace-delete/delete/response`.
B	If no resource with the identifier exists in the collection, the server SHALL respond with a not-found exception (`404`).

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature DELETE response requirement /req/create-replace-delete/delete/response.

If no resource with the identifier exists in the collection, the server SHALL respond with a not-found exception (404).

7.4.4. Error situations

The requirements for handling unsuccessful requests are provided in the HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP Status Codes.

8. Requirements Class "MovingFeatures"

8.1. Overview

Requirements Class
http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/req/movingfeatures
Target type	Web API
Dependency	http://www.opengis.net/spec/ogcapi-features-1/1.0/req/core
Dependency	http://www.opengis.net/spec/ogcapi-features-4/1.0/req/create-replace-delete
Dependency	http://www.opengis.net/spec/movingfeatures/json/1.0/req/trajectory
Dependency	http://www.opengis.net/spec/movingfeatures/json/1.0/req/prism

Requirements Class

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

Target type

Web API

Dependency

http://www.opengis.net/spec/ogcapi-features-1/1.0/req/core

Dependency

http://www.opengis.net/spec/ogcapi-features-4/1.0/req/create-replace-delete

Dependency

http://www.opengis.net/spec/movingfeatures/json/1.0/req/trajectory

Dependency

http://www.opengis.net/spec/movingfeatures/json/1.0/req/prism

The MovingFeatures requirements class defines the requirements for a moving feature. A moving feature is an object that provides information about and access to TemporalGeometry and TemporalProperties.

8.2. Information Resources

The seven resources defined in this Requirement Class are summarized in Table 7.

Table 7. MovingFeatures Resources
Resource	URI	HTTP Method
MovingFeatures	`{root}/collections/{collectionId}/items`	GET, POST
MovingFeature	`{root}/collections/ {collectionId}/items/ {mfeatureId}`	GET, DELETE
TemporalGeometry	`{root}/collections/ {collectionId}/items/ {mFeatureId}/tgsequence`	GET, POST
TemporalPrimitiveGeometry	`{root}/collections/ {collectionId}/items/ {mFeatureId}/tgsequence/ {tGeometryId}`	DELETE
TemporalGeometry Query	`{root}/collections/ {collectionId}/items/ {mFeatureId}/tgsequence/ {tGeometryId}/{queryType}`	GET
TemporalProperties	`{root}/collections/ {collectionId}/items/ {mFeatureId}/tproperties`	GET, POST
TemporalProperty	`{root}/collections/ {collectionId}/items/ {mFeatureId}/tproperties/ {tPropertiesName}`	GET, POST

8.3. Resource MovingFeatures

8.3.1. Overview

The MovingFeatures resource supports retrieving and creating operations via GET and POST HTTP methods respectively.

A retrieve operation returns a set of features which describes the moving feature available from this API.
A create operation posts a new MovingFeature resource instance to a specific Collection (specified by {collectionId} with this API.

The OGC API — MF Items query is an OGC API — Features endpoint that may be used to catalog pre-existing moving features. If a {mFeatureID} is not specified, the query will return a list of the available moving features. The list of moving features returned to the response can be limited using the bbox, datetime, limit, and subTrajectory query parameters. This behavior and query parameters for use with the Items query are specified in OGC API — Features and OGC API — Common, except subTrajectory parameter.

8.3.2. Query Parameters

Query parameters are used in URLs to define the resources which are returned on a GET request.

The query parameters bbox, datetime, and limit are inherited from OGC API — Common.

Parameter subTrajectory

The subTrajectory query parameter is defined as follows:

Requirement 12 /req/movingfeatures/param-subtrajectory-definition

Requirement 12	/req/movingfeatures/param-subtrajectory-definition
A	The operation SHALL support a query parameter `subTrajectory` with the following characteristics (using an OpenAPI Specification 3.0 fragment): `name: subTrajectory in: query required: false schema: type: boolean style: form explode: false`
B	The `subTrajectory` parameter SHALL be used with `datetime` parameter.
C	If the `subTrajecotry` parameter is "true", the `datetime` parameter SHALL be a bounded interval, not half-bounded intervals or a date-time.

The operation SHALL support a query parameter subTrajectory with the following characteristics (using an OpenAPI Specification 3.0 fragment):

name: subTrajectory
in: query
required: false
schema:
  type: boolean
style: form
explode: false

The subTrajectory parameter SHALL be used with datetime parameter.

If the subTrajecotry parameter is "true", the datetime parameter SHALL be a bounded interval, not half-bounded intervals or a date-time.

Requirement 13 /req/movingfeatures/param-subtrajectory-response

Requirement 13	/req/movingfeatures/param-subtrajectory-response
A	The endpoint SHALL return only a subsequence of the trajectory derived from temporal primitive geometry by the *subTrajectory* operation at a time interval (new start time and new end time) included in the `datetime` parameter, using interpolated trajectory according to the `interpolation` property in TemporalPrimitiveGeometry, if the `subTrajectory` parameter is "true".
B	If the `subTrajectory` parameter is "true", the `datetime` parameter SHALL match all temporal primitive geometry objects in the moving feature or moving feature collection.
C	If the `subTrajectory` parameter is "true", the `interpolation` property in the response SHALL be the same as the temporal primitive geometry’s `interpolation` property value.
D	Apply `subTrajectory` only to resources that intersect a `bbox` parameter, if the `subTrajectory` parameter is provided with a `bbox` parameter.
E	The `subTrajectory` parameter SHALL not be used with the `leaf` parameter.

The endpoint SHALL return only a subsequence of the trajectory derived from temporal primitive geometry by the subTrajectory operation at a time interval (new start time and new end time) included in the datetime parameter, using interpolated trajectory according to the interpolation property in TemporalPrimitiveGeometry, if the subTrajectory parameter is "true".

If the subTrajectory parameter is "true", the datetime parameter SHALL match all temporal primitive geometry objects in the moving feature or moving feature collection.

If the subTrajectory parameter is "true", the interpolation property in the response SHALL be the same as the temporal primitive geometry’s interpolation property value.

Apply subTrajectory only to resources that intersect a bbox parameter, if the subTrajectory parameter is provided with a bbox parameter.

The subTrajectory parameter SHALL not be used with the leaf parameter.

The subTrajectory query parameter is used to select a subsequence of TemporalGeometrySequence for the specified time interval. Each MovingFeature in the MovingFeatures has TemporalGeometrySequence. The subTrajectory parameter is used to implement the subTrajectory operation, which is defined in the OGC Moving Feature Access Standard. This operation required two timestamps (newStartTime and newEndTime) to represent a specified time interval. The time interval for the subTrajectory operation is taken from datetime parameter.

If the subTrajectory parameter is provided by the client, the endpoint SHALL return only a subset of the trajectory derived from temporal primitive geometry by the operation at time (newStartTime and newEndTime) included in the subTrajectory parameter, using interpolated trajectory according to the interpolation property in TemporalPrimitiveGeometry. The interpolation property in the response shall be the same as the original temporal primitive geometry.

Figure 2. Example of a response result with subTrajectory parameter

8.3.3. Operation

Retrieve

The retrieve operation is defined in the Features conformance class of OGC API — Features. Additional support for query parameter subTrajectory is needed to support MovingFeatures resource.

Issue a GET request on {root}/collections/{collectionID}/items path

Support for GET on the {root}/collections/{collectionID}/items path is required by OGC API — Features.

Requirement 14	/req/movingfeatures/features-get
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Features `Features` operation requirement `/req/core/fc-op`.

Create

The create operation is defined in the CREATE conformance class of OGC API — Features. This operation targeted MovingFeature resource.

Issue a POST request on {root}/collections/{collectionID}/items path

Support for the HTTP POST method is specified as a requirement in OGC API — Features.

Requirement 15 /req/movingfeatures/features-post

Requirement 15	/req/movingfeatures/features-post
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `CREATE` operation requirement `/req/create-replace-delete/insert-post-op`.
B	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `CREATE` request body requirements `/req/create-replace-delete/insert-body` and `/req/create-replace-delete/insert-content-type`.
C	The content of the request body SHALL be based upon the *MovingFeature* object and *MovingFeatureCollection* object in OGC Moving Features JSON Encoding Standard.

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature CREATE operation requirement /req/create-replace-delete/insert-post-op.

The content of the request body SHALL be based upon the MovingFeature object and MovingFeatureCollection object in OGC Moving Features JSON Encoding Standard.

The following example adds a new feature (MovingFeature object in MF-JSON) to the specific Collection. The feature is represented as MovingFeature object (or MovingFeatureCollection object) in MF-JSON. A pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server.

An Example of Creating a New MovingFeature Object:

   Client                                                                     Server
     |                                                                          |
     | POST /collections/mfc_1/items   HTTP/1.1                                 |
     | Content-Type: application/geo+json                                       |
     |                                                                          |
     | {                                                                        |
     |   "type": "Feature",                                                     |
     |   "id": "mf_1",                                                          |
     |   "properties": {                                                        |
     |      "name": "car1",                                                     |
     |      "state": "test1",                                                   |
     |      "video": "http://.../example/video.mpeg"                            |
     |   },                                                                     |
     |   "crs": {                                                               |
     |      "type": "Name",                                                     |
     |      "properties": {                                                     |
     |         "name": "urn:ogc:def:crs:OGC:1.3:CRS84"                          |
     |      }                                                                   |
     |   },                                                                     |
     |   "trs": {                                                               |
     |      "type": "Link",                                                     |
     |      "properties": {                                                     |
     |         "type": "ogcdef",                                                |
     |         "href": "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"    |
     |      }                                                                   |
     |   },                                                                     |
     |   "temporalGeometry": {                                                  |
     |      "type": "MovingPoint",                                              |
     |      "datetimes": [                                                      |
     |         "2011-07-14T22:01:01.000Z",                                      |
     |         "2011-07-14T22:01:02.000Z",                                      |
     |         "2011-07-14T22:01:03.000Z",                                      |
     |         "2011-07-14T22:01:04.000Z",                                      |
     |         "2011-07-14T22:01:05.000Z"                                       |
     |      ],                                                                  |
     |      "coordinates": [                                                    |
     |         [139.757083,35.627701,0.5],                                      |
     |         [139.757399,35.627701,2.0],                                      |
     |         [139.757555,35.627688,4.0],                                      |
     |         [139.757651,35.627596,4.0],                                      |
     |         [139.757716,35.627483,4.0]                                       |
     |      ],                                                                  |
     |      "interpolation": "Linear",                                          |
     |      "base": {                                                           |
     |         "type": "glTF",                                                  |
     |         "href": "http://.../example/car3dmodel.gltf"                     |
     |      },                                                                  |
     |      "orientations": [                                                   |
     |          {"scales": [1,1,1],"angles": [0,0,0]},                          |
     |          {"scales": [1,1,1],"angles": [0,355,0]},                        |
     |          {"scales": [1,1,1],"angles": [0,0,330]},                        |
     |          {"scales": [1,1,1],"angles": [0,0,300]},                        |
     |          {"scales": [1,1,1],"angles": [0,0,270]},                        |
     |      ]                                                                   |
     |   },                                                                     |
     |   "temporalProperties": [                                                |
     |      {                                                                   |
     |         "datetimes": [                                                   |
     |            "2011-07-14T22:01:01.450Z",                                   |
     |            "2011-07-14T23:01:01.450Z",                                   |
     |            "2011-07-15T00:01:01.450Z"                                    |
     |            ],                                                            |
     |         "length": {                                                      |
     |            "type": "Measure",                                            |
     |            "form": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Length", |
     |            "values": [1,2.4,1],                                          |
     |            "interpolation": "Linear",                                    |
     |            "description": "description1"                                 |
     |         },                                                               |
     |         "discharge": {                                                   |
     |            "type": "Measure",                                            |
     |            "form": "MQS",                                                |
     |            "values": [3,4,5],                                            |
     |            "interpolation": "Step"                                       |
     |         }                                                                |
     |      },                                                                  |
     |      {                                                                   |
     |         "datetimes": [                                                   |
     |            "2011-07-15T23:01:01.450Z",                                   |
     |            "2011-07-16T00:01:01.450Z"                                    |
     |         ],                                                               |
     |         "camera": {                                                      |
     |            "type": "Image",                                              |
     |            "values": [                                                   |
     |               "http://.../example/image1",                               |
     |               "VBORw0KGgoAAAANSUhEU......"                               |
     |            ],                                                            |
     |            "interpolation": "Discrete"                                   |
     |         },                                                               |
     |         "labels": {                                                      |
     |            "type": "Text",                                               |
     |            "values": ["car","human"],                                    |
     |            "interpolation": "Discrete"                                   |
     |         }                                                                |
     |      }                                                                   |
     |   ]                                                                      |
     | }                                                                        |
     |------------------------------------------------------------------------->|
     |                                                                          |
     | HTTP/1.1 201 Created                                                     |
     | Location: /collections/mfc_1/items/mf_1                                  |
     |<-------------------------------------------------------------------------|

8.3.4. Response

Retrieve

A successful response to the MovingFeatures GET operation is a document that contains the static data for a set of moving features.

If the value of the subTrajectory query parameter is provided, the value of the corresponding temporalGeometry property of each moving feature is calculated using the subTrajectory parameter value and included in the result, i.e., a MovingFeatureCollection object of MF-JSON.

In a typical deployment of the OGF API — MF, the MovingFeatures GET response will list MovingFeature resource.

Requirement 16 /req/movingfeatures/features-get-success

Requirement 16	/req/movingfeatures/features-get-success
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Features `Features` response requirement `/req/core/fc-response`.
B	The response SHALL only include moving features selected by the request with `limit`, `bbox`, `datetime`, and `subTrajectory` parameters.
C	Each moving feature in the response SHALL include the mandatory properties listed in Table 8.

An implementation of the OGC API — MF SHALL comply with the OGC API — Features Features response requirement /req/core/fc-response.

The response SHALL only include moving features selected by the request with limit, bbox, datetime, and subTrajectory parameters.

Each moving feature in the response SHALL include the mandatory properties listed in Table 8.

MovingFeatures GET Response Schema (movingFeatureCollection.yaml):

type: object
required:
  - type
  - features
properties:
  type:
    type: string
    enum:
      - 'FeatureCollection'
  features:
    type: array
    nullable: true
    items:
      $ref: 'movingFeature.yaml'
  crs:
    $ref: "MF-JSON/Prism/crs.yaml"
  trs:
    $ref: "MF-JSON/Prism/trs.yaml"
  bbox:
    $ref: "MF-JSON/Prism/bbox.yaml"
  time:
    $ref: "MF-JSON/Prism/lifeSpan.yaml"
  links:
    type: array
    items:
      $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml'
  timeStamp:
    type: string
    format: date-time
  numberMatched:
    type: integer
    minimum: 0
  numberReturned:
    type: integer
    minimum: 0

The following JSON payload is an example of a response to an OGC API — Moving Features MovingFeatures GET operation.

An Example of a MovingFeatures GET Operation:

{
  "type": "FeatureCollection",
  "features":[
    {
      "id": "mf-1",
      "type": "Feature",
      "temporalGeometry": {
        "type": "MovingPoint",
        "datetimes": ["2011-07-14T22:01:01Z", "2011-07-14T22:01:02Z", "2011-07-14T22:01:03Z", "2011-07-14T22:01:04Z", "2011-07-14T22:01:05Z"],
        "coordinates": [
          [139.757083, 35.627701, 0.5],
          [139.757399, 35.627701, 2.0],
          [139.757555, 35.627688, 4.0],
          [139.757651, 35.627596, 4.0],
          [139.757716, 35.627483, 4.0]
        ],
        "interpolation": "Linear"
      },
      "properties":{
        "label": "car",
        "state": "test1",
        "video": "http://www.opengis.net/spec/movingfeatures/json/1.0/prism/example/video.mpeg"
      },
      "bbox":[
        139.757083, 35.627483, 0.0,
        139.757716, 35.627701, 4.5
      ],
      "time":[
        "2011-07-14T22:01:01Z",
        "2011-07-15T01:11:22Z"
      ],
      "crs": {
        "type": "Name",
        "properties": "urn:ogc:def:crs:OGC:1.3:CRS84"
      },
      "trs": {
        "type": "Name",
        "properties": "urn:ogc:data:time:iso8601"
      }
    }
  ],
  "crs": {
    "type": "Name",
    "properties": "urn:ogc:def:crs:OGC:1.3:CRS84"
  },
  "trs": {
    "type": "Name",
    "properties": "urn:ogc:data:time:iso8601"
  },
  "links":[
    {
      "href": "https://data.example.org/collections/mfc-1/items",
      "rel": "self",
      "type": "application/geo+json"
    },
    {
      "href": "https://data.example.org/collections/mfc-1/items&offset=1&limit=1",
      "rel": "next",
      "type": "application/geo+json"
    }
  ],
  "timeStamp": "2020-01-01T12:00:00Z",
  "numberMatched": 100,
  "numberReturned": 1
}

Create

A successful response to the MovingFeatures POST operation is an HTTP status code.

Requirement 17	/req/movingfeatures/features-post-success
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `CREATE` response requirement `/req/create-replace-delete/insert-response` and `/req/create-replace-delete/insert-response-rid`.

8.3.5. Error situations

The requirements for handling unsuccessful requests are provided in the HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP Status Codes.

8.4. Resource MovingFeature

8.4.1. Overview

A MovingFeature object consists of the set of static information that describes a single moving feature and the set of temporal object, such as temporal geometry and temporal properties. An abbreviated copy of this information is returned for each MovingFeature in the {root}/collections/{collectionId}/items GET response.

Table 8 defines the set of properties that may be used to describe a moving feature. The schema for the moving feature object presented in this clause is an extension of the GeoJSON Feature Object defined in GeoJSON. By default, the properties defined in Table 8 are the same as the MovingFeature Object in OGC MF-JSON. The semantics of each property are also the same as those defined in MF-JSON.

However, depending on where this schema is used (i.e., depending on which resource produces results with which query parameter), there are differences in requirements from the schema defined in MF-JSON; as sometimes it only needs to have static information, and sometimes it also has a temporalGeometry. For example, in MF-JSON, type and temporalGeometry are mandatory, but in this API, id and type are mandatory. This is why the defined schema is represented in GeoJSON, not MF-JSON.

Table 8. Table of the properties related to the moving feature
Property	Requirement	Description
id	M	A unique identifier to the moving feature.
type	M	The GeoJSON feature type (i.e., one of 'Feature' or 'FeatureCollection').
geometry	O	Projective geometry of the moving feature.
properties	O	A set of properties of GeoJSON.
bbox	O	Bounding box information for the moving feature.
time	O	Life span information for the moving feature.
crs	O	Coordinate reference system (CRS) information for the moving feature.
trs	O	Temporal reference system information for the moving feature.
temporalGeometry	O	A sequence of TemporalPrimitiveGeometry for the moving feature.
temporalProperties	O	A set of TemporalProperty of the moving feature.

Note	The properties id, type, geometry, properties, and bbox were inherited from GeoJSON.

Note	The properties time, crs, trs, temporalGeometry, and temporalProperties were inherited from OGC MF-JSON

Requirement 18	/req/movingfeatures/mf-mandatory
A	A moving feature object SHALL contain all the mandatory properties listed in Table 8.

8.4.2. Operation

Retrieve

The retrieve operation is defined in the Feature conformance class of OGC API — Features. No modifications are needed to support MovingFeature resources.

Issue a GET request on the {root}/collections/{collectionId}/items/{mFeatureId} path

The {mFeatureId} path parameter is the unique identifier for a single moving feature offered by the API. The list of valid values for {mFeatureId} is provided in the {root}/collections/{collectionId}/items GET response.

Support for GET on the {root}/collections/{collectionID}/items/{mFeatureId} path is required by OGC API — Features.

Requirement 19 /req/movingfeatures/mf-get

Requirement 19	/req/movingfeatures/mf-get
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Features `Feature` operation requirement `/req/core/f-op`.
B	For every moving feature in a moving feature collection (path `{root}/collections/{collectionId}`), the server SHALL support the HTTP GET operation at the path `{root}/collections/{collectionId}/items/{mFeatureId}`
C	The path parameter `collectionId` is each `id` property in the Collection GET operation response where the value of the `itemType` property is specified as MovingFeature. The path parameter `mFeatureId` is an `id` property of the moving feature.

An implementation of the OGC API — MF SHALL comply with the OGC API — Features Feature operation requirement /req/core/f-op.

For every moving feature in a moving feature collection (path {root}/collections/{collectionId}), the server SHALL support the HTTP GET operation at the path {root}/collections/{collectionId}/items/{mFeatureId}

The path parameter collectionId is each id property in the Collection GET operation response where the value of the itemType property is specified as MovingFeature. The path parameter mFeatureId is an id property of the moving feature.

Delete

The delete operation is defined in the DELETE conformance class of OGC API — Features.

Issue a DELETE request on {root}/collections/{collectionId}/items/{mFeatureId} path

Support for the HTTP DELETE method is required by OGC API — Features.

Requirement 20 /req/movingfeatures/mf-delete

Requirement 20	/req/movingfeatures/mf-delete
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `DELETE` operation requirement `req/create-replace-delete/delete/delete-op`.
B	For every moving feature in a moving feature collection (path `{root}/collections/{collectionId}`), the server SHALL support the HTTP DELETE operation at the path `{root}/collections/{collectionId}/items/{mFeatureId}`
C	The path parameter `collectionId` is each `id` property in the Collection GET operation response where the value of the `itemType` property is specified as MovingFeature. The path parameter `mFeatureId` is an `id` property of the moving feature.

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature DELETE operation requirement req/create-replace-delete/delete/delete-op.

For every moving feature in a moving feature collection (path {root}/collections/{collectionId}), the server SHALL support the HTTP DELETE operation at the path {root}/collections/{collectionId}/items/{mFeatureId}

8.4.3. Response

Retrieve

A successful response to the MovingFeature GET operation is a set of metadata that describes the moving feature identified by the {mFeatureId} parameter. This response does not include a set of temporal object information. The temporal object information may be accessed using TemporalGeometry and TemporalProperties operations.

Requirement 21 /req/movingfeatures/mf-get-success

Requirement 21	/req/movingfeatures/mf-get-success
A	A successful execution of the operation SHALL be reported as a response with an HTTP status code `200`.
B	The content of that response SHALL include the set of moving feature’s metadata that defined in the response schema.

A successful execution of the operation SHALL be reported as a response with an HTTP status code 200.

The content of that response SHALL include the set of moving feature’s metadata that defined in the response schema.

MovingFeature GET Response Schema (movingFeature.yaml):

type: object
required:
  - id
  - type
properties:
  type:
    type: string
    enum:
      - 'Feature'
  temporalGeometry:
    $ref: "MF-JSON/Prism/temporalGeometry.yaml"
  temporalProperties:
    $ref: "MF-JSON/Prism/temporalProperties.yaml"
  crs:
    $ref: "MF-JSON/Prism/crs.yaml"
  trs:
    $ref: "MF-JSON/Prism/trs.yaml"
  bbox:
    $ref: "MF-JSON/Prism/bbox.yaml"
  time:
    $ref: "MF-JSON/Prism/lifeSpan.yaml"
  geometry:
    $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/geometryGeoJSON.yaml'
  properties:
    type: object
    nullable: true
  id:
    description: 'An identifier for the feature'
    oneOf:
      - type: string
      - type: integer
  links:
    type: array
    items:
      $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml'

The time property of the MovingFeature response represents a particular period of moving feature existence.

The following JSON payload is an example of a response to an OGC API — Moving Features MovingFeature operation.

An Example of a MovingFeature JSON Payload:

{
  "id": "mf-1",
  "type": "Feature",
  "geometry":{
    "type": "LineString",
    "coordinates": [
      [139.757083, 35.627701, 0.5],
      [139.757399, 35.627701, 2.0],
      [139.757555, 35.627688, 4.0],
      [139.757651, 35.627596, 4.0],
      [139.757716, 35.627483, 4.0]
    ]
  },
  "properties":{
    "name": "car1",
    "state": "test1",
    "video": "http://www.opengis.net/spec/movingfeatures/json/1.0/prism/example/video.mpeg"
  },
  "bbox":[
    139.757083, 35.627483, 0.0,
    139.757716, 35.627701, 4.5
  ],
  "time":[
    "2011-07-14T22:01:01Z",
    "2011-07-15T01:11:22Z"
  ],
  "crs": {
    "type": "Name",
    "properties": "urn:ogc:def:crs:OGC:1.3:CRS84"
  },
  "trs": {
    "type": "Name",
    "properties": "urn:ogc:data:time:iso8601"
  }
}

Delete

A successful response to the Collection DELETE operation is an HTTP status code.

Requirement 22 /req/movingfeatures/mf-delete-success

Requirement 22	/req/movingfeatures/mf-delete-success
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Features `DELETE` response requirement `/req/create-replace-delete/delete/response`.
B	If no resource with the identifier exists in the collection, the server SHALL respond with a not-found exception (`404`).

An implementation of the OGC API — MF SHALL comply with the OGC API — Features DELETE response requirement /req/create-replace-delete/delete/response.

If no resource with the identifier exists in the collection, the server SHALL respond with a not-found exception (404).

8.4.4. Error situations

The requirements for handling unsuccessful requests are provided in the HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP Status Codes.

8.5. Resource TemporalGeometrySequence

8.5.1. Overview

The TemporalGeometrySequence resource supports retrieving and creating operations via GET and POST HTTP methods respectively.

A retrieve operation returns a sequence of TemporalPrimitiveGeometry object which is included in the MovingFeature that specified by {mFeatureId}. The sequence of TemporalPrimitiveGeometry object returned to the response can be limited using the query parameters limit, bbox, datetime, and leaf (or subTrajectory).
A create operation posts a new TemporalPrimitiveGeometry resource to the MovingFeature that specified by {mFeatureId}.

8.5.2. Query Parameters

Query parameters are used in URLs to define the resources which are returned on a GET request.

The query parameters bbox, datetime, and limit are inherited from OGC API — Common.

The subTrajectory query parameter is defined in the MovingFeatures clause.

Parameter leaf

The leaf query parameter is defined as follows:

Requirement 23 /req/movingfeatures/param-leaf-definition

Requirement 23	/req/movingfeatures/param-leaf-definition
A	The operation SHALL support a query parameter `leaf` with the following characteristics (using an OpenAPI Specification 3.0 fragment): `name: leaf in: query required: false schema: type: array uniqueItems: true minItems: 1 items: type: string format: date-time style: form explode: false`
B	The `leaf` parameter SHALL be a sequence of monotonic increasing instants with `date-time` strings.
C	The syntax of `date-time` is specified by RFC 3339, 5.6.

The operation SHALL support a query parameter leaf with the following characteristics (using an OpenAPI Specification 3.0 fragment):

name: leaf
in: query
required: false
schema:
  type: array
  uniqueItems: true
  minItems: 1
  items:
    type: string
    format: date-time
style: form
explode: false

The leaf parameter SHALL be a sequence of monotonic increasing instants with date-time strings.

The syntax of date-time is specified by RFC 3339, 5.6.

Requirement 24 /req/movingfeatures/param-leaf-response

Requirement 24	/req/movingfeatures/param-leaf-response
A	The `leaf` parameter SHALL match all resources in the moving feature that are associated with temporal information.
B	If the `leaf` parameter is provided by the client, the endpoint SHALL return only temporal geometry coordinate (or temporal property value) with the *pointAtTime* operation at each date-time included in the `leaf` parameter, using interpolated trajectory according to the `interpolation` property.
C	If the `leaf` parameter is provided by the client, the `interpolation` property in the response SHALL be 'Discrete'.
D	Apply `leaf` only to resources that intersect a `bbox` or (and) a `datetime` parameter, if the `leaf` parameter is provided with a `bbox` or (and) a `datetime` parameter.
D	The `leaf` parameter SHALL not be used with the `subTrajectory` parameter.

The leaf parameter SHALL match all resources in the moving feature that are associated with temporal information.

If the leaf parameter is provided by the client, the endpoint SHALL return only temporal geometry coordinate (or temporal property value) with the pointAtTime operation at each date-time included in the leaf parameter, using interpolated trajectory according to the interpolation property.

If the leaf parameter is provided by the client, the interpolation property in the response SHALL be 'Discrete'.

Apply leaf only to resources that intersect a bbox or (and) a datetime parameter, if the leaf parameter is provided with a bbox or (and) a datetime parameter.

The leaf parameter SHALL not be used with the subTrajectory parameter.

The leaf parameter is a sequence of monotonic increasing instants represented by date-time strings (ex. "2018-02-12T23:20:50Z") whose structure adheres to IETF RFC3339. The leaf parameter consists of a list of the date-time format strings, different from datetime parameter. The list does not allow the same element value. Example 1 shows valid expression examples of the leaf parameter.

Example 1. leaf parameter valid (and invalid) Examples

(O) "2018-02-12T23:20:50Z"

(O) "2018-02-12T23:20:50Z","2018-02-12T23:30:50Z"

(O) "2018-02-12T23:20:50Z","2018-02-12T23:30:50Z","2018-02-12T23:40:50Z"

(X) "2018-02-12T23:20:50Z","2018-02-12T23:20:50Z"

(X) "2018-02-12T23:20:50Z","2018-02-12T22:40:50Z"

If the leaf parameter is provided by the client, the endpoint returns only temporal geometry coordinate (or temporal property value) with the leaf query at each time included in the leaf parameter, similar to pointAtTime operation in the OGC Moving Feature Access Standard. The interpolation property in the response shall be "Discrete".

Figure 3. Example of a response result with leaf parameter

8.5.3. Operation

Retrieve

Issue a GET request on the {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence path

Requirement 25 /req/movingfeatures/tgsequence-get

Requirement 25	/req/movingfeatures/tgsequence-get
A	For every moving feature identified in the MovingFeatures GET response (path `{root}/collections/{collectionId}/items`), the server SHALL support the HTTP GET operation at the path `{root}/collections/{collectionId}/items/{mFeatureId}/tgsequence`
B	The path parameter `collectionId` is each `id` property in the Collection GET response where the value of the `itemType` property is specified as MovingFeature. The path parameter `mFeatureId` is each `id` property in the MovingFeatures GET response.

For every moving feature identified in the MovingFeatures GET response (path {root}/collections/{collectionId}/items), the server SHALL support the HTTP GET operation at the path {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence

The path parameter collectionId is each id property in the Collection GET response where the value of the itemType property is specified as MovingFeature. The path parameter mFeatureId is each id property in the MovingFeatures GET response.

Create

The create operation is defined in the CREATE conformance class of OGC API — Features. This operation targeted TemporalPrimitiveGeometry resource.

Issue a POST request on {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence path

Support for the HTTP POST method is specified as a requirement in OGC API — Features.

Requirement 26 /req/movingfeatures/tgsequence-post

Requirement 26	/req/movingfeatures/tgsequence-post
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `CREATE` operation requirement `/req/create-replace-delete/insert-post-op`.
B	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `CREATE` request body requirements `/req/create-replace-delete/insert-body` and `/req/create-replace-delete/insert-content-type`.
C	The content of the request body SHALL be based upon the *TemporalPrimitiveGeometry* object in OGC Moving Features JSON Encoding Standard schema.
D	The ending date-time instance (*t_end) in the temporal geometry object in MovingFeature, determined by `mFeatureId`, SHALL be earlier than the beginning date-time instance (t_new) in the temporal geometry object in the request body, i.e., t_end < t_new*.

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature CREATE operation requirement /req/create-replace-delete/insert-post-op.

The content of the request body SHALL be based upon the TemporalPrimitiveGeometry object in OGC Moving Features JSON Encoding Standard schema.

The ending date-time instance (t_end) in the temporal geometry object in MovingFeature, determined by mFeatureId, SHALL be earlier than the beginning date-time instance (t_new) in the temporal geometry object in the request body, i.e., t_end < t_new.

The following example adds a new feature (TemporalPrimitiveGeometry object in MF-JSON) to the feature created by the Creation a MovingFeature Example. The feature is represented as TemporalPrimitiveGeometry object in MF-JSON, which is an extension of the JSON. A pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server.

An Example of Creating a New TemporalPrimitiveGeometry Object:

   Client                                                                     Server
     |                                                                          |
     | POST /collections/mfc_1/items/mf_1/tgsequence  HTTP/1.1                  |
     | Content-Type: application/json                                           |
     |                                                                          |
     | {                                                                        |
     |    "id": "tg_1",                                                         |
     |    "type": "MovingPoint",                                                |
     |    "datetimes": [                                                        |
     |       "2011-07-14T22:01:06.000Z",                                        |
     |       "2011-07-14T22:01:07.000Z",                                        |
     |       "2011-07-14T22:01:08.000Z"                                         |
     |    ],                                                                    |
     |    "coordinates": [                                                      |
     |       [139.757716,35.627483,4.0],                                        |
     |       [139.757782,35.627483,4.0],                                        |
     |       [139.757843,35.627483,4.0]                                         |
     |    ],                                                                    |
     |    "interpolation": "Linear",                                            |
     |    "base": {                                                             |
     |       "type": "glTF",                                                    |
     |       "href": "http://.../example/car3dmodel.gltf"                       |
     |    },                                                                    |
     |    "orientations": [                                                     |
     |        {"scales": [1,1,1],"angles": [0,0,270]},                          |
     |        {"scales": [1,1,1],"angles": [0,0,270]},                          |
     |        {"scales": [1,1,1],"angles": [0,0,270]}                           |
     |    ]                                                                     |
     | }                                                                        |
     |------------------------------------------------------------------------->|
     |                                                                          |
     | HTTP/1.1 201 Created                                                     |
     | Location: /collections/mfc_1/items/mf_1/tgsequence/tg_1                  |
     |<-------------------------------------------------------------------------|

8.5.4. Response

Retrieve

A successful response to the TemporalGeometrySequence GET operation is a document that contains the set of temporal geometry of the moving feature identified by the {mFeatureId} parameter.

Requirement 27 /req/movingfeatures/tgsequence-get-success

Requirement 27	/req/movingfeatures/tgsequence-get-success
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `Features` response requirement `/req/core/fc-response`.
B	The response SHALL only includes temporal primitive geometry selected by request with `limit`, `bbox`, `datetime`, and `leaf` (or `subTrajectory`) parameters.
C	Each temporal primitive geometry in the response SHALL include the mandatory properties listed in Table 9.

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature Features response requirement /req/core/fc-response.

The response SHALL only includes temporal primitive geometry selected by request with limit, bbox, datetime, and leaf (or subTrajectory) parameters.

Each temporal primitive geometry in the response SHALL include the mandatory properties listed in Table 9.

TemporalGeometrySequence GET Response Schema (temporalGeometrySequence.yaml):

type: object
required:
  - type
  - geometrySequence
properties:
  type:
    type: string
    enum:
      - "TemporalGeometrySequence"
  geometrySequence:
    type: array
    items:
      $ref: 'MF-JSON/Prism/temporalPrimitiveGeometry.yaml'
  links:
    type: array
    items:
      $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml'
  timeStamp:
    type: string
    format: date-time
  numberMatched:
    type: integer
    minimum: 0
  numberReturned:
    type: integer
    minimum: 0

The following JSON payload is an example of a response to an OGC API — Moving Features TemporalGeometrySequence GET operation.

An Example of a TemporalGeometrySequence GET operation:

{
  "type": "TemporalGeometrySequence",
  "geometrySequence": [
    {
      "id": "tg-1",
      "type": "MovingPoint",
      "datetimes": [
        "2011-07-14T22:01:02Z",
        "2011-07-14T22:01:03Z",
        "2011-07-14T22:01:04Z"
      ],
      "coordinates": [
        [139.757399, 35.627701, 2.0],
        [139.757555, 35.627688, 4.0],
        [139.757651, 35.627596, 4.0]
      ],
      "interpolation": "Linear",
      "base": {
        "type": "glTF",
        "href": "https://www.opengis.net/spec/movingfeatures/json/1.0/prism/example/car3dmodel.gltf"
      },
      "orientations":[
        {
          "scales": [1,1,1],
          "angles": [0,355,0]
        },
        {
          "scales": [1,1,1],
          "angles": [0,0,330]
        },
        {
          "scales": [1,1,1],
          "angles": [0,0,300]
        }
      ],
      "crs": {
        "type": "Name",
        "properties": "urn:ogc:def:crs:OGC:1.3:CRS84"
      },
      "trs": {
        "type": "Name",
        "properties": "urn:ogc:data:time:iso8601"
      }
    }
  ],
  "links": [
    {
      "href": "https://data.example.org/collections/mfc-1/items/mf-1/tgsequence",
      "rel": "self",
      "type": "application/json"
    },
    {
      "href": "https://data.example.org/collections/mfc-1/items/mf-1/tgsequence&offset=10&limit=1",
      "rel": "next",
      "type": "application/json"
    }
  ],
  "timeStamp": "2021-09-01T12:00:00Z",
  "numberMatched": 100,
  "numberReturned": 1
}

Create

A successful response to the TemporalGeometrySequence POST operation is an HTTP status code.

Requirement 28	/req/movingfeatures/tgsequence-post-success
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `CREATE` response requirement `/req/create-replace-delete/insert-response` and `/req/create-replace-delete/insert-response-rid`.

8.5.5. Error situations

The requirements for handling unsuccessful requests are provided in the HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP Status Codes.

8.6. Resource TemporalPrimitiveGeometry

8.6.1. Overview

A TemporalPrimitiveGeometry resource represents the movement of a moving feature with various types of moving geometry, i.e., MovingPoint, MovingLineString, MovingPolygon, and MovingPointCloud. It can also represent the movement of a 3D object with its orientation.

The schema for the TemporalPrimitiveGeometry presented in this clause is the same as the TemporalPrimitiveGeometry object defined in MF-JSON. Table 9 defines the set of properties that may be used to describe a TemporalPrimitiveGeometry.

Table 9. Table of the properties related to the **TemporalPrimitiveGeometry**
Property	Requirement	Description
id	M	A unique identifier to the temporal primitive geometry.
*type*	M	A primitive geometry type of MF-JSON (i.e., one of 'MovingPoint', 'MovingLineString', 'MovingPolygon', or 'MovingPointCloud').
*datetimes*	M	A sequence of monotonically increasing instants.
*coordinates*	M	A sequence of leaf geometries of a temporal geometry, having the same number of elements as "datetimes".
*interpolation*	M	A predefined type of motion curve (i.e., one of 'Discrete', 'Step', 'Linear', 'Quadratic' or 'Cubic').
*base*	O	*type*: A type of 3D file format, such as 'STL', 'OBJ', 'PLY', and 'glTF'.
*base*	O	*href*: A URL to address a 3D model data which represents a base geometry of a 3D shape.
*orientations*	O	*scales*: An array value of numbers along the x, y, and z axis in order as three scale factors.
*orientations*	O	*angles*: An array value of numbers along the x, y, and z axis in order as Euler angles in degree.

Note	The detailed information and requirements for each property are described in the OGC Moving Feature JSON Encoding Standard.

Requirement 29	/req/movingfeatures/tpgeometry-mandatory
A	A TemporalPrimitiveGeometry object SHALL contain all the mandatory properties listed in Table 9.

8.6.2. Operation

Delete

The delete operation is defined in the DELETE conformance class of API — Features.

Issue a DELETE request on {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence/{tGeometryId} path

The {tGeometryId} parameter is the unique identifier for a TemporalPrimitiveGeometry object offered by the API. The list of valid values for {tGeometryId} is provided in the {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence GET response.

Support for the HTTP DELETE method is specified as a requirement in OGC API — Features.

Requirement 30 /req/movingfeatures/tpgeometry-delete

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature DELETE operation requirement /req/create-replace-delete/delete/delete-op.

For every temporal geometry in a moving feature (path {root}/collections/{collectionId}/items/{mFeatureId}), the server SHALL support the HTTP DELETE operation at the path {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence/{tGeometryId}

The path parameter collectionId is each id property in the Collection GET operation response where the value of the itemType property is specified as MovingFeature.
The path parameter mFeatureId is an id property of the moving feature. The path parameter tGeometryId is an id property of the temporal geometry.

8.6.3. Response

Delete

A successful response to the TemporalPrimitiveGeometry DELETE operation is an HTTP status code.

Requirement 31 /req/movingfeatures/tpgeometry-delete-success

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature DELETE response requirement /req/create-replace-delete/delete/response.

If no resource with the identifier exists in the collection, the server SHALL respond with a not-found exception (404).

8.6.4. Error situations

The requirements for handling unsuccessful requests are provided in the HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP Status Codes.

8.7. TemporalGeometry Query Resources

8.7.1. Overview

TemporalGeometry Query resources are spatiotemporal queries that support operations for accessing TemporalPrimitiveGeometry resources. The OGC API — MF Standard identifies an initial set of common query types to implement. These are described in this clause. This list may change as the Standard is used and experience is gained.

Query resources related to the TemporalPrimitiveGeometry resource can be exposed using the path templates:

{root}/collections/{collectionId}/items/{mFeatureId}/tgsequence/{tGeometryId}/{queryType}

Where:

{root} = Base URI for the API server
{collectionId} = An identifier for a specific Collection of data
{mFeatureId} = An identifier for a specific MovingFeature of a specific Collection of data
{tGeometryId} = An identifier for a specific TemporalPrimitiveGeometry of a specific MovingFeature of data
{quertyType} = An identifier for the query pattern performed by an implementation instance of the OGC API — MF.

Table 10 provides a mapping of the initial query types proposed for the OGC API — MF.

Table 10. Table of the query resources
Path Template	Query Type	Description
`{root}/collections/{collectionId}/items/ {mFeatureId}/tgsequence/{tGeometryId}/distance`	Distance	Return a graph of the time to distance function as a form of the TemporalProperty.
`{root}/collections/{collectionId}/items/ {mFeatureId}/tgsequence/{tGeometryId}/velocity`	Velocity	Return a graph of the time to velocity function as a form of the TemporalProperty.
`{root}/collections/{collectionId}/items/ {mFeatureId}/tgsequence/{tGeometryId}/acceleration`	Acceleration	Return a graph of the time to acceleration function as a form of the TemporalProperty.

8.7.2. Query parameters

Query parameters are used in URLs to define the resources which are returned on a GET request. The query parameters datetime is inherited from OGC API — Common.

8.7.3. Distance Query

The Distance query returns a time-to-distance curve of the TemporalPrimitiveGeometry object as a form of the TemporalProperty. Figure 4 shows an example of the time-to-distance curve.

Figure 4. Example of time-to-distance curve [OGC 16-120r3, OGC Moving Features Access]

The filter constraints are defined by the following query parameter:

Parameter datetime

The datetime parameter defines the specified date and time to return the distance value from the time-to-distance curve. If the datetime is provided, the datetime must be a date-time, not a half-bounded interval or bounded interval. When the datetime is not specified, an implementation instance (endpoint) of the API returns data from all available times of the specified TemporalPrimitiveGeometry resource.

8.7.4. Velocity Query

The Velocity query returns a time-to-velocity curve of the TemporalPrimitiveGeometry object as a form of the TemporalProperty.

The filter constraints are defined by the following query parameter:

Parameter datetime

The datetime parameter defines the specified date and time to return the velocity value from the time-to-velocity graph. If the datetime is provided, the datetime must be a date-time, not a half-bounded interval or bounded interval. When the datetime is not specified, an implementation instance (endpoint) of the API returns data from all available times of the specified TemporalPrimitiveGeometry resource.

8.7.5. Acceleration Query

The Acceleration query returns a time-to-acceleration curve of the TemporalPrimitiveGeometry object as a form of the TemporalProperty.

The filter constraints are defined by the following query parameter:

Parameter datetime

The datetime parameter defines the specified date and time to return the acceleration value from the time-to-acceleration curve. If the datetime is provided, the datetime must be a date-time, not a half-bounded interval or bounded interval. When the datetime is not specified, an implementation instance (endpoint) of the API returns data from all available times of the specified TemporalPrimitiveGeometry resource.

8.7.6. Operation Requirements

Requirement 32 /req/movingfeatures/tpgeometry-query

For every TemporalPrimitiveGeometry identified in the TemporalGeometrySequence GET response (path {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence), the server SHALL support the HTTP GET operation at the path {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence/{tGeometryId}/{queryType}

The path parameter collectionId is each id property in the Collection GET operation response where the value of the itemType property is specified as MovingFeature.
The path parameter mFeatureId is an id property of the moving feature.
The path parameter tGeometryId is an id property of the temporal geometry.

The path parameter queryType SHALL be one of the predefined query type (distance, velocity, and acceleration)

Permission 1 /per/movingfeatures/tpgeometry-query

A distance query GET operation MAY include a datetime query parameter.

A velocity query GET operation MAY include a datetime query parameter.

An acceleration query GET operation MAY include a datetime query parameter.

If the datetime parameter is provided, the datetime SHALL be a date-time, not a half-bounded interval or bounded interval.

8.7.7. Response Requirements

Requirement 33 /req/movingfeatures/tpgeometry-query-success

A successful execution of the distance, velocity, and acceleration query GET operation SHALL be reported as a response with an HTTP status code 200.

The content of that response SHALL include the parametric value that is defined in the response schema.

The type property SHALL be "TReal"

8.8. Resource TemporalProperties

8.8.1. Overview

A TemporalProperties object consists of the set of TemporalProperty which is included in the MovingFeature that is specified by {mFeatureId}. The TemporalProperties resource supports the retrieve and create operations via the HTTP GET and POST methods respectively.

A retrieve operation returns a list of the available abbreviated copy of TemporalProperty object in the specified moving feature. The TemporalProperties resource returned to the response can be limited using the query parameters limit, datetime, and subTemporalValue.
A create operation posts a new TemporalProperty object to the MovingFeature that is specified by {mFeatureId}.

8.8.2. Query Parameters

Query parameters are used in URLs to define the resources which are returned on a GET request.

The query parameters datetime and limit are inherited from OGC API — Common.

Parameter subTemporalValue

The subTemporalValue query parameter is defined as follows:

Requirement 34 /req/movingfeatures/param-subtemporalvalue-definition

The operation SHALL support a query parameter subTemporalValue with the following characteristics (using an OpenAPI Specification 3.0 fragment):

name: subTemporalValue
in: query
required: false
schema:
  type: boolean
style: form
explode: false

The subTemporalValue parameter SHALL be used with datetime parameter.

If the subTemporalValue parameter is "true", the datetime parameter SHALL be a bounded interval, not half-bounded intervals or a date-time.

Requirement 35 /req/movingfeatures/param-subtemporalvalue-response

The endpoint SHALL return only a subsequence of the temporal primitive values derived from temporal property for specified a time interval (new start time and new end time) included in the datetime parameter, using interpolated temporal property values according to the interpolation property in TemporalProperty, if the subTemporalValue parameter is "ture".

If the subTemporalValue parameter is "true", the datetime parameter SHALL match all temporal property objects in the moving feature.

If the subTemporalValue parameter is "true", the interpolation property in the response SHALL be the same as the temporal property’s interpolation property value.

The subTemporalValue parameter SHALL not be used with the leaf parameter.

The subTemporalValue query parameter is used to select a subset of TemporalProperty for the specified time interval. Each TemporalProperty in the TemporalProperties has a sequence of TemporalPrimitiveValue. The subTemporalValue parameter behaves functionally the same as the subTrajectory parameter. The difference is that subTrajectory is associated with temporal geometry, while subTemporalValue is associated with temporal properties.

8.8.3. Operation

Retrieve

Issue a GET request on the {root}/collections/{collectionId}/items/{mFeatureId}/tproperties path

Requirement 36 /req/movingfeatures/tproperties-get

The path parameter collectionId is each id property in the Collection GET response where the value of the itemType property is specified as MovingFeature.
The path parameter mFeatureId is each id property in the MovingFeatures GET response.

Create

The create operation is defined in the CREATE conformance class in the OGC API — Features. This operation targeted TemporalProperty resource.

Issue a POST request on {root}/collections/{collectionId}/items/{mFeatureId}/tproperties path

Support for the HTTP POST method is specified as a requirement in OGC API — Features.

Requirement 37 /req/movingfeatures/tproperties-post

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature CREATE operation requirement /req/create-replace-delete/insert-post-op.

The content of the request body SHALL be based upon a TemporalProperty defined in this API or a ParametricValues object defined in OGC Moving Features JSON Encoding Standard.

TemporalProperties Request Body Schema (temporalProperty.yaml):

type: object
required:
  - name
  - type
properties:
  name:
    type: string
  type:
    type: string
    enum:
      - 'TBoolean'
      - 'TText'
      - 'TInteger'
      - 'TReal'
      - 'TImage'
  form:
    oneOf:
      - type: string
        format: uri
      - type: string
        minLength: 3
        maxLength: 3
  valueSequence:
    type: array
    uniqueItems: true
    items:
      $ref: 'temporalPrimitiveValue.yaml'
  description:
    type: string
  links:
    type: array
    items:
      $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml'

The following example adds a new feature (TemporalProperty Object and ParametricValues Object in MF-JSON) to the feature created by the Creation a MovingFeature Example. The feature is represented as a JSON payload. A pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server.

An Example of Creating a New TemporalProperty Object:

   Client                                                                     Server
     |                                                                          |
     | POST /collections/mfc_1/items/mf_1/tproperties   HTTP/1.1                |
     | Content-Type: application/json                                           |
     |                                                                          |
     | {                                                                        |
     |    "name": "speed",                                                      |
     |    "type": "TReal",                                                      |
     |    "form": "KMH"                                                         |
     | }                                                                        |
     |------------------------------------------------------------------------->|
     |                                                                          |
     | HTTP/1.1 201 Created                                                     |
     | Location: /collections/mfc_1/items/mf_1/tproperties/speed                |
     |<-------------------------------------------------------------------------|

An Example of Creating a New TemporalProperty Object with ParametricValues as a MF-JSON encoding:

   Client                                                                     Server
     |                                                                          |
     | POST /collections/mfc_1/items/mf_1/tproperties   HTTP/1.1                |
     | Content-Type: application/json                                           |
     |                                                                          |
     | {                                                                        |
     |    "datetimes": [                                                        |
     |       "2011-07-14T22:01:06.000Z",                                        |
     |       "2011-07-14T22:01:07.000Z",                                        |
     |       "2011-07-14T22:01:08.000Z",                                        |
     |    ],                                                                    |
     |    "speed": {                                                            |
     |       "type": "Measure",                                                  |
     |       "form": "KMH",                                                     |
     |       "values": [65.0, 70.0, 80.0],                                      |
     |       "interpolation": "Linear"                                          |
     |    }                                                                     |
     | }                                                                        |
     |------------------------------------------------------------------------->|
     |                                                                          |
     | HTTP/1.1 201 Created                                                     |
     | Location: /collections/mfc_1/items/mf_1/tproperties/speed                |
     |<-------------------------------------------------------------------------|

8.8.4. Response

Retrieve

A successful response to the TemporalProperties GET operation is a document that contains the set of metadata (and static data) of TemporalProperty in the moving feature identified by the {mFeatureId} parameter. The response result does not include dynamic (and temporal information).

If the value of the subTemporalValue query parameter is provided, the temporal value of the corresponding temporalProperties property of the moving feature is calculated using the subTemporalValue parameter value and included in the result.

Requirement 38 /req/movingfeatures/tproperties-get-success

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature Features response requirement /req/core/fc-response.

The response SHALL only include moving features selected by the request with limit, datetime, and subTemporalValue parameters.

Each temporal property object in the response SHALL include the mandatory properties listed in Table 11.

TemporalProperties GET Response Schema (TemporalProperties.yaml):

type: object
required:
  - temporalProperties
properties:
  temporalProperties:
    oneOf:
      - $ref: "MF-JSON/Prism/temporalProperties.yaml"
      - type: array
        items:
          $ref: "temporalProperty.yaml"
  links:
    type: array
    items:
      $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml'
  timeStamp:
    type: string
    format: date-time
  numberMatched:
    type: integer
    minimum: 0
  numberReturned:
    type: integer
    minimum: 0

The following JSON payload is an example of a response to an OGC API — Moving Features TemporalProperties GET operation.

An Example of a TemporalProperties GET Operation:

{
  "temporalProperties": [
    {
      "name": "length",
      "type": "TReal",
      "form": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Length"
    },
    {
      "name": "speed",
      "type": "TReal",
      "form": "KHM"
    }
  ],
  "links": [
    {
      "href": "https://data.example.org/collections/mfc-1/items/mf-1/tproperties",
      "rel": "self",
      "type": "application/json"
    },
    {
      "href": "https://data.example.org/collections/mfc-1/items/mf-1/tproperties&offset=2&limit=2",
      "rel": "next",
      "type": "application/json"
    }
  ],
  "timeStamp": "2021-09-01T12:00:00Z",
  "numberMatched": 10,
  "numberReturned": 2
}

The following JSON payload is an example of a response to an OGC API — Moving Features TemporalProperties GET operation with query parameter subTemporalValue.

An Example of a TemporalProperties GET Operation with subTemporalValue:

{
  "temporalProperties": [
    {
      "datetimes": ["2011-07-14T22:01:06.000Z", "2011-07-14T22:01:07.000Z", "2011-07-14T22:01:08.000Z"],
      "length": {
        "type": "Measure",
        "form": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Length",
        "values": [1.0, 2.4, 1.0],
        "interpolation": "Linear"
      },
      "speed" : {
        "type" : "Measure",
        "form" : "KMH",
        "values" : [65.0, 70.0, 80.0],
        "interpolation": "Linear"
      }
    }
  ],
  "links": [
    {
      "href": "https://data.example.org/collections/mfc-1/items/mf-1/tproperties",
      "rel": "self",
      "type": "application/json"
    },
    {
      "href": "https://data.example.org/collections/mfc-1/items/mf-1/tproperties&offset=2&limit=2",
      "rel": "next",
      "type": "application/json"
    }
  ],
  "timeStamp": "2021-09-01T12:00:00Z",
  "numberMatched": 10,
  "numberReturned": 2
}

Create

A successful response to the TemporalProperties POST operation is an HTTP status code.

Requirement 39	/req/movingfeatures/tproperties-post-success
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `CREATE` response requirement `/req/create-replace-delete/insert-response` and `/req/create-replace-delete/insert-response-rid`.

8.8.5. Error situations

The requirements for handling unsuccessful requests are provided in the HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP Status Codes.

8.9. Resource TemporalProperty

8.9.1. Overview

The TemporalProperty resource supports the retrieve and create operations via the HTTP GET and POST methods respectively.

A retrieve operation returns a TemporalProperty resource which is included in the TemporalProperties that specified by {tPropertyName}. The TemporalProperty resource returned to the response can be limited using the parameters datetime, leaf and subTemporalValue.
A create operation posts a new temporal primitive value object to the TemporalProperties that specified by {tPropertyName}.

A temporal property object is a collection of dynamic non-spatial attributes and their temporal values with time. An abbreviated copy of this information is returned for each TemporalProperty in the {root}/collections/{collectionId}/items/{mFeatureId}/tproperties response.

The schema for the temporal property object presented in this clause is an extension of the ParametricValues Object defined in MF-JSON. Table 11 defines the set of property that may be used to describe a temporal property.

Table 11. Table of the properties related to the temporal property
Property	Requirement	Description
*name*	M	An identifier for the resource assigned by an external entity.
*type*	M	A predefined temporal property type (i.e., one of 'TBoolean', 'TText', 'TInteger', 'TReal', and 'TImage').
*valueSequence*	M	A sequence of temporal primitive value
*form*	O	A unit of measure.
*description*	O	A short description.

Table 12. Table of the properties related to the temporal primitive value
Property	Requirement	Description
*datetimes*	M	A sequence of monotonic increasing instants.
*values*	M	A sequence of dynamic values having the same number of elements as "datetimes".
*interpolation*	M	A predefined type for a dynamic value (i.e., one of 'Discrete', 'Step', 'Linear', or 'Regression').

Note	The detailed information and requirements for each property are described in the OGC Moving Feature JSON Encoding Standard.

Requirement 40	/req/movingfeatures/tproperty-mandatory
A	A temporal property object SHALL contain all the mandatory properties listed in Table 11 and Table 12.

8.9.2. Query Parameters

Query parameters are used in URLs to define the resources which are returned on a GET request.

The query parameter datetime is inherited from OGC API — Common.

The leaf query parameter is defined in the TemporalGeometrySequence clause.

The subTemporalValue query parameter is defined in the TemporalProperties clause.

8.9.3. Operation

Retrieve

Issue a GET request on the {root}/collections/{collectionId}/items/{mFeatureId}/tproperties/{tPropertyName} path

The {tPropertyName} parameter is the unique identifier for a single temporal property value offered by an implementation instance (endpoint) of the OGC API — MF. The list of valid values for {tPropertyName} is provided in the {root}/collections/{collectionId}/items/{mFeatureId}/tproperties GET response.

Requirement 41 /req/movingfeatures/tproperty-get

For every temporal property in a moving feature (path {root}/collections/{collectionId}/items/{mFeatureId}/tproperties), the server SHALL support the HTTP GET operation at the path {root}/collections/{collectionId}/items/{mFeatureId}/tproperties/{tPropertyName}

The path parameter collectionId is each id property in the Collection GET response where the value of the itemType property is specified as MovingFeature.
The path parameter mFeatureId is each id property in the MovingFeatures GET response.
tPropertyName is a local identifier of the temporal property.

Create

The create operation is defined in the CREATE conformance class in the OGC API — Features. This operation targeted the new temporal primitive value object defined in Table 12.

Issue a POST request on {root}/collections/{collectionId}/items/{mFeatureId}/tproperties/{tPropertyName} path

Support for the HTTP POST method is specified as a requirement in OGC API — Features.

Requirement 42 /req/movingfeatures/tproperty-post

An implementation of the OGC API — MF SHALL comply with the OGC API — Feature CREATE operation requirement /req/create-replace-delete/insert-post-op.

The content of the request body SHALL be based upon the TemporalPrimitiveValue schema.

The ending date-time instance (t_end) in the temporal value object in TemporalProperty, determined by tPropertyName, SHALL be earlier than the beginning date-time instance (t_new) in the temporal value object in the request body, i.e., t_end < t_new.

TemporalProperty Request Body Schema (TemporalPrimitiveValue.yaml):

type: object
required:
  - datetimes
  - values
  - interpolation
properties:
  datetimes:
    type: array
    uniqueItems: true
    minItems: 2
    items:
      type: string
      format: date-time
  values:
    oneOf:
      - type: number
      - type: string
      - type: boolean
  interpolation:
    type: string
    enum:
      - 'Discrete'
      - 'Step'
      - 'Linear'
      - 'Regression'

The following example adds a new feature (TemporalPrimitiveValue object) to the feature created by Creating a New TemporalPrimitiveValue Object Example. The feature is represented as a JSON payload. A pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server.

An Example of Creating a New TemporalPrimitiveValue Object:

   Client                                                                     Server
     |                                                                          |
     | POST /collections/mfc_1/items/mf_1/tproperties/speed   HTTP/1.1          |
     | Content-Type: application/json                                           |
     |                                                                          |
     | {                                                                        |
     |    "datetimes": [                                                        |
     |       "2011-07-14T22:01:09.000Z",                                        |
     |       "2011-07-14T22:01:010.000Z",                                       |
     |    ],                                                                    |
     |    "values": [                                                           |
     |       90.0,                                                              |
     |       95.0,                                                              |
     |    ],                                                                    |
     |    "interpolation": "Linear"                                             |
     | }                                                                        |
     |------------------------------------------------------------------------->|
     |                                                                          |
     | HTTP/1.1 201 Created                                                     |
     | Location: /collections/mfc_1/items/mf_1/tproperties/speed                |
     |<-------------------------------------------------------------------------|

8.9.4. Response

Retrieve

A successful response to the TemporalProperty GET operation is a temporal property identified by the {tPropertyName} parameter.

Requirement 43 /req/movingfeatures/tproperty-get-success

A successful execution of the operation SHALL be reported as a response with an HTTP status code 200.

The response SHALL only include temporal properties selected by the request with leaf and subTemporalValue parameters.

The content of that response SHALL include the parametric value that is defined in the response schema.

The following JSON payload is an example of a response to an OGC API — Moving Features TemporalProperty GET operation.

An Example of TemporalProperty GET Operation:

{
  "temporalProperties": [
    {
      "datetimes":[
        "2011-07-14T22:01:02Z",
        "2011-07-14T22:01:03Z",
        "2011-07-14T22:01:04Z"
      ],
      "values":[
        65.0,
        70.0,
        80.0
      ],
      "interpolation": "Linear"
    },
    {
      "datetimes":[
        "2011-07-15T08:00:00Z",
        "2011-07-15T08:00:01Z",
        "2011-07-15T08:00:02Z"
      ],
      "values":[
        0.0,
        20.0,
        50.0
      ],
      "interpolation": "Linear"
    }
  ],
  "links": [
    {
      "href": "https://data.example.org/collections/mfc-1/items/mf-1/tproperties/speed",
      "rel": "self",
      "type": "application/json"
    }
  ]
}

Create

A successful response to the TemporalProperty POST operation is an HTTP status code.

Requirement 44	/req/movingfeatures/tproperty-post-success
A	An implementation of the OGC API — MF SHALL comply with the OGC API — Feature `CREATE` response requirement `/req/create-replace-delete/insert-response` and `/req/create-replace-delete/insert-response-rid`.

8.9.5. Error situations

The requirements for handling unsuccessful requests are provided in the HTTP Response. General guidance on HTTP status codes and how they should be handled is provided in HTTP Status Codes.

9. Common Requirements

9.1. Parameters

The query parameters bbox, datetime, and limit are inherited from OGC API — Common. All requirements and recommendations in API — Common regarding these parameters also apply to OGC API — MF. No modifications are required.

9.1.1. Parameter limit

Requirement 45 /req/common/param-limit

An implementation instance of the OGC API — MF SHALL support the Limit parameter for the operation.

Requests which include the Limit parameter SHALL comply with OGC API — Common requirement /req/collections/rc-limit-definition.

Responses to Limit requests SHALL comply with OGC API — Common requirements /req/collections/rc-limit-response

9.1.2. Parameter bbox

Requirement 46 /req/common/param-bbox

An implementation instance of the OGC API — MF SHALL support the Bounding Box (bbox) parameter for the operation.

Requests which include the Bounding Box parameter SHALL comply with OGC API — Common requirement /req/collections/rc-bbox-definition.

Responses to Bounding Box requests SHALL comply with OGC API — Common requirement /req/collections/rc-bbox-response.

9.1.3. Parameter datetime

Requirement 47 /req/common/param-datetime

An implementation instance of the OGC API — MF SHALL support the DateTime (datetime) parameter for the operation.

Requests which include the DateTime parameter SHALL comply with OGC API — Common requirement /req/collections/rc-time-definition.

Responses to DateTime requests SHALL comply with OGC API — Common requirement /req/collections/rc-time-response.

9.2. HTTP Response

Each HTTP request shall result in a response that meets the following requirement.

Requirement 48 /req/common/http-response

An HTTP operation SHALL return a response which includes a status code and an optional description element.

If the status code is not equal to 200, then the description element SHALL be populated.

The YAML schema for these results is provided in HTTP Response Schema.

An Example of the HTTP Response Schema:

title: Exception Schema
description: JSON schema for exceptions based on RFC 7807
type: object
required:
  - type
properties:
  type:
    type: string
  title:
    type: string
  status:
    type: integer
  detail:
    type: string
  instance:
    type: string

9.3. HTTP Status Codes

Table 13 lists the main HTTP status codes that clients should be prepared to receive. This includes support for specific security schemes or URI redirection. In addition, other error situations may occur in the transport layer outside of the server.

Table 13. Typical HTTP status codes
Status code	Description
`200`	A successful request.
`201`	The server has been fulfilled the operation and a new resource has been created.
`202`	A successful request, but the response is still being generated. The response will include a `Retry-After` header field giving a recommendation in seconds for the client to retry.
`204`	A successful request, but the resource has no data resulting from the request. No additional content or message body is provided.
`304`	An entity tag was provided in the request and the resource has not been changed since the previous request.
`308`	The server cannot process the data through a synchronous request. The response includes a `Location` header field which contains the URI of the location the result will be available at once the query is complete Asynchronous queries.
`400`	The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value.
`401`	The request requires user authentication. The response includes a `WWW-Authenticate` header field containing a challenge applicable to the requested resource.
`403`	The server understood the request, but is refusing to fulfill it. While status code `401` indicates missing or bad authentication, status code `403` indicates that authentication is not the issue, but the client is not authorized to perform the requested operation on the resource.
`404`	The requested resource does not exist on the server. For example, a path parameter had an incorrect value.
`405`	The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests.
`406`	Content negotiation failed. For example, the `Accept` header submitted in the request did not support any of the media types supported by the server for the requested resource.
`413`	Request entity too large. For example the query would involve returning more data than the server is capable of processing, the implementation should return a message explaining the query limits imposed by the server implementation.
`500`	An internal error occurred in the server.

Annex A: Conformance Class Abstract Test Suite (Normative)

A.1. Introduction

The Abstract Test Suite (ATS) is a compendium of test assertions applicable to implementations of the OGC API — MF. An ATS provides a basis for developing an Executable Test Suite to verify that the implementation under test conforms to all the relevant functional specifications.

The abstract test cases (assertions) are organized into test groups that correspond to distinct conformance test classes defined in the OGC API — MF Standard.

OGC APIs are not Web Services in the traditional sense. Rather, they define the behavior and content of a set of Resources exposed through a Web Application Programming Interface (Web API). Therefore, an API may expose resources in addition to those defined by the standard. A test engine shall traverse the API, identify and validate test points, and ignore resource paths which are not to be tested.

The Conformance Classes addressed by this Abstract Test Suite are the:

MovingFeature Collection Catalog Conformance Class
MovingFeature Conformance Class

A.2. Conformance Class MovingFeature Collection Catalog

Conformance Class

http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/conf/mf-collection

Target type

Web API

Requirements Class

http://www.opengis.net/spec/ogcapi-movingfeatures-1/1.0/req/mf-collection

Dependency

http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/html

Dependency

http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/json

Dependency

http://www.opengis.net/spec/ogcapi-common-2/1.0/conf/collections

Dependency

http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson

Dependency

http://www.opengis.net/spec/ogcapi-features-4/1.0/conf/create-replace-delete

A.2.1. MovingFeature Collections

HTTP GET Operation

Abstract Test 1

/conf/mf-collection/collections-get

Requirement

/req/mf-collection/collections-get
/req/mf-collection/collections-get-success

Test purpose

Validate that the MovingFeature Collections can be retrieved from the expected location.

Test method

1. Issue an HTTP GET request to the URL {root}/collections
2. Validate that a document was returned with a status code 200
3. Validate the contents of the returned document using test /conf/mf-collection/collections-get-success

Abstract Test 2

/conf/mf-collection/collections-get-success

Requirement

/req/mf-collection/collections-get-success

Test purpose

Validate that the MovingFeature Collections complies with the required structure and contents.

Test method

1. Validate that all response documents comply with OGC API — Common /conf/collections/rc-md-success
2. Validate the Collections resource for all supported media types using the resources and tests identified in Table 14
3. Verify that the response document contains a itemType property and its value is 'movingfeature'

The Collections content may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the against that schema. All supported formats should be exercised.

Table 14. Schema and Tests for MovingFeature Collections content
Format	Schema Document	Test ID
HTML	collections.yaml	/conf/html/content
JSON	collections.yaml	/conf/json/content

HTTP POST Operation

Abstract Test 3

/conf/mf-collection/collections-post

Requirement

/req/mf-collection/collections-post
/req/mf-collection/collections-post-success

Test purpose

Validate that the MovingFeature Collections can be created at the expected location.

Test method

1. Validate that the server complies with OGC API — Features POST operation requirements
2. Validate that a body of a POST request using for all supported media types using the resources and tests identified in Table 15
3. Validate that the request body complies OGC API — Features POST request body requirements
4. Issue an HTTP POST request to the URL {root}/collections
5. Validate the contents of the response using test /conf/mf-collection/collections-post-success

Table 15. Schema and Tests for Request Body of `{root}/collections` POST
Format	Schema Document	Test ID
HTML	collection_requestbody.yaml	/conf/html/content
JSON	collection_requestbody.yaml	/conf/json/content

Abstract Test 4

/conf/mf-collection/collections-post-success

Requirement

/req/mf-collection/collections-post-success

Test purpose

Validate that the response of {root}/collections POST request complies with the required structure and contents.

Test method

1. Validate that a document was returned with a status code 201 or 202
2. Validate that all response documents comply with OGC API — Features POST response requirements

A.2.2. MovingFeature Collection

HTTP GET Operation

Abstract Test 5

/conf/mf-collection/collection-get

Requirement

/req/mf-collection/collection-get
/req/mf-collection/collection-get-success

Test purpose

Validate that the MovingFeature Collection can be retrieved from the expected location.

Test method

For every Collection described in the Collections content, issue an HTTP GET request to the URL {root}/collections/{collectionId} where {collectionId} is the id property for the collection

1. Validate that a Collection was returned with a status code 200
2. Validate the contents of the returned document using test /conf/mf-collection/collection-get-success

Abstract Test 6

/conf/mf-collection/collection-get-success

Requirement

/req/mf-collection/collection-get-success /req/mf-collection/mandatory-collection

Test purpose

Validate that the MovingFeature Collection complies with the required structure and contents.

Test method

1. Validate that all response documents comply with OGC API — Common /conf/collections/src-md-success
2. Validate the Collection resource for all supported media types using the resources and tests identified in Table 16 and Table 6

Table 16. Schema and Tests for MovingFeature Collection content
Format	Schema Document	Test ID
HTML	collection.yaml	/conf/html/content
JSON	collection.yaml	/conf/json/content

HTTP PUT Operation

Abstract Test 7

/conf/mf-collection/collection-put

Requirement

/req/mf-collection/collection-put
/req/mf-collection/collection-put-success

Test purpose

Validate that the MovingFeature Collection can be replaced at the expected location.

Test method

1. Validate that the server complies with OGC API — Features PUT operation requirements
2. Validate that a body of a PUT request using for all supported media types using the resources and tests identified in Table 15
3. Validate that the request body complies OGC API — Features PUT request body requirements
4. Issue an HTTP PUT request to the URL {root}/collections/{collectionId}
5. Validate the contents of the response using test /conf/mf-collection/collections-put-success

Abstract Test 8

/conf/mf-collection/collections-put-success

Requirement

/req/mf-collection/collection-put-success

Test purpose

Validate that the response of {root}/collections/{collectionId} PUT request complies with the required structure and contents.

Test method

1. Validate that a document was returned with a status code 200, 202, or 204
2. Validate that all response documents comply with OGC API — Features PUT response requirements

HTTP DELETE Operation

Abstract Test 9

/conf/mf-collection/collection-delete

Requirement

/req/mf-collection/collection-delete
/req/mf-collection/collection-delete-success

Test purpose

Validate that the MovingFeature Collection can be deleted at the expected location.

Test method

1. Validate that the server complies with OGC API — Features DELETE operation requirements
2. Issue an HTTP DELETE request to the URL {root}/collections/{collectionId}
3. Validate the contents of the response using test /conf/mf-collection/collections-put-success

Abstract Test 10

/conf/mf-collection/collections-delete-success

Requirement

/req/mf-collection/collection-delete-success

Test purpose

Validate that the response of {root}/collections/{collectionId} DELETE request complies with the required structure and contents.

Test method

1. Validate that a document was returned with a status code 200, 202, or 204
2. Validate that all response documents comply with OGC API — Features DELETE response requirements

A.3. Conformance Class MovingFeatures

Conformance Class

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

Target type

Web API

Requirements Class

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

Dependency

http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/html

Dependency

http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/json

Dependency

http://www.opengis.net/spec/ogcapi-common-2/1.0/conf/collections

Dependency

http://www.opengis.net/spec/ogcapi-common-2/1.0/conf/simple-query

Dependency

http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core

Dependency

http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson

Dependency

http://www.opengis.net/spec/ogcapi-features-4/1.0/conf/create-replace-delete

A.3.1. MovingFeatures

HTTP GET Operation

Abstract Test 11

/conf/movingfeatures/features-get

Requirement

/req/movingfeatures/features-get
/ref/movingfeatures/features-get-success

Test purpose

Validate that MovingFeatures can be identified and extracted from a MovingFeature Collection using query parameters.

Test method

For every MovingFeature Collection identified in MovingFeature Collections, issue an HTTP GET request to the URL {root}/collections/{collectionId}/items where {collectionId} is the id property for a MovingFeature Collection described in the MovingFeature Collections content

1. Validate that a document was returned with a status code 200
2. Validate the contents of the returned document using test /conf/movingfeatures/features-get-success

Repeat these tests using the following parameter tests that defined in the OGC API — Common:
- Bounding Box: Bounding Box Tests
- Limit: Limit Tests
- Date-Time: Date-Time Tests

Execute requests with combinations of the "bbox" and "datetime" query parameters and verify that only features are returned that match both selection criteria.

Abstract Test 12

/conf/movingfeatures/features-get-success

Requirement

/ref/movingfeatures/features-get-success

Test purpose

Validate that the MovingFeatures complies with the required structure and contents.

Test method

1. Validate that all response documents comply with OGC API — Features /conf/core/fc-response
2. Validate the Collections resource for all supported media types using the resources and tests identified in Table 17

The MovingFeatures content may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the against that schema. All supported formats should be exercised.

Table 17. Schema and Tests for **MovingFeatures** content
Format	Schema Document	Test ID
HTML	movingFeatureCollection.yaml	/conf/html/content
GeoJSON	movingFeatureCollection.yaml	/conf/geojson/content

HTTP POST Operation

Abstract Test 13

/conf/movingfeatures/features-post

Requirement

/req/movingfeatures/mf-mandatory
/req/movingfeatures/features-post
/req/movingfeatures/features-post-success

Test purpose

Validate that the MovingFeature can be created at the expected location.

Test method

1. Validate that the server complies with OGC API — Features POST operation requirements
2. Validate that a body of a POST request using for all supported media types using the resources and tests identified in Table 18 and Table 8
3. Validate that the request body complies OGC API — Features POST request body requirements
4. Issue an HTTP POST request to the URL {root}/collections/{collectionId}/items
5. Validate the contents of the response using test /conf/movingfeatures/features-post-success

Table 18. Schema and Tests for Request Body of `{root}/collections/{collectionId}/items` POST
Format	Schema Document	Test ID
JSON	MF-JSON_Prism.schema.json	/conf/json/content

Abstract Test 14

/conf/movingfeatures/features-post-success

Requirement

/req/movingfeatures/features-post-success

Test purpose

Validate that the response of {root}/collections/{collectionId}/items POST request complies with the required structure and contents.

Test method

1. Validate that a document was returned with a status code 201 or 202
2. Validate that all response documents comply with OGC API — Features POST response requirements

A.3.2. MovingFeature

HTTP GET Operation

Abstract Test 15

/conf/movingfeatures/mf-get

Requirement

/req/movingfeatures/mf-get
/ref/movingfeatures/mf-get-success

Test purpose

Validate that the MovingFeature can be retrieved from the expected location.

Test method

For every MovingFeature identified in MovingFeature Collection, issue an HTTP GET request to the URL {root}/collections/{collectionId}/items/{mFeaturesId} where {collectionId} is the id property for a MovingFeature Collection described in the MovingFeature Collections content and {mFeatureId} is the id property for the MovingFeature

1. Validate that a document was returned with a status code 200
2. Validate the contents of the returned document using test /conf/movingfeatures/features-get-success

Abstract Test 16

/conf/movingfeatures/mf-get-success

Requirement

/ref/movingfeatures/mf-get-success

Test purpose

Validate that the MovingFeature complies with the required structure and contents.

Test method

1. Validate that all response documents comply with OGC API — Features /conf/core/f-success
2. Validate the Collections resource for all supported media types using the resources and tests identified in Table 19

The MovingFeature content may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the against that schema. All supported formats should be exercised.

Table 19. Schema and Tests for MovingFeature content
Format	Schema Document	Test ID
HTML	movingFeature.yaml	/conf/html/content
GeoJSON	movingFeature.yaml	/conf/geojson/content

HTTP DELETE Operation

Abstract Test 17

/conf/movingfeatures/mf-delete

Requirement

/req/movingfeatures/mf-delete
/req/movingfeatures/mf-delete-success

Test purpose

Validate that the MovingFeature can be deleted at the expected location.

Test method

1. Validate that the server complies with OGC API — Features DELETE operation requirements
2. Issue an HTTP DELETE request to the URL {root}/collections/{collectionId}/items/{mFeatureId}
3. Validate the contents of the response using test /conf/mf-collection/collections-put-success

Abstract Test 18

/conf/movingfeatures/mf-delete-success

Requirement

/req/movingfeatures/mf-delete-success

Test purpose

Validate that the response of {root}/collections/{collectionId}/items/{mFeatureId} DELETE request complies with the required structure and contents.

Test method

1. Validate that a document was returned with a status code 200, 202, or 204
2. Validate that all response documents comply with OGC API — Features DELETE response requirements

A.3.3. Parameter Leaf

Abstract Test 19

/conf/movingfeatures/param-leaf-definition

Requirement

/req/movingfeatures/param-leaf-definition

Test purpose

Validate that the leaf query parameter is constructed correctly.

Test method

Verify that the leaf query parameter complies with the definition (using an OpenAPI Specification 3.0 fragment)

Abstract Test 20

/conf/movingfeatures/param-leaf-response

Requirement

/req/movingfeatures/param-leaf-definition
/req/movingfeatures/param-leaf-response

Test purpose

Validate that the leaf query parameter is processed correctly.

Test method

DO FOR each Resource which have datetimes property:

1. Calculate a temporal geometry coordinate (or temporal property value) with the pointAtTime query at each time included in the leaf parameter, using interpolated trajectory according to the interpolation property
2. Verify that the temporal geometry coordinate (or temporal property value) intersects the interpolated trajectory according to the interpolation property, using datetime value defined by the leaf parameter

A.3.4. TemporalGeometrySequence

HTTP GET Operation

Abstract Test 21

/conf/movingfeatures/tgsequence-get

Requirement

/req/movingfeatures/tgsequence-get
/req/movingfeatures/tgsequence-get-success

Test purpose

Validate that the TemporalGeometrySequence can be identified and extracted from a MovingFeature object using query parameters.

Test method

For every TemporalGeometrySequence identified in MovingFeature, issue an HTTP GET request to the URL {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence where {collectionId} is the id property for a MovingFeature Collection described in the MovingFeature Collection content and {mFeatureId} is the id property for the MovingFeature

1. Validate that a document was returned with a status code 200
2. Validate the contents of the returned document using test /conf/movingfeatures/tgsequence-get-success

Repeat these tests using the following parameter tests that defined in the OGC API — Common and OGC API — MF:
- Bounding Box: Bounding Box Tests
- Limit: Limit Tests
- Date-Time: Date-Time Tests
- Leaf: Leaf Definition Test and Leaf Response Test

Execute requests with combinations of the "bbox", "datetime", and "leaf" query parameters and verify that only features are returned that match both selection criteria.

Abstract Test 22

/conf/movingfeatures/tgsequence-get-success

Requirement

/req/movingfeatures/tgsequence-get-success

Test purpose

Validate that the TemporalGeometrySequence complies with the required structure and contents.

Test method

1. Validate that the type property is present and has a value of MovingGeometryCollection
2. Validate the prism property is present and that it is populated with an array of TemporalPrimitiveGeometry items
3. Validate that only TemporalPrimitiveGeometry which match the selection criteria are included in the MovingFeature
4. If the links property is present, validate that all entries comply with OGC API — Features /conf/core/fc-links
5. If the timeStamp property is present, validate that it complies with OGC API — Features /conf/core/fc-timeStamp
6. If the numberMatched property is present, validate that it complies with OGC API — Features /conf/core/fc-numberMatched
7. If the numberReturned property is present, validate that it complies with OGC API — Features /conf/core/fc-numberReturned
8. Validate the TemporalGeometry resource for all supported media types using the resources and tests identified in Table 20

The TemporalPrimitiveGeometry content may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the against that schema. All supported formats should be exercised.

Table 20. Schema and Tests for **TemporalGeometrySequence** content
Format	Schema Document	Test ID
HTML	temporalGeometrySequence.yaml	/conf/html/content
JSON	temporalGeometrySequence.yaml	/conf/json/content

HTTP POST Operation

Abstract Test 23

/conf/movingfeatures/tgsequence-post

Requirement

/req/movingfeatures/tpgeometry-mandatory
/req/movingfeatures/tgsequence-post
/req/movingfeatures/tgsequence-post-success

Test purpose

Validate that the TemporalPrimitiveGeometry can be created at the expected location.

Test method

1. Validate that the server complies with OGC API — Features POST operation requirements
2. Validate that a body of a POST request using for all supported media types using the resources and tests identified in Table 21 and Table 9
3. Validate that the request body complies OGC API — Features POST request body requirements
4. Issue an HTTP POST request to the URL {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence
5. Validate the contents of the response using test /conf/movingfeatures/tgeometry-post-success

Table 21. Schema and Tests for Request Body of `{root}/collections/{collectionId}/items/{mFeatureId}/tgsequence` POST
Format	Schema Document	Test ID
JSON	MF-JSON_Prism.schema.json	/conf/json/content

Abstract Test 24

/conf/movingfeatures/tgsequence-post-success

Requirement

/req/movingfeatures/tgsequence-post-success

Test purpose

Validate that the response of {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence POST request complies with the required structure and contents.

Test method

1. Validate that a document was returned with a status code 201 or 202
2. Validate that all response documents comply with OGC API — Features POST response requirements

A.3.5. TemporalPrimitiveGeometry

HTTP DELETE Operation

Abstract Test 25

/conf/movingfeatures/tpgeometry-delete

Requirement

/req/movingfeatures/tpgeometry-delete
/req/movingfeatures/tpgeometry-delete-success

Test purpose

Validate that the TemporalPrimitiveGeometry can be deleted at the expected location.

Test method

1. Validate that the server complies with OGC API — Features DELETE operation requirements
2. Issue an HTTP DELETE request to the URL {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence/{tgeometryId}
3. Validate the contents of the response using test /conf/mf-collection/collections-put-success

Abstract Test 26

/conf/mf-collection/tpgeometry-delete-success

Requirement

/req/movingfeatures/tpgeometry-delete-success

Test purpose

Validate that the response of {root}/collections/{collectionId}/items/{mFeatureId}/tgsequence/{tGeometryId} DELETE request complies with the required structure and contents.

Test method

1. Validate that a document was returned with a status code 200, 202, or 204
2. Validate that all response documents comply with OGC API — Features DELETE response requirements

A.3.6. TemporalGeometry Query

HTTP GET Operation

Abstract Test 27

/conf/movingfeatures/tpgeometry-query-distance

Requirement

/req/movingfeatures/tpgeometry-query
/req/movingfeatures/tpgeometry-query-success

Test purpose

Validate that resources can be identified and extracted from a TemporalPrimitiveGeometry with a Distance query using query parameters.

Test method

IF a query parameter datetime is not empty, validate that the query parameter datetime with the following parameter tests that defined in the OGC API — Common:
- Date-Time: Date-Time Tests

1. Issue an HTTP GET request to the URL {root}/collections/{collectionId}/items/ {mFeatureId}/tgsequence/{tGeometryId}/distance
2. Validate that a document was returned with a status code 200
3. Verify the type is "TReal"

IF a query parameter datetime is not empty: Execute requests with datetime query parameter and verify the correctly calculated value is returned.

IF a query parameter datetime is empty: Verify that a time-to-distance curve is correctly returned according to the specified TemporalPrimitiveGeometry resource by {tGeometryId}.

Abstract Test 28

/conf/movingfeatures/tpgeometry-query-velocity

Requirement

/req/movingfeatures/tpgeometry-query
/req/movingfeatures/tpgeometry-query-success

Test purpose

Validate that resources can be identified and extracted from a TemporalPrimitiveGeometry with a Velocity query using query parameters.

Test method

IF a query parameter datetime is not empty, validate that the query parameter datetime with the following parameter tests that defined in the OGC API — Common:
- Date-Time: Date-Time Tests

1. Issue an HTTP GET request to the URL {root}/collections/{collectionId}/items/ {mFeatureId}/tgsequence/{tGeometryId}/velocity
2. Validate that a document was returned with a status code 200
3. Verify the type is "TReal"

IF a query parameter datetime is not empty: Execute requests with datetime query parameter and verify the correctly calculated value is returned.

IF a query parameter datetime is empty: Verify that a time-to-velocity curve is correctly returned according to the specified TemporalPrimitiveGeometry resource by {tGeometryId}.

Abstract Test 29

/conf/movingfeatures/tpgeometry-query-acceleration

Requirement

/req/movingfeatures/tpgeometry-query
/req/movingfeatures/tpgeometry-query-success

Test purpose

Validate that resources can be identified and extracted from a TemporalPrimitiveGeometry with a Acceleration query using query parameters.

Test method

IF a query parameter datetime is not empty, validate that the query parameter datetime with the following parameter tests that defined in the OGC API — Common:
- Date-Time: Date-Time Tests

1. Issue an HTTP GET request to the URL {root}/collections/{collectionId}/items/ {mFeatureId}/tgsequence/{tGeometryId}/acceleration
2. Validate that a document was returned with a status code 200
3. Verify the type is "TReal"

IF a query parameter datetime is not empty: Execute requests with datetime query parameter and verify the correctly calculated value is returned.

IF a query parameter datetime is empty: Verify that a time-to-acceleration curve is correctly returned according to the specified TemporalPrimitiveGeometry resource by {tGeometryId}.

A.3.7. TemporalProperties

HTTP GET Operation

Abstract Test 30

/conf/movingfeatures/tproperties-get

Requirement

/req/movingfeatures/tproperties-get
/req/movingfeatures/tproperties-get-success

Test purpose

Validate that the TemporalProperties can be identified and extracted from a MovingFeature object using query parameters.

Test method

For every TemporalProperty identified in MovingFeature, issue an HTTP GET request to the URL {root}/collections/{collectionId}/items/{mFeatureId}/tproperties where {collectionId} is the id property for a MovingFeature Collection described in the MovingFeature Collection content and {mFeatureId} is the id property for the MovingFeature

1. Validate that a document was returned with a status code 200
2. Validate the contents of the returned document using test /conf/movingfeatures/tproperties-get-success

Repeat these tests using the following parameter tests that are defined in the OGC API — Common:
- Limit: Limit Tests
- Date-Time: Date-Time Tests

Execute requests with combinations of the "datetime" query parameters and verify that only features are returned that match both selection criteria.

Abstract Test 31

/conf/movingfeatures/tproperties-get-success

Requirement

/req/movingfeatures/tproperties-get-success

Test purpose

Validate that the TemporalProperties complies with the required structure and contents.

Test method

1. Validate the TemporalProperties property is present and that it is populated with an array of TemporalProperty items
2. Validate that the name and type property is present
3. Validate the type property is present and its value is one of the predefined values (i.e., one of 'TBoolean', 'TText', 'TInteger', 'TReal', and 'TImage')
4. If the links property is present, validate that all entries comply with OGC API — Features /conf/core/fc-links
5. If the timeStamp property is present, validate that it complies with OGC API — Features /conf/core/fc-timeStamp
6. If the numberMatched property is present, validate that it complies with OGC API — Features /conf/core/fc-numberMatched
7. If the numberReturned property is present, validate that it complies with OGC API — Features /conf/core/fc-numberReturned
8. Validate the TemporalProperties resource for all supported media types using the resources and tests identified in Table 22

The TemporalProperties content may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the against that schema. All supported formats should be exercised.

Table 22. Schema and Tests for **TemporalProperties** content
Format	Schema Document	Test ID
HTML	temporalPropertyCollection.yaml	/conf/html/content
JSON	temporalPropertyCollection.yaml	/conf/json/content

HTTP POST Operation

Abstract Test 32

/conf/movingfeatures/tproperties-post

Requirement

/req/movingfeatures/tproperty-mandatory
/req/movingfeatures/tproperties-post
/req/movingfeatures/tproperties-post-success

Test purpose

Validate that the TemporalProperty can be created at the expected location.

Test method

1. Validate that the server complies with OGC API — Features POST operation requirements
2. Validate that a body of a POST request using for all supported media types using the resources and tests identified in Table 23 and Table 11
3. Validate that the request body complies OGC API — Features POST request body requirements
4. Issue an HTTP POST request to the URL {root}/collections/{collectionId}/items/{mFeatureId}/tproperties
5. Validate the contents of the response using test /conf/movingfeatures/tproperties-post-success

Table 23. Schema and Tests for Request Body of `{root}/collections/{collectionId}/items/{mFeatureId}/tproperties` POST
Format	Schema Document	Test ID
HTML	tproperty_requestbody.yaml	/conf/html/content
JSON	tproperty_requestbody.yaml	/conf/json/content
JSON	MF-JSON_Prism.schema.json	/conf/json/content

Abstract Test 33

/conf/movingfeatures/tproperties-post-success

Requirement

/req/movingfeatures/tproperties-post-success

Test purpose

Validate that the response of {root}/collections/{collectionId}/items/{mFeatureId}/tproperties POST request complies with the required structure and contents.

Test method

1. Validate that a document was returned with a status code 201 or 202
2. Validate that all response documents comply with OGC API — Features POST response requirements

A.3.8. TemporalProperty

HTTP GET Operation

Abstract Test 34

/conf/movingfeatures/tproperty-get

Requirement

/req/movingfeatures/tproperty-get
/req/movingfeatures/tproperty-get-success

Test purpose

Validate that the TemporalProperty can be identified and extracted from a TemporalProperties using query parameters.

Test method

For every TemporalProperty identified in MovingFeature, issue an HTTP GET request to the URL {root}/collections/{collectionId}/items/{mFeatureId}/tproperties/{tpropertyName} where {collectionId} is the id property for a MovingFeature Collection described in the MovingFeature Collections content, {mFeatureId} is the id property for the MovingFeature, {tpropertyName} is the name property for the TemporalProperty

1. Validate that a document was returned with a status code 200
2. Validate the contents of the returned document using test /conf/movingfeatures/tproperty-get-success

Repeat these tests using the following parameter tests that defined in the OGC API — Common and OGC API — MF:
- Limit: Limit Tests
- Date-Time: Date-Time Tests
- Leaf: Leaf Definition Test and Leaf Response Test

Execute requests with combinations of the "datetime" and "leaf" query parameters and verify that only features are returned that match both selection criteria.

Abstract Test 35

/conf/movingfeatures/tproperty-get-success

Requirement

/req/movingfeatures/tproperty-get-success

Test purpose

Validate that the TemporalProperty complies with the required structure and contents.

Test method

1. Validate the TemporalProperties property is present and that it is populated with an array of TemporalPrimitiveValue items
2. If the links property is present, validate that all entries comply with OGC API — Features /conf/core/fc-links
3. If the timeStamp property is present, validate that it complies with OGC API — Features /conf/core/fc-timeStamp
4. If the numberMatched property is present, validate that it complies with OGC API — Features /conf/core/fc-numberMatched
5. If the numberReturned property is present, validate that it complies with OGC API — Features /conf/core/fc-numberReturned
6. Validate the TemporalProperty resource for all supported media types using the resources and tests identified in Table 24

The TemporalProperty content may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate the against that schema. All supported formats should be exercised.

Table 24. Schema and Tests for **TemporalProperty** content
Format	Schema Document	Test ID
HTML	temporalProperty.yaml	/conf/html/content
JSON	temporalProperty.yaml	/conf/json/content

HTTP POST Operation

Abstract Test 36

/conf/movingfeatures/tproperty-post

Requirement

/req/movingfeatures/tproperty-mandatory
/req/movingfeatures/tproperty-post
/req/movingfeatures/tproperty-post-success

Test purpose

Validate that the TemporalPrimitiveValue can be created at the expected location.

Test method

1. Validate that the server complies with OGC API — Features POST operation requirements
2. Validate that a body of a POST request using for all supported media types using the resources and tests identified in Table 25 and Table 12
3. Validate that the request body complies OGC API — Features POST request body requirements
4. Issue an HTTP POST request to the URL {root}/collections/{collectionId}/items/{mFeatureId}/tproperties/{tPropertyName}
5. Validate the contents of the response using test /conf/movingfeatures/tproperty-post-success

Table 25. Schema and Tests for Request Body of `{root}/collections/{collectionId}/items/{mFeatureId}/tproperties/{tPropertyName}` POST
Format	Schema Document	Test ID
HTML	tvalue_requestbody.yaml	/conf/html/content
JSON	tvalue_requestbody.yaml	/conf/json/content

Abstract Test 37

/conf/movingfeatures/tproperty-post-success

Requirement

/req/movingfeatures/tproperty-post-success

Test purpose

Validate that the response of {root}/collections/{collectionId}/items/{mFeatureId}/tproperties/{tPropertyName} POST request complies with the required structure and contents.

Test method

1. Validate that a document was returned with a status code 201 or 202
2. Validate that all response documents comply with OGC API — Features POST response requirements

Annex B: Relationship with other OGC/ISO Standards (Informative)

This specification is built upon the following OGC/ISO Standards. The geometry concept is presented first, followed by the feature concept. Note that a feature is not a geometry. However, a feature often contains a geometry as one of its attributes. However, it is legal to build features without a geometry attribute, or with more than one geometry attributes.

B.1. Static geometries, features and accesses

The following standards define static objects, without time-varying properties.

B.1.1. Geometry (ISO 19107)

The ISO 19107, Geographic information — Spatial schema standard defines a GM_Object base type which is the root of all geometric objects. Some examples of GM_Object subtypes are GM_Point, GM_Curve, GM_Surface and GM_Solid. A GM_Object instance can be regarded as an infinite set of points in a particular coordinate reference system. The standard provides a GM_CurveInterpolation code list to identify how those points are computed from a finite set of points. Some interpolation methods listed by ISO 19107 are (non-exhaustive list):

linear: Positions on a straight line between each consecutive pair of control points.
geodesic: Positions on a geodesic curve between each consecutive pair of control points. A geodesic curve is a curve of shortest length. The geodesic shall be determined in the coordinate reference system of the curve.
circularArc3Points: For each set of three consecutive control points, a circular arc passing from the first point through the middle point to the third point. Note: if the three points are co-linear, the circular arc becomes a straight line.
elliptical: For each set of four consecutive control points, an elliptical arc passing from the first point through the middle points in order to the fourth point. Note: if the four points are co-linear, the arc becomes a straight line. If the four points are on the same circle, the arc becomes a circular one.
cubicSpline: The control points are interpolated using initial tangents and cubic polynomials, a form of degree 3 polynomial spline.

The UML below shows the GM_Object base type with its operations (e.g. distance(…) for computing the distance between two geometries). GM_Curve (not shown in this UML) is a subtype of GM_Primitive. All operations assume static objects, without time-varying coordinates or attributes.

Figure 5. GM_Object from ISO 19107:2003 figure 6

Geometry, topology and temporal-objects (GM_Object, TP_Object, TM_Object) are not abstractions of real-world phenomena. These types can provide types for feature properties as described in the next section but cannot be specialized to features.

B.1.2. Features (ISO 19109)

The ISO 19109, Geographic information — Rules for application schema standard defines types for the definition of features. A feature is an abstraction of a real-world phenomena. The terms “feature type” and “feature instance” are used to separate the following concepts of “feature”:

Feature type: The whole collection of real-world phenomena classified in a concept. For example the “bridge” feature type is the abstraction of the collection of all real-world phenomena that is classified into the concept behind the term “bridge”.
Feature instance: A certain occurrence of a feature type. For example “Tower Bridge” feature instance is the abstraction of a certain real-world bridge in London.

In object-oriented modelling, feature types are equivalent to classes and feature instances are equivalent to objects,

The UML below shows the General Feature Model. FeatureType is a metaclass that is instantiated as classes that represent individual feature types. A FeatureType instance contains the list of properties (attributes, associations and operations) that feature instances of that type can contain. Geometries are properties like any other, without any special treatment. All properties are static, without time-varying values.

Figure 6. General Feature Model from ISO 19109:2009 figure 5

B.1.3. Simple Features SQL

The Simple Feature Access — Part 2: SQL Option Standard describes a feature access implementation in SQL based on a profile of ISO 19107. This standard defines feature table as a table where the columns represent feature attributes, and the rows represent feature instances. The geometry of a feature is one of its feature attributes.

B.1.4. Filter Encoding (ISO 19143)

The ISO 19143, Geographic information — Filter encoding standard (also OGC Standard) provides types for constructing queries. These objects can be transformed into a SQL “SELECT … FROM … WHERE … ORDER BY …” statement to fetch data stored in a SQL-based relational database. Similarly, the same objects can be transformed into a XQuery expression in order to retrieve data from XML document. The UML below shows the objects used for querying a subset based on spatial operations such as “contains” or “intersects”.

Figure 7. Spatial operators from ISO 19143 figure 6

B.1.5. Features web API

The OGC 17-069, Features — Part 1: Core Standard specifies the fundamental building blocks for interacting with features using a Web API pattern. This Draft Standards defines how to get all features available on a server, or to get feature instances by their identifier.

B.1.6. Features Filtering web API

The draft OGC TBD, Features — Part 3: Filtering and the Common Query Language (CQL) standard extends the Feature web API with capabilities to encode more sophisticated queries. The conceptual model is close to ISO 19143.

B.2. Temporal Geometries and Moving Features

B.2.1. Moving Features (ISO 19141)

The ISO 19141, Geographic information — Schema for moving features standard extends the ISO 19107 spatial schema for addressing features whose locations change over time. Despite the “Moving Features” name, that standard is more about “Moving geometries”. The UML below shows how the MF_Trajectory type extends the “static” types from ISO 19107.

Figure 8. Trajectory type from ISO 19141 figure 3

Trajectory inherits operations shown below. Those operations are in addition to the operations inherited from GM_Object. For example the distance(…) operation from ISO 19107 is now completed by a nearestApproach(…) operation.

Figure 9. Temporal geometry from ISO 19141 figure 6

B.2.2. Moving Features XML encoding (OGC 18-075)

The OGC 18-075 Moving Features Encoding Part I: XML Core Standard takes a subset of the ISO 19141 Standard and defines an XML encoding. That standard also completes ISO 19141 by allowing to specify attributes whose value change over time. This extension to the above General Feature Model is shown below:

Figure 10. Dynamic attribute from OGC 18-075 figure 3

B.2.3. Moving Features JSON encoding (OGC 19-045)

The OGC 19-045 Moving Features Encoding Extension — JSON Standard takes a subset of the ISO 19141 Standard and defines a JSON encoding. The Standard provides various UML diagrams summarizing ISO 19141.

Annex C: Revision History

Date

Release

Editor

Primary clauses modified

Description

2021-09-14

0.1

Taehoon Kim, Kyoung-Sook Kim, and Martin Desruisseaux

all

first draft version

2022-03-01

0.2

Taehoon Kim, Kyoung-Sook Kim

all

revised sections related to resources to add CRUD operations

2022-10-09

0.3

Taehoon Kim, Kyoung-Sook Kim

all

added TemporalGeometry Query resources

2023-02-21

0.9

Taehoon Kim, Kyoung-Sook Kim, Mahmoud, and Esteban

all

finalize draft version

2023-05-19

0.9.9

Taehoon Kim, Kyoung-Sook Kim, Mahmoud, and Esteban

all

finalize draft version

2023-07-10

1.0.draft

Taehoon Kim, Kyoung-Sook Kim, Mahmoud, and Esteban

all

finalize draft version

Annex D: Bibliography

[1] OGC: OGC Moving Features Encoding Extension — JSON. (2020).

[2] OGC: OGC Moving Features Access. (2017).

[3] OGC: OGC API — Features — Part 1: Core. (2019).

[4] OGC: OGC API — Features — Part 2: Coordinate Reference Systems by Reference. (2020).

[5] OGC: OGC API — Features — Part 4: Create, Replace, Update and Delete. (2020).

[6] OGC: OGC API — Features, https://ogcapi.ogc.org/features/

[7] OGC: OGC API — Common, https://ogcapi.ogc.org/common/

[8] OGC: OGC API, https://ogcapi.ogc.org/

[9] OpenAPI, https://www.openapis.org/