oSIST prEN ISO 19168-1:2023

Geographic information - Geospatial API for features - Part 1: Core (ISO/DIS 19168-1:2023)

This document specifies the behaviour of Web APIs that provide access to features in a dataset in a manner independent of the underlying data store. This document defines discovery and query operations.
Discovery operations enable clients to interrogate the API, including the API definition and metadata about the feature collections provided by the API, to determine the capabilities of the API and retrieve information about available distributions of the dataset.
Query operations enable clients to retrieve features from the underlying data store based upon simple selection criteria, defined by the client.

Geoinformationen - Raumbezogene API für Features - Teil 1: Kern (ISO/DIS 19168-1:2023)

Information géographique - API géospatiale pour les entités - Partie 1: Profil minimal (ISO/DIS 19168-1:2023)

Le présent document spécifie le comportement des API Web donnant accès aux entités d'un jeu de données indépendamment du système sous-jacent de stockage de données. Le présent document définit les opérations de découverte et d'interrogation.
Les opérations de découverte permettent aux clients d'interroger l'API, y compris la définition et les métadonnées de l'API concernant les collections d'entités fournies par l'API, pour déterminer les capacités de l'API et extraire des informations relatives aux distributions disponibles de jeux de données.
Les opérations d'interrogation permettent aux clients d'extraire des entités du système sous-jacent de stockage de données sur la base de critères de sélection simples définis par le client.

Geografske informacije - Geoprostorski API za funkcije - 1. del: Osrednji profil (ISO/DIS 19168-1:2023)

General Information

• Status: Not Published
• Public Enquiry End Date: 13-Oct-2023
• ICS: 07.040 - Astronomy. Geodesy. Geography
• ICS: 35.240.70 - IT applications in science
• Technical Committee: GIG - Geographic information
• Current Stage: 4020 - Public enquire (PE) (Adopted Project)
• Start Date: 04-Aug-2023
• Due Date: 22-Dec-2023
• Ref Project: prEN ISO 19168-1 - Geographic information - Geospatial API for features - Part 1: Core (ISO/DIS 19168-1:2023)

Relations

• Revises: SIST EN ISO 19168-1:2021 - Geographic information - Geospatial API for features - Part 1: Core (ISO 19168-1:2020)
• Effective Date: 20-Feb-2023

Standards Content (Sample)

SLOVENSKI STANDARD
oSIST prEN ISO 19168-1:2023
01-oktober-2023
Geografske informacije - Geoprostorski API za funkcije - 1. del: Osrednji profil
(ISO/DIS 19168-1:2023)
Geographic information - Geospatial API for features - Part 1: Core (ISO/DIS 19168-
1:2023)
Geoinformationen - Raumbezogene API für Features - Teil 1: Kern (ISO/DIS 19168-
1:2023)
Information géographique - API géospatiale pour les entités - Partie 1: Profil minimal
(ISO/DIS 19168-1:2023)
Ta slovenski standard je istoveten z: prEN ISO 19168-1
ICS:
07.040 Astronomija. Geodezija. Astronomy. Geodesy.
Geografija Geography
35.240.70 Uporabniške rešitve IT v IT applications in science
znanosti
oSIST prEN ISO 19168-1:2023 en,fr,de
2003-01.Slovenski inštitut za standardizacijo. Razmnoževanje celote ali delov tega standarda ni dovoljeno.

---------------------- Page: 1 ----------------------
oSIST prEN ISO 19168-1:2023

---------------------- Page: 2 ----------------------
oSIST prEN ISO 19168-1:2023
DRAFT INTERNATIONAL STANDARD
ISO/DIS 19168-1
ISO/TC 211 Secretariat: SIS
Voting begins on: Voting terminates on:
2023-08-02 2023-10-25
Geographic information — Geospatial API for features —
Part 1:
Core
Information géographique — API géospatiale pour les entités —
Partie 1: Profil minimal
ICS: 35.240.70
This document is circulated as received from the committee secretariat.
THIS DOCUMENT IS A DRAFT CIRCULATED
FOR COMMENT AND APPROVAL. IT IS
ISO/CEN PARALLEL PROCESSING
THEREFORE SUBJECT TO CHANGE AND MAY
NOT BE REFERRED TO AS AN INTERNATIONAL
STANDARD UNTIL PUBLISHED AS SUCH.
IN ADDITION TO THEIR EVALUATION AS
BEING ACCEPTABLE FOR INDUSTRIAL,
TECHNOLOGICAL, COMMERCIAL AND
USER PURPOSES, DRAFT INTERNATIONAL
STANDARDS MAY ON OCCASION HAVE TO
BE CONSIDERED IN THE LIGHT OF THEIR
POTENTIAL TO BECOME STANDARDS TO
WHICH REFERENCE MAY BE MADE IN
Reference number
NATIONAL REGULATIONS.
ISO/DIS 19168-1:2023(E)
RECIPIENTS OF THIS DRAFT ARE INVITED
TO SUBMIT, WITH THEIR COMMENTS,
NOTIFICATION OF ANY RELEVANT PATENT
RIGHTS OF WHICH THEY ARE AWARE AND TO
PROVIDE SUPPORTING DOCUMENTATION. © ISO 2023

---------------------- Page: 3 ----------------------
oSIST prEN ISO 19168-1:2023
ISO/DIS 19168-1:2023(E)
DRAFT INTERNATIONAL STANDARD
ISO/DIS 19168-1
ISO/TC 211 Secretariat: SIS
Voting begins on: Voting terminates on:

Geographic information — Geospatial API for features —
Part 1:
Core
Information géographique — API géospatiale pour les entités —
Partie 1: Profil minimal
ICS: 35.240.70
This document is circulated as received from the committee secretariat.
COPYRIGHT PROTECTED DOCUMENT
THIS DOCUMENT IS A DRAFT CIRCULATED
FOR COMMENT AND APPROVAL. IT IS
© ISO 2023
ISO/CEN PARALLEL PROCESSING
THEREFORE SUBJECT TO CHANGE AND MAY
All rights reserved. Unless otherwise specified, or required in the context of its implementation, no part of this publication may
NOT BE REFERRED TO AS AN INTERNATIONAL
be reproduced or utilized otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting on STANDARD UNTIL PUBLISHED AS SUCH.
the internet or an intranet, without prior written permission. Permission can be requested from either ISO at the address below
IN ADDITION TO THEIR EVALUATION AS
or ISO’s member body in the country of the requester. BEING ACCEPTABLE FOR INDUSTRIAL,
TECHNOLOGICAL, COMMERCIAL AND
ISO copyright office
USER PURPOSES, DRAFT INTERNATIONAL
CP 401 • Ch. de Blandonnet 8
STANDARDS MAY ON OCCASION HAVE TO
BE CONSIDERED IN THE LIGHT OF THEIR
CH-1214 Vernier, Geneva
POTENTIAL TO BECOME STANDARDS TO
Phone: [phone]
WHICH REFERENCE MAY BE MADE IN
Reference number
Email: [e-mail]
NATIONAL REGULATIONS.
Website: www.iso.org ISO/DIS 19168-1:2023(E)
RECIPIENTS OF THIS DRAFT ARE INVITED
Published in Switzerland
TO SUBMIT, WITH THEIR COMMENTS,
NOTIFICATION OF ANY RELEVANT PATENT
RIGHTS OF WHICH THEY ARE AWARE AND TO
ii
  © ISO 2023 – All rights reserved
PROVIDE SUPPORTING DOCUMENTATION. © ISO 2023

---------------------- Page: 4 ----------------------
oSIST prEN ISO 19168-1:2023
ISO/DIS 19168-1:2023(E)
Contents Page
Foreword .v
Introduction .vii
1 Scope . 1
2 Normative references . 1
3 Terms and definitions . 2
3.1 Terms and definitions . 2
3.2 Abbreviated terms . 3
4 Conformance . 3
5 Conventions . 4
5.1 Identifiers . 4
5.2 Link relations . 4
5.3 Use of HTTPS . 5
5.4 HTTP URIs . 5
5.5 API definition . 6
5.5.1 General remarks . 6
5.5.2 Role of OpenAPI . 6
5.5.3 References to OpenAPI components in normative statements . 6
5.5.4 Paths in OpenAPI definitions . 7
5.5.5 Reusable OpenAPI components . 7
6 Overview . 7
6.1 Design Considerations . 7
6.2 Encodings . 8
6.3 Examples . 9
7 Requirements Class "Core" .9
7.1 Overview . 9
7.2 API landing page . 11
7.2.1 Operation . 11
7.2.2 Response . . 11
7.2.3 Error situations .12
7.3 API definition . 12
7.3.1 Operation .12
7.3.2 Response . .12
7.3.3 Error situations .12
7.4 Declaration of conformance classes . 13
7.4.1 Operation .13
7.4.2 Response . .13
7.4.3 Error situations .13
7.5 HTTP 1.1 . 13
7.5.1 HTTP status codes . 14
7.6 Unknown or invalid query parameters . 15
7.7 Web caching . 15
7.8 Support for cross-origin requests . 15
7.9 Encodings . 16
7.10 String internationalization . 16
7.11 Coordinate reference systems . 17
7.12 Link headers . 17
7.13 Feature collections . 17
7.13.1 Operation . 17
7.13.2 Response . . 18
7.13.3 Error situations . 24
7.14 Feature collection . 24
7.14.1 Operation . 24
iii
© ISO 2023 – All rights reserved

---------------------- Page: 5 ----------------------
oSIST prEN ISO 19168-1:2023
ISO/DIS 19168-1:2023(E)
7.14.2 Response . . 24
7.14.3 Error situations .25
7.15 Features . 25
7.15.1 Operation . 25
7.15.2 Parameter limit.25
7.15.3 Parameter bbox .26
7.15.4 Parameter datetime. 27
7.15.5 Parameters for filtering on feature properties .29
7.15.6 Combinations of filter parameters .30
7.15.7 Response . .30
7.15.8 Error situations . 32
7.16 Feature . 33
7.16.1 Operation . 33
7.16.2 Response . . 33
7.16.3 Error situations .33
8 Requirements classes for encodings .34
8.1 Overview .34
8.2 Requirements Class "HTML" .34
8.3 Requirements Class "GeoJSON" . 35
8.4 Requirements Class "Geography Markup Language (GML), Simple Features
Profile, Level 0" . 36
8.5 Requirements Class "Geography Markup Language (GML), Simple Features
Profile, Level 2" .38
9 Requirements class "OpenAPI 3.0" .38
9.1 Basic requirements .38
9.2 Complete definition . 39
9.3 Exceptions. 39
9.4 Security .40
9.5 Features .40
10 Media Types .40
11 Security Considerations .41
11.1 Multiple Access Routes . 41
11.2 Multiple Servers . 42
11.3 Path Manipulation on GET . 42
11.4 Path Manipulation on PUT and POST . 42
Annex A (normative) Abstract Test Suite .43
Bibliography .59
iv
  © ISO 2023 – All rights reserved

---------------------- Page: 6 ----------------------
oSIST prEN ISO 19168-1:2023
ISO/DIS 19168-1:2023(E)
Foreword
ISO (the International Organization for Standardization) is a worldwide federation of national standards
bodies (ISO member bodies). The work of preparing International Standards is normally carried out
through ISO technical committees. Each member body interested in a subject for which a technical
committee has been established has the right to be represented on that committee. International
organizations, governmental and non-governmental, in liaison with ISO, also take part in the work.
ISO collaborates closely with the International Electrotechnical Commission (IEC) on all matters of
electrotechnical standardization.
The procedures used to develop this document and those intended for its further maintenance are
described in the ISO/IEC Directives, Part 1. In particular, the different approval criteria needed for the
different types of ISO document should be noted. This document was drafted in accordance with the
editorial rules of the ISO/IEC Directives, Part 2 (see www.iso.org/directives).
ISO draws attention to the possibility that the implementation of this document may involve the use
of (a) patent(s). ISO takes no position concerning the evidence, validity or applicability of any claimed
patent rights in respect thereof. As of the date of publication of this document, ISO [had/had not] received
notice of (a) patent(s) which may be required to implement this document. However, implementers are
cautioned that this may not represent the latest information, which may be obtained from the patent
database available at www.iso.org/patents. ISO shall not be held responsible for identifying any or all
such patent rights.
Any trade name used in this document is information given for the convenience of users and does not
constitute an endorsement.
For an explanation of the voluntary nature of standards, the meaning of ISO specific terms and
expressions related to conformity assessment, as well as information about ISO's adherence to
the World Trade Organization (WTO) principles in the Technical Barriers to Trade (TBT), see
www.iso.org/iso/foreword.html.
This document was prepared by Technical Committee ISO/TC 211, Geographic information/Geomatics.
This second edition cancels and replaces the first edition (ISO 19168-1:2020), which has been technically
revised.
The main changes are as follows:
Bugfixes:
— Fix core.xsd
— Correct links to RFCs
— describedBy -> describedby
— Fix Abstract Test Suite
— Add dependencies in ATS
— Fix links to RFCs
— Set rel in the links schema to required
— Reference RFC 723x for HTTP 1.1
— Fix issues in the Abstract Test Suite
— Correct reference
— Value of parameter profile should be in quotes
v
© ISO 2023 – All rights reserved

---------------------- Page: 7 ----------------------
oSIST prEN ISO 19168-1:2023
ISO/DIS 19168-1:2023(E)
— Change dateTime to datetime in Annex A
Improvements and clarifications:
— Add conformance class URIs to clause 2
— Add note to clarify requirements on spatial/temporal
— Update OpenAPI 3.0 reference
— Update definition of dataset
— Relax use of "distribution"
— Clarify use of a degenerated bbox
— Clarifications on temporal coordinate reference systems
— Update links to OpenAPI Specification
— Enforce that bbox extents are 4 or 6 numbers
— Discuss self and alternate links for collections
— Clarify /req/oas30/oas-definition-1
— Add clarification on next links
— Add clarification on headers in GML-SF responses
— Clarification on limit parameter
— Clarify use of 'default CRS'
— Add recommendation for self/alternate links on landing page
— Add references to bbox-crs
— Clarify /req/core/sfc-md-success
— Add definition of landing page
— Clarification on multiple bounding boxes in an extent
— Clarification on paging and extent
— Wording of test for featureId ambiguous
— Clarify interval terminology
— Add note on itemType
A list of all parts in the ISO 19168 series can be found on the ISO website.
Any feedback or questions on this document should be directed to the user’s national standards body. A
complete listing of these bodies can be found at www.iso.org/members.html.
vi
  © ISO 2023 – All rights reserved

---------------------- Page: 8 ----------------------
oSIST prEN ISO 19168-1:2023
ISO/DIS 19168-1:2023(E)
Introduction
[10]
OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent
way. The OpenAPI specification is used to define the API building blocks.
The OGC API family of standards is organized by resource type. This standard specifies the fundamental
API building blocks for interacting with features. The spatial data community uses the term 'feature'
for things in the real world that are of interest.
For those not familiar with the term 'feature,' the explanations on Spatial Things, Features and
[7]
Geometry in the W3C/OGC Spatial Data on the Web Best Practice document provide more detail.
OGC API Features provides API building blocks to create, modify and query features on the Web. OGC
API Features is comprised of multiple parts, each of them is a separate standard. This part, the "Core,"
specifies the core capabilities and is restricted to fetching features where geometries are represented
in the coordinate reference system WGS 84 with axis order longitude/latitude. Additional capabilities
that address more advanced needs will be specified in additional parts. Examples include support for
creating and modifying features, more complex data models, richer queries, additional coordinate
reference systems, multiple datasets and collection hierarchies.
By default, every API implementing this standard will provide access to a single dataset. Rather than
sharing the data as a complete dataset, the OGC API Features standards offer direct, fine-grained access
to the data at the feature (object) level.
The API building blocks specified in this standard are consistent with the architecture of the Web. In
particular, the API design is guided by the IETF HTTP/HTTPS RFCs, the W3C Data on the Web Best
[8] [7]
Practices, the W3C/OGC Spatial Data on the Web Best Practices, and the emerging OGC Web API
Guidelines. A particular example is the use of the concepts of datasets and dataset distributions as
[9]
defined in DCAT and used in schema.org.
This standard specifies discovery and query operations that are implemented using the HTTP GET
method. Support for additional methods (in particular POST, PUT, DELETE, PATCH) will be specified in
additional parts.
Discovery operations enable clients to interrogate the API, including the API definition and metadata
about the feature collections provided by the API, to determine the capabilities of the API and retrieve
information about available distributions of the dataset.
Query operations enable clients to retrieve features from the underlying data store based upon simple
selection criteria, defined by the client.
A subset of the OGC API family of standards is expected to be published by ISO. For example, this
document is in the process to be published by ISO as ISO 19168-1. To reflect that only a subset of the
OGC API standards will be published by ISO and to avoid using organization names in the titles of ISO
standards, standards from the "OGC API" series are published by ISO as "Geospatial API." That is, the
title of this document in OGC is "OGC API - Features - Part 1:Core" and the title in ISO is "Geographic
Information - Geospatial API for Features - Part 1: Core."
For simplicity, this document consistently uses:
— "OGC API" to refer to the family of standards for geospatial Web APIs that in ISO is published as
"Geospatial API;"
— "OGC API - Features" to refer to the multipart standard for features that in ISO is published as
ISO 19168 / "Geographic Information - Geospatial API for Features;" and
— "OGC API - Features - Part 1: Core" to refer to this document that in ISO is published as ISO 19168-1
/ "Geographic Information - Geospatial API for Features - Part 1: Core."
This standard defines the resources listed in Table 1. For an overview of the resources, see section 7.1
Overview.
vii
© ISO 2023 – All rights reserved

---------------------- Page: 9 ----------------------
oSIST prEN ISO 19168-1:2023
ISO/DIS 19168-1:2023(E)
Table 1 — Overview of resources,
...