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.


 

i. Abstract

The OpenSearch specification [NR3] is defined as a binding of the Abstract Protocol Definition (APD) for the searchRetrieve operation, one of a set of documents [NR4] for the OASIS Search Web Services (SWS) initiative [OR1]. The OpenSearch Description Document (OSDD) allows clients to retrieve service metadata from an OpenSearch implementation. The OSDD format allows the use of extensions that allow search engines to inform clients about specific and contextual query parameters and response formats. The OpenSearch extension for Earth Observation (EO) collections and products search is defined in [OR20]. The mandatory response format is based on Atom 1.0/XML [OR14].

JavaScript Object Notation (JSON) [NR1] has been gaining in popularity for encoding data in Web-based applications. JSON consists of sets of objects described by name/value pairs.  GeoJSON [NR2] is a format for encoding collections of simple geographical features along with their non-spatial attributes using JSON. This OGC standard describes a GeoJSON [NR2] and JSON-LD [NR15] encoding for OpenSearch Response documents.

The GeoJSON encoding defined in this document is defined as a compaction[1] through a normative context, of the proposed JSON-LD encoding, with some extensions as presented in section 8 of this document.  Therefore, the JSON-LD encoding can also be applied to other RDF [OR8] encodings including RDF/XML [OR11] and RDF Turtle [OR12].

Although this document makes no assumptions as to the "service" interfaces through which the Search Response is obtained and applies equally well to a Service Oriented Architecture as well as a Resource Oriented or RESTful architecture.  The documented approach is mainly intended to be applied in combination with the following technologies:

  • OGC OpenSearch extensions [OR19], [OR20], [NR3].

GeoJSON is a format for encoding collections of simple geographical features along with their non-spatial attributes using JSON. GeoJSON objects may represent a geometry, a feature, or a collection of features. GeoJSON supports the following geometry types derived from the OGC Simple Features specification: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon and GeometryCollection. Features in GeoJSON contain a geometry object and additional properties, and a feature collection represents a list of features.

JSON is human readable and easily parseable. However, JSON is schemaless.  JSON and GeoJSON documents do not include an explicit definition of the structure of the JSON objects contained in them.  Therefore, this standard is based on a normative JSON-LD context which allows each property to be explicitly defined as a URI.  Furthermore, the JSON encoding is defined using JSON Schema [OR24] which allows validation of instances against these schemas.

ii.   Keywords

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

ogcdoc, ogc documents, Earth Observation, EO Collection, EO Product, GeoJSON, JSON, JSON-LD, Linked Data, Metadata, OpenSearch, OpenSearch Earth Observation Service

iii.   Preface

The recent release of the document is the result of work sponsored by EUMETSAT and ESA in the context of the continuation of the ESA HMA (Heterogeneous Missions Accessibility) initiative.

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 when possible.

iv.   Submitting organizations

The following organizations will submit the original document or its revisions to the Open Geospatial Consortium (OGC):

  • CEOS – Committee on Earth Observation Satellites
  • CGI
  • Con terra GmbH
  • ESA – European Space Agency
  • EUMETSAT
  • Spacebel s.a.

The editors would like to acknowledge that this work is the result of collaboration and review of many organizations and would like to thank for the comments and contributions from:

  • DLR
  • GeoSolutions
  • VITO

Note: this acknowledgement does not imply a complete endorsement by these organizations.

v.   Submitters

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

Name

Affiliation

Yves Coene

Spacebel s.a.

Uwe Voges

con terra GmbH

Olivier Barois

ESA

Andrea Della Vecchia

ESA

John Taylor

CGI

Michael Schick

EUMETSAT

 

1        Scope

1.1       OpenSearch Extension for Earth Observation

The OpenSearch extension for Earth Observation (EO) is defined in OGC 13-026r9 [OR20]. It is complementary to the OpenSearch Geo and Time Extensions [OR19] and recommends their use for spatial and temporal queries. It specifies a series of additional parameters that can be used to constrain searches especially for EO collection and EO product metadata. Further it defines a search operation response model supporting best practices for REST API´s such as HATEOAS (Hypermedia As The Engine Of Application State) and a default response encoding based on Atom 1.0/XML [OR14].

The OpenSearch Description Document (OSDD) allows clients to retrieve service metadata from an OpenSearch implementation. The OSDD format allows the use of extensions that allow search engines to inform clients about specific and contextual query parameters and response formats.

1.2       OpenSearch Extension for Earth Observation Response Model

The response of an OpenSearch search request can be considered a container which contains resources as search response entries. The container itself includes information about the discovery service or search engine. It further adds some specific "search metadata" (e.g., total results of a search). The resources of an OpenSearch search response can be of different types, e.g., EO collection metadata or EO product metadata. The model is applicable to multiple types of resources. Therefore, this model just includes elements which can easily be derived (mapped) from different native metadata models used to describe different kinds of resources.

Further resource details can be acquired by following hyperlinks (see below) which, for example, lead to related searches (to implement two-step-searches [OR20]) or to alternative representations (including full native metadata descriptions, the data described by the metadata,  previews etc.). Those hyperlinks support the best practices for (Hypermedia) API´s such as HATEOAS.

The supported response formats for a search operation are advertised in the OSDD of a given OpenSearch instance. The default response format is Atom/XML and is defined in [OR20]. Other formats may be supported by the server as well. One of these formats is GeoJSON(-LD), a format for encoding a feature (representing a resource) and a collection of features (representing a container).

This OGC standard defines a GeoJSON [NR2] and JSON-LD [NR15] encoding of the OpenSearch response format as an alternative to its default Atom/XML representation.  It does not (re)define the OpenSearch search parameters as these were defined in [OR20]. Their mapping to the GeoJSON response format is included in Annex F: of the current document for the convenience of the reader.

Table : Overview of OpenSearch Extension for EO Documents

 

Atom/XML
Implementation

GeoJSON(-LD) Implementation

Search request and search parameter definitions

OGC 13-026r9

OGC 13-026r9

Search response definition

OGC 13-026r9

OGC 17-047r1

 

It is worthwhile noting that although the encoding is intended for use in the Earth Observation domain (i.e., searches for EO collections or products), the proposed encoding can also be applied to other domains.  The only assumption made is that resource metadata is modelled as GeoJSON features. 

1.3       Design Approach and Rationale

This section is non-normative.

The response encoding defined in the document satisfies the following design goals.

  • Feature-based GeoJSON model: The model maximises reuse of pre-existing standardised property names.  Whereever possible, existing properties from the GeoJSON [NR2] and OWS Context [NR5] FeatureCollection objects are used for modelling Search response properties instead of proposing new property names.  Existing properties are extended where needed (e.g., links).
  • Generic solution: The document proposes JSON objects and properties for representing OpenSearch response elements.  The model remains very close to the original XML encoding (e.g., same property names where possible) and can express the same information.  There is no assumption about the content of the actual "features."

 

1.4       Document Outline

Hereafter a brief outline of the document content allows readers to jump directly to the topic of their interest.

  • Chapter 3 lists the normative and informative references used in this document.
  • Chapter 4 defines the main terms used in the document.
  • The conventions used in this document are explained in Chapter 5.
  • Chapter 6 gives an overview.
  • Chapter 7 specifies the proposed GeoJSON encoding.
  • Chapter 8 describes how the encoding can be extended with additional properties and describes the extension to JSON-LD which allows for describing multi-dimensional arrays as allowed by GeoJSON.
  • Chapter 9 provides information about the expected MIME media types which correspond to the proposed encodings.
  • Chapter 10 describes future work.

Finally, the following information was moved to the appendices.

  • Annex A defines the Abstract Test Suite for the standard.
  • Annex B includes normative JSON-LD @context definitions that allow interpreting the GeoJSON encoding as JSON-LD.
  • Annex C.1 presents the mapping of the properties proposed in this specification to the XML Response model. Annex C.2 compares the response elements with the corresponding elements of the OpenSearch Atom response and OASIS Abstract Protocol Binding.
  • Annex D contains the complete listing of examples illustrating the encodings defined in this document.
  • Annex E includes the JSON schema definitions defining the GeoJSON encoding.
  • Annex F defines the mapping of OpenSearch parameters defined in OGC 13-026r9 on JSON properties defined in OGC 17-003r2 and OGC 17-084.
  • Annex G explains where the schema file, context files and examples can be found in the OGC schema repository.
  • Annex H provides the revision history of this document.

 


2        Conformance

2.1       Conformance to base specifications

This section describes the compliance testing required for an implementation of this standard.

2.2       Conformance classes

The framework, concepts, and methodology for testing, and the criteria to be achieved in order to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site[2].

Annex A defines a set of tests and conformance classes that will support various applications with a range of different requirements.  The following conformance classes are distinguished. Testing is based on data validation. In order to conform to this OGC standard, an implementation shall implement all conformance classes specified in Annex A (normative).

 

Table : Conformance classes related to data instances

Conformance Class

Description

Clause

/conf/core

Core conformance class.

7.1

/conf/feature-collection

FeatureCollection objects.

7.2

/conf/properties

Properties objects.

7.2.1

/conf/links

Links objects.

7.2.5

/conf/control-information

ControlInformation objects.

7.3

/conf/queries

Queries objects.

7.3.1

/conf/feature

Feature objects.

7.4

/conf/feature-properties

Feature Property objects.

7.4.1

/conf/exceptions

Exception related objects.

7.5

/conf/exception-report

ExceptionReport objects.

7.5.2


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.

3.1       Normative references

 

[NR1]          RFC 7159, The JavaScript Object Notation (JSON) Data Interchange Format, 2014, http://www.ietf.org/rfc/rfc7159.txt

[NR2]          RFC 7946, The GeoJSON Format, 2016, https://tools.ietf.org/html/rfc7946

[NR3]          OpenSearch 1.1 Draft 5, http://www.opensearch.org/Specifications/OpenSearch/1.1

[NR4]          OASIS OpenSearch - searchRetrieve: Part 4. APD Binding for OpenSearch Version 1.0, OASIS Standard, 2013, http://docs.oasis-open.org/search-ws/searchRetrieve/v1.0/searchRetrieve-v1.0-part4-opensearch.html

[NR5]          OGC 14-055r2, OGC OWS Context GeoJSON Encoding, 2017, http://docs.opengeospatial.org/is/14-055r2/14-055r2.html

[NR6]          OGC 06-121r9, OGC Web Services Common Standard, Version 2.0.0, 2010, http://portal.opengeospatial.org/files/?artifact_id=38867

[NR7]          RFC 3986, Uniform Resource Identifiers (URI): Generic Syntax, 2005, http://www.ietf.org/rfc/rfc3986.txt

[NR8]          RFC 3987, Internationalised Resource Identifiers (IRIs), 2005, https://tools.ietf.org/html/rfc3987.

[NR9]          RFC 2616, Hypertext Transfer Protocol – HTTP/1.1, 1999, http://www.ietf.org/rfc/rfc2616.txt

[NR11]         RFC 5988, Web Linking, 2010,  http://www.ietf.org/rfc/rfc5988.txt

[NR12]         ECMA International, "ECMAScript Language Specification, Edition 5.1", Standard ECMA-262, 2011, http://www.ecma-international.org/publications/standards/Ecma-262.htm

[NR13]         The JSON Data Interchange Format, 2017, http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf        

[NR15]         JSON-LD 1.0, A JSON-based Serialisation for Linked Data, W3C Recommendation, 2014, http://www.w3.org/TR/json-ld/

3.2       Other references

 

[OR1]          OASIS searchRetrieve: Part 0. Overview, OASIS Standard, 2013, http://docs.oasis-open.org/search-ws/searchRetrieve/v1.0/os/part0-overview/searchRetrieve-v1.0-os-part0-overview.html.

[OR2]          OASIS searchRetrieve: Part 3. searchRetrieve Operation: APD Binding for SRU 2.0, Version 1.0, OASIS Standard, 2013, http://docs.oasis-open.org/search-ws/searchRetrieve/v1.0/os/part3-sru2.0/searchRetrieve-v1.0-os-part3-sru2.0.html.

[OR3]          Dublin Core Metadata Initiative, DCMI Metadata Terms, 2012, http://dublincore.org/documents/dcmi-terms/.

[OR4]          JSON-LD 1.0 Processing Algorithms and API, W3C Recommendation, 2014, https://www.w3.org/TR/json-ld-api/

[OR5]          OGC 12-084r2, OWS Context Atom Encoding Standard, 2013, http://docs.opengeospatial.org/is/12-084r2/12-084r2.html 

[OR6]          OGC 15-053, Implementing JSON/GeoJSON in an OGC Standard ER, 2015, Joan Masó.

[OR7]          OGC 11-052r4, OGC GeoSPARQL – A Geographic Query Language for RDF Data, Version 1.0, 2012, https://portal.opengeospatial.org/files/?artifact_id=47664, http://www.essepuntato.it/lode/owlapi/http://schemas.opengis.net/geosparql/1.0/geosparql_vocab_all.rdf

[OR8]          RDF 1.1 Primer, W3C Working Group Note, 2014, http://www.w3.org/TR/rdf11-primer/

[OR9]          RDF 1.1 Concepts and Abstract Syntax, W3C Recommendation, 2014, http://www.w3.org/TR/rdf11-concepts/

[OR10]        RDF Schema 1.1, W3C Recommendation, 2014, http://www.w3.org/TR/rdf-schema/

[OR11]        RDF 1.1 XML Syntax, W3C Recommendation, 2014, http://www.w3.org/TR/rdf-syntax-grammar/

[OR12]        RDF 1.1 Turtle, Terse RDF Triple Language, W3C Recommendation, 2014, http://www.w3.org/TR/turtle/

[OR13]        Data Catalog Vocabulary (DCAT), W3C Recommendation, 2014, https://www.w3.org/TR/vocab-dcat/.

[OR14]        RFC 4287, The Atom Syndication Format, 2005, https://tools.ietf.org/html/rfc4287 

[OR15]        Building JSON-LD APIs: Best Practices, Draft Community Group Report, 2016, http://json-ld.org/spec/latest/json-ld-api-best-practices/

[OR16]        Google JSON Style Guide, Revision 0.9, https://google.github.io/styleguide/jsoncstyleguide.xml

[OR17]        W3C vCard Ontology - for describing People and Organizations, W3C Interest Group Note, 2014, http://www.w3.org/TR/vcard-rdf/

[OR18]        GeoJSON-LD Vocabulary, http://geojson.org/geojson-ld/, http://geojson.org/geojson-ld/vocab.rdf

[OR19]        OGC 10-032r8, OGC OpenSearch Geo and Time Extensions, 2014, http://www.opengeospatial.org/standards/opensearchgeo

[OR20]        OGC 13-026r9, OGC OpenSearch Extension for Earth Observation Products., 2016

[OR21]        JSON-LD 1.1, "A JSON-based Serialisation for Linked Data", W3C Editor’s Draft, 2018, https://www.w3.org/TR/json-ld11/.

[OR22]        OGC 08-167r2, Semantic Annotations in OGC Standards, Version 2.0, 2012, https://portal.opengeospatial.org/files/?artifact_id=47857.

[OR23]        FOAF Vocabulary Specification 0.99, Namespace Document, 2014 – Paddington Edition, http://xmlns.com/foaf/spec/ .

[OR24]        JSON Schema, https://tools.ietf.org/html/draft-zyp-json-schema-04

[OR25]        http://goessner.net/articles/JsonPath/index.html

[OR26]        OGC 17-003, OGC EO Dataset Metadata GeoJSON(-LD) Encoding Standard, 2019

[OR27]        OGC 17-084, OGC EO Collection Metadata GeoJSON(-LD) Encoding Standard, 2019

[OR29]        Dublin Core Metadata Initiative term declarations represented in RDF schema language, http://dublincore.org/schemas/rdfs/.

[OR31]        SKOS Simple Knowledge Organization System Reference, W3C Recommendation, 2009, http://www.w3.org/TR/skos-reference/.

4        Terms and definitions

This document uses the terms defined in Sub-clause 5.3 of OGC 06-121r9 [NR6], 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.

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

4.1.          compaction

While expansion removes context from a given input, compaction’s primary function is to perform the opposite operation: to express a given input according to a particular context. Compaction applies a context that specifically tailors the way information is expressed for a particular person or application. This simplifies applications that consume JSON or JSON-LD by expressing the data in application-specific terms, and it makes the data easier to read by humans [OR4].

4.2.          collection

A Collection or a Dataset Series (in short Series) defines a container for a list of Products (or datasets) that have common properties. Products inherit all the Collection properties that are not explicitly overridden.

4.3.          context

A set of rules for interpreting a JSON-LD document as specified in the section "The Context" of the JSON-LD specification [NR15].

4.4.          dataset

Observation obtained by satellite instruments (OGC 10-140).  See granule and product.

4.5.          Domain (RDF)

Domain (rdfs:domain) is used to state that any resource that has a given property is an instance of one or more classes  [OR10].

4.6.          embedding

Embedding is a JSON-LD feature that allows using node objects as property values [NR15].

4.7.          expansion

The algorithm that removes [JSON-LD] context is called expansion [OR4].

4.8.          fatal exception

A server supplies exceptions (diagnostics) in the response as appropriate. A diagnostic is fatal or non-fatal. A fatal diagnostic is generated when the execution of the request cannot proceed and no results are available. For example, if the client supplied an invalid query there might be nothing that the server can do. A non-fatal diagnostic is one where processing may be affected but the server can continue (See section 2.9 of [OR2]).

4.9.          GeoJSON

A geospatial data interchange format based on Javascript Object Notation (JSON) [NR2].

4.10.       granule

The smallest aggregation of data that can be independently managed.  Granule usually matches the individual file of EO satellite data.

4.11.       identifier

A character string that may be composed of numbers and characters that is exchanged between the client and the server with respect to a specific identity of a resource.

4.12.       JSON

A lightweight, text-based, language-independent data interchange format, based on the Javascript programming language.

4.13.       JSON Schema

JSON Schema is a JSON media type for defining the structure of JSON data.  JSON Schema provides a contract for what JSON data is required for a given application and how to interact with it [OR24]. 

4.14.       OpenSearch

Draft specification for web search syndication, originating from Amazon’s A9 project and given a corresponding interface binding by the OASIS Search Web Services working group.

 

4.15.       OpenSearch Description Document (OSDD)

An XML document available at a consistent location describing metadata for the service and providing templates for queries (See [NR4] §5).

 

4.16.       Product

A Product or a Dataset corresponds to an identifiable collection of data under one single identifier. It is independent of a physical form or an encoding even if it is normally distributed in a single file.

 

4.17.       Range (RDF)

Range (rdfs:range) is used to state that values of a property are instances of one or more classes  [OR10].

4.18.       RDF Triple

An RDF triple consists of three components: the subject, the predicate and the object.  An RDF triple is conventionally written in the order subject, predicate, object.  [OR9].

4.19.       search entry

An element of the search response representing a catalogued resource [OR19].

4.20.       search feed

The response document of a search service request containing zero or more entries [OR19].

4.21.       service interface

Shared boundary between an automated system or human being and another automated system or human being [ISO 19101].


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       Abbreviated terms

Some frequently used abbreviated terms:

APD                 Abstract Protocol Definition

API                  Application Programming Interface

ATS                 Abstract Test Suite

CEOS               Committee on Earth Observation Satellites

EO                   Earth Observation

EOP                 Earth Observation Product

GML                Geography Markup Language

HATEOAS       Hypermedia As The Engine Of Application State

HMA               Heterogeneous Missions Accessibility

HTTP               HyperText Transfer Protocol

IRI                   Internationalised Resource Identifier

ISO                  International Organisation for Standardisation

JSON               JavaScript Object Notation

JSON-LD         JavaScript Object Notation for Linked Data

LDP                 Linked Data Protocol

OASIS             Organization for the Advancement of Structured Information Standards

OGC                Open Geospatial Consortium

O&M               Observations and Measurements

OWC               OGC Web Services Context

RDF                 Resource Description Framework

RDFS               RDF Schema

REST               Representational State Transfer

SI                     International System of Units (French: Système international d’unités)

SRU                 Search/Retrieval via URL

UML                Unified Modeling Language

URI                  Uniform Resource Identifier

URL                 Uniform Resource Locator

URN                Uniform Resource Name

W3C                World Wide Web Consortium

WGISS             Working Group on Information Systems and Services

WKT                Well-Known Text

XML                eXtensible Markup Language

XSD                 XML Schema Definition Language

5.2       Symbols

5.2.1       JSON Schema diagrams

The schema diagrams[3] included in the document show the JSON structure expressed in JSON Schema [OR24] and documented in Annex E.1.

 

Table : JSON Schema diagram symbols

JSON Schema Entity

Representation

Description

Definition

definition

Definitions are shown as blue rectangles with solid borders.

Mandatory property

mandatory property

Mandatory properties are shown with solid borders.

Optional property

optional property

Optional properties are shown with dashed borders.

Property of type "Object" referring to a "Definition" of the Object.

property of type object

The "Def" attribute inside a rectangle representing a property of type Object refers to the corresponding Object definition.

Pattern property

pattern property

A pattern property defines the property's name as a regular expression.  There are no minimum or maximum occurrence settings for a pattern property.

Unspecified property

unspecified property

A property can be implicitly specified by adding a suitable pattern property or property wildcard.

"All Of" operator

all of

Contains one or more sub-schemas (definitions), added as children of the operator. An instance is valid if it is valid against all these sub-schemas.

"Any Of" operator

any of

Contains one or more sub-schemas (definitions), added as children of the operator. An instance is valid if it is valid against at least one of these sub-schemas.

"One Of" operator

one of

Contains one or more sub-schemas (definitions), added as children of the operator. An instance is valid if it is valid against exactly one of these sub-schemas.

Subschema (definitions)

subschema

The "Def" attribute inside a rectangle representing a (Sub) Schema refers to the corresponding Object definition.

5.2.2       JSONPath

The data dictionary tables in the current document use the JSONPath notation [OR25].  A brief overview of this notation is included in the table below which is taken from [OR25].

 

Xpath

JSONPath

Description

/

$

the root object/element

.

@

the current object/element

/

. or []

child operator

//

..

recursive descent. JSONPath borrows this syntax from E4X.

*

*

wildcard. All objects/elements regardless their names.

[]

[]

subscript operator. Xpath uses it to iterate over element collections and for predicates. In Javascript and JSON it is the native array operator.

|

[,]

Union operator in Xpath results in a combination of node sets. JSONPath allows alternate names or array indices as a set.

[]

?()

applies a filter (script) expression.

 

5.3       Namespace abbreviations

The following namespace abbreviations will be used in this document:

 

Table : Namespace abbreviations

Abbreviation

Full namespace URI

Reference

atom

http://www.w3.org/2005/Atom/

[OR14]

dcat

http://www.w3.org/ns/dcat#

[OR13]

dct

http://purl.org/dc/terms/

[OR29]

eo

http://a9.com/-/opensearch/extensions/eo/1.0/

[OR20]

foaf

http://xmlns.com/foaf/0.1/

[OR23]

geo

http://a9.com/-/opensearch/extensions/geo/1.0/

[OR19]

gj

https://purl.org/geojson/vocab#

[OR18]

gsp

http://www.opengis.net/ont/geosparql#

[OR7]

os

http://a9.com/-/spec/opensearch/1.1/

[NR3]

owc

http://www.opengis.net/ont/owc/1.0/

[OR5]

owl

http://www.w3.org/2002/07/owl#

 

rdf

http://www.w3.org/1999/02/22-rdf-syntax-ns#

[OR11]

rdfs

http://www.w3.org/2000/01/rdf-schema#

[OR10]

skos

http://www.w3.org/2004/02/skos/core#

[OR31]

sru

http://docs.oasis-open.org/ns/search-ws/sruResponse/

[OR2]

sru

http://a9.com/-/opensearch/extensions/sru/2.0/   

 

time

http://a9.com/-/opensearch/extensions/time/1.0/

[OR19]

xs

http://www.w3.org/2001/XMLSchema-datatypes#

 

xsd

http://www.w3.org/2001/XMLSchema#

 

 

5.4       Layout and identifiers

The normative provisions in the current document are denoted by the URI http://www.opengis.net/spec/os-geojson/1.0.  All requirements and conformance classes that appear in this document are denoted by relative URIs which are relative to this base URI.

5.5       Style

This document applies the "double quote" guideline defined in [OR16]:  "If a property requires quotes, double quotes must be used. All property names must be surrounded by double quotes. Property values of type string must be surrounded by double quotes. Other value types (like boolean or number) should not be surrounded by double quotes."

5.6       Data dictionary tables

This document includes data dictionary tables with information as per sub-clause 5.5 of OGC 06-121r9 [NR6].  The following comment applies:

  • Column 1 provides the JSON property name as well as the corresponding JSONPath [OR25] expression.

 


6        Overview

This standard defines a GeoJSON-based [NR2] serialization syntax for OpenSearch Responses that conforms to a subset of [NR15] syntax constraints but does not require JSON-LD processing. While other serialization forms are possible, such alternatives are not discussed in this document.

When serialized, absent properties are represented by either (a) setting the property value to null, or (b) by omitting the property declaration altogether at the option of the publisher. These representations are semantically equivalent. If a property has an array value, the absence of any items in that array shall be represented by omitting the property entirely or by setting the value to null. The appropriate interpretation of an omitted or explicitly null value is that no value has been assigned as opposed to the view that the given value is empty or nil.

JSON does not have a formal class model. JSON objects are just sets of properties. However, the JSON encoding described in this standard features a "type" property on each JSON object.

An OpenSearch Response Document conforming to this standard is a GeoJSON document whose root value is a FeatureCollection object, and whose MIME media type corresponds to one of the media types described in chapter 9.

6.1       JavaScript Object Notation

JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format that defines a small set of formatting rules for the portable representation of structured data.  JSON is derived from the object literals of JavaScript, as defined in the ECMAScript Programming Language Standard [NR12] and can represent four primitive types (strings, numbers, boolean values, and null) and two structured types (objects and arrays).  The ordering of the members or properties of any JSON object is considered irrelevant. Even though JSON is based on a subset of the JavaScript Programming Language it is currently well supported by nearly all programming languages, including Java, Python, and C#.

The JSON format is currently described by two independent standards, RFC7159 [NR1] and ECMA-404 [NR13]. Both standards documents are consistent, but the latter defines mainly the grammatical syntax where the former provides some additional semantic and security points.

6.2       GeoJSON Format Specification

GeoJSON [NR2] is a format for encoding collections of simple geographical features along with their non-spatial attributes using JSON. GeoJSON consists of a single object representing a geometry, feature, or collection of features. The geometries supported are Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and Geometry Collections.


 

7        GeoJSON Encoding Specification

7.1       Requirements class: Core

Requirements Class

/req/core

Target type

Data instance

Dependency

HTTP 1.1

Dependency

/req/feature-collection

Dependency

/req/diagnostics

Requirement

/req/core/feature-collection

Requirement

/req/core/exceptions

Requirement 1
/req/core/feature-collection

Nominal search responses (with or without non-fatal exceptions) shall comply with the /req/feature-collection requirements class presented in section 7.2 and have an HTTP Status Code 200.

 

Requirement 2
/req/core/exceptions

In case of fatal exceptions, search responses shall comply with the req/exceptions requirements class presented in section 7.5 and have an HTTP Status Code different from 200.

If the API of an OpenSearch interface compliant with the current specification is described with an OpenAPI[4] description, then it should contain a Response Object as below.  It shows how a FeatureCollection is returned when HTTP Status Code is 200, while an ExceptionReport object is to be returned in case of exceptions.

Example 1: Extract of OpenAPI Description for a compliant interface


{
   "200": {
      "description": "Nominal search response",
      "content": {
         "application/geo+json": {
           "schema": {
              "$ref": "#/components/schemas/FeatureCollection"
           }
         }
      }
   },
   "default": {
      "description": "Unexpected fatal exception",
      "content": {
         "application/geo+json": {
           "schema": {
              "$ref": "#/components/schemas/ExceptionReport"
           }
         }
      }
   }
}

 

7.2       Requirements class: Feature Collection

 

Requirements Class

/req/feature-collection

Target type

Data instance

Dependency

/req/control-information

Dependency

/req/properties

Dependency

/req/feature

Dependency

/req/exception

Dependency

JSON [NR1]

Dependency

GeoJSON [NR2]

Dependency

http://www.opengis.net/spec/owc-geojson/1.0/core

Requirement

/req/feature-collection/properties

Requirement

/req/feature-collection/control-information

Requirement 3
/req/feature-collection/properties

A "FeatureCollection" object shall implement the properties shown in Table 5, with the value matching the type shown, and with the obligation shown.

 

Requirement 4
/req/feature-collection/control-information

A "FeatureCollection" object shall implement the properties of a ControlInformation object (Table 13).

The FeatureCollection object (originally defined in [NR2]) models a search response containing one of more search entries (Features). It may contain an optional @context property.  The @context properties are typically absent in the GeoJSON encoding and implicitly refer to the normative @context defined in Annex B.

The FeatureCollection inherits all ControlInformation properties.

Such response objects are typically used in responses from service interfaces compliant with OpenSearch [NR3], [NR4] or its extensions OGC 10-032r8 [OR19] and OGC 13-026r9 [OR20].  In the context of Earth Observation, the FeatureCollection can represent equally well the search responses of the first step and second step of a two-step search [OR20] (with different feature content for Dataset Series/Collections and Datasets/Products).  This is further explained in section 7.4 and examples of such responses are provided in appendices D1.1 and D1.2.

FeatureCollection Schema (GeoJSON)
Figure : FeatureCollection Schema (GeoJSON)

Complete description of the FeatureCollection is given in Table 5. 

Table : FeatureCollection object properties

GeoJSON Property

Definition

Data type and values

Multiplicity and use

@context

$.@context

 

Optional context property either embedding an actual context or a reference to the normative JSON-LD context defined in Annex B: "normative JSON-LD @context definition."

See Annex B.1.1.

Property

Zero or one

(optional)

type

$.type

As defined by [NR2].

Range: String

Fixed value: "FeatureCollection"

One (mandatory)

 

id

$.id

Unambiguous reference or identification of the search response (IRI).

Is defined by [NR5] §7.1.1.

Range: String (URI)

One (mandatory)

 

bbox

$.bbox

Information on the coordinate range of the geometry objects which are contained. The value is an array of length 4 (assuming the number of dimensions represented in the contained geometries is 2).  Typically south-west point and north-east point.  The value defines a shape with edges that have constant longitude and latitude. 

Is defined by [NR2].

Domain: FeatureCollection

Range: Array of Double

Zero or one (optional)

features

$.features

Collection of EarthObservation (Feature) objects as defined by [NR2].

It is possible for the Array to be empty.

Property [NR2].

Domain: FeatureCollection

Range: Array of Feature (See  Table 16)

Zero or more (optional)

properties

$.properties

Groups all other properties of the search response not covered by the properties higher in this table as imposed by [NR2]. See section 7.2.1.

Property [NR2].

Domain: FeatureCollection

Range: Properties (See Table 6)

One
(mandatory)

exceptions

$.exceptions

List of one of more non-fatal diagnostics (i.e., Exceptions).  If present, then list shall not be empty.

 

Property

Range: Array of Exception (See  Table 19)

Zero or one (optional)

The example below contains also the inherited ControlInformation properties defined in Table 13.

Example 2: FeatureCollection encoding example (GeoJSON)


{
   "type": "FeatureCollection",
   "id": "http://fedeo.esa.int/opensearch/request?startRecord=1&maximumRecords=10&platform=sentinel&httpAccept=application/geo%2Bjson",
   "bbox": [
      -180,
      -90,
      180,
      90
   ],
   "totalResults": 74,
   "startIndex": 1,
   "itemsPerPage": 10,
   "queries": {
      "request": [
         {
           "eo:platform": "sentinel",
           "count": 10,
           "startIndex": 1,
           "sru:recordSchema": "server-choice"
         }
      ]
   },
   "properties": { … },
   "features": []
}


 

Example 3: FeatureCollection encoding example (with explicit @context property)


{
   "@context": "https://www.opengis.net/spec/os-geojson/1.0",
   "type": "FeatureCollection",
   …
}


In the remainder of the document, we will not include the @context property in the GeoJSON encoding in which case it is implied as explained in Annex B.1.1.

7.2.1       Properties

 

Requirements Class

/req/properties

Target type

Data instance

Dependency

/req/category

Dependency

/req/agent

Dependency

/req/links

Dependency

/req/common-properties

Requirement

/req/properties/properties

Requirement

/req/properties/common-properties

 

Requirement 5

/req/properties/properties

A FeatureCollection "Properties" object shall implement the properties shown in Table 6, with the value matching the type shown, and with the obligation shown.

 

Requirement 6

/req/properties/common-properties

A FeatureCollection "Properties" object shall implement the properties of a CommonProperties object (Table 7).

The Properties block contains the properties and links to related objects. It contains all mandatory properties $.properties.* defined by OGC 14-055r2 [NR5]. Some optional properties defined by [NR5] can be added by implementations, but are not repeated in the table below.

Properties Schema (FeatureCollection)
Figure : Properties Schema (FeatureCollection)

Complete description of Properties is given in Table 6. 

Table : Properties object properties

JSON Property

Definition

Data type and values

Multiplicity and use

creator[5]

$.properties.creator

An entity or agent responsible for creating the response document.

Optional property in [NR5]

Domain: Properties

Range: String

One
(mandatory)

generator

$.properties.generator

 

Application responsible for creating the response document.

Optional[6] property in [NR5]

Domain: Properties

Range: Agent (See Table 9)

Zero or one
(optional)

subtitle

$.properties.subtitle

Description of the search response purpose or content.  Not empty string.

Optional property in [NR5]

Domain: Properties

Range: String

Zero or one
(optional)

lang

$.properties.lang

Language of response document.  Not empty string with an RFC-3066 code.

Mandatory property in [NR5]

Domain: Properties

Range: String

One
(mandatory)

links

$.properties.links

Refers to related and actionable resources including paging information.  See Table 10.

Mandatory property in [NR5]

Domain: Properties

Range: Links.  (See Table 10)

One (mandatory)

 

Example 4: Properties encoding example


{
 
  "properties": {
      "title": "FEDEO Clearinghouse - Search Response",
      "creator": "FEDEO Clearinghouse",
      "generator": {
           "type": "Agent",
           "title": "FEDEO Clearinghouse",
           "uri": "http://fedeo.esa.int/opensearch/readme.html",
            "version": "1.0"
      },
      "authors": [
         {
           "type": "Agent",
           "name": "FEDEO Clearinghouse",
           "email": "eohelp@eo.esa.int"
         }
      ],
      "updated": "2017-09-26T11:27:19Z",
      "lang": "en",
      "rights": "Copyright 2016-2017, European Space Agency",
      "links": { … }
   }
 
}


 

7.2.2       CommonProperties

Requirement 7

/req/common-properties

A "CommonProperties" object shall implement the properties shown in Table 7, with the value matching the type shown, and with the obligation shown.

The CommonProperties properties are inherited by the Properties block for FeatureCollections as well as Features.  They are taken from OGC 14-055r2 [NR5].

CommonProperties Schema
Figure : CommonProperties Schema

Complete description of CommonProperties is given in Table 7. 

Table : CommonProperties object properties

JSON Property

Definition

Data type and values

Multiplicity and use

type

$..properties.type

Unique identifier for the type of current element.  This property has the fixed value "Properties."

Domain: Properties

Range: String

 

Zero or one (optional)

title

$..properties.title

Title for the search response.

Mandatory property in [NR5]

Domain: Properties

Range: String

One
(mandatory)

publisher

$..properties.publisher

An entity or agent responsible for publishing the response document.

Optional property in [NR5]

Domain: Properties

Range: String

Zero or one
(optional)

authors

$..properties.authors

Entities or persons primarily responsible for making the response document.

Optional property in [NR5]

Domain: Properties

Range: Array of Agent (See Table 9)

Zero or one
(optional)

updated

$..properties.updated

Date of creation or last update of the response document (RFC3339 date).

Mandatory property in [NR5]

Domain: Properties

Range: DateTime

One
(mandatory)

date[7]

$..properties.date

Date or range of dates relevant to the response document.  String representing a date according to the ISO-8601 format.

Optional property in [NR5]

Domain: Properties

Range: String

Zero or one
(optional)

categories

$..properties.categories

Keywords related to the response document.

Optional property in [NR5]

Domain: Properties

Range: Array of Category (See Table 8)

Zero or one
(optional)

rights

$..properties.rights

 

Information about rights held in and over the response document.

Optional property in [NR5]

Domain: Properties

Range: String

Zero or one
(optional)

We refer to section 7.2.1 (FeatureCollection) and section 7.4.1 (Feature) for examples using the above properties.

7.2.3       Category

 

Requirement 8

/req/category

A "Category" object shall implement the properties defined in OGC 14-055r2 [NR5], with the value matching the type shown, and with the obligation shown.

The Category block contains the properties of a keyword and is defined in [NR5].

Category Schema
Figure : Category Schema

Complete description of Category is given in Table 8. 

Table : Category object properties

JSON Property

Definition

Data type and values

Multiplicity and use

type

$..properties/categories[*].type

Type of the element.  This property has the fixed value "Category."

Domain: Category

Range: String

Fixed value: "Category"

Zero or one (optional)

scheme

$..properties/categories[*].scheme

Identification of the code-list defining the keyword.

Defined in section 7.1.1.15 of [NR5]. 

Optional property in [NR5]

Domain: Category

Range: String (URI).

Zero or one (optional)

term

$..properties/categories[*].term

Identification of the keyword.  See also [OR22] for using of URI as string value.

Mandatory property in [NR5]

Domain: Category

Range: String

One (mandatory)

label

$..properties/categories[*].label

Human readable representation of the keyword.

Optional property in [NR5]

Domain: Category

Range: String

Zero or one (optional)

 

Example 5: Category encoding example


{
     "type":   "Category",
     "scheme": "http://www.eionet.europa.eu/gemet/",
     "term":   "http://www.eionet.europa.eu/gemet/concept/4612",
     "label":  "Land cover"
}


 

7.2.4       Agent

Requirement 9

/req/agent

An "Agent" object shall implement the properties defined in Table 9, with the value matching the type shown, and with the obligation shown.

The Agent object is a parent class which can contain the properties of a person, an organization or a software application.  It is based on foaf:Agent [OR23] and some of its properties were defined/renamed in [NR5].

Agent Schema
Figure : Agent Schema

Complete description of Agent is given in Table 9. 

Table : Agent object properties

JSON Property

Definition

Data type and values

Multiplicity and use

type

$..properties.authors[*].type

Type of the element.  This property can have one of the following fixed values "Agent," "Person," or "Organization."

Domain: Agent

Range: String

Zero or one (optional)

name

$..properties.authors[*].name

Human readable name of Person or Organization.

Defined in section 7.1.1.7 of [NR5].

Optional property in [NR5]

Domain: Agent

Range: String.

Zero or one (optional)

email

$..properties.authors[*].email

Email of Person or Organization.

Optional property in [NR5]

Domain: Agent

Range: String.

Zero or one (optional)

uri

$..properties.authors[*].uri

$.properties.generator.uri

 

URI of Agent, Person or Organization.

Optional property in [NR5]

Domain: Agent

Range: String (URI).

Zero or one (optional)

title

$.properties.generator.title

 

Title of Agent (applicable to software applications).

Optional property in Table 8 of [NR5]

Domain: Agent

Range: String.

Zero or one (optional)

version

Version of Agent (applicable to software applications).

Optional property in Table 8 of [NR5]

Domain: Agent

Range: String.

Zero or one (optional)

Example 6: Agent encoding example (author)


{
     "type":   "Agent",
     "name":   "Earth Observation Helpdesk",
     "email":  "EOHelp@esa.int",
     "uri":    "http://earth.esa.int"
}


 

Example 7: Agent encoding example (generator)


{
     "type":     "Agent",
     "title":    "CMR-OpenSearch",
     "version":  "1.76.3",
     "uri":      "https://cmr.earthdata.nasa.gov/opensearch"
}


7.2.5       Links

 

Requirements Class

/req/links

Target type

Data instance

Dependency

/req/link

Requirement

/req/links/properties

 

Requirement 10

/req/links/properties

A "Links" object shall implement the properties shown in Table 10, with the value matching the type shown, and with the obligation shown.

The Links block contains references to related resources as hypermedia links.  They include specification references and references to alternative representations of the metadata.  For the JSON encoding of the Links object, we use the property names adopted by section 7.1.2 of the GeoJSON encoding for OWS Context OGC 14-055r2 [NR5]. 

The Links object is a map containing descriptions of potential Links. The key is the "relation" as defined in [NR11] or a relation defined in [NR5].

The Link objects are grouped in arrays according to the "relation" they represent.  Implementers may add additional properties if additional "relations" need to be represented.  For consistency, all relations refer to arrays of Link objects and not to single Link objects.  This allows to have similar references with different media types included for the same relation.  The general pattern is thus  $.properties.links.relation[*].href.  It should be noted that also in the Atom OpenSearch response, multiple Atom links are allowed by the response syntax, whatever the value of the "rel" attribute.  Clients shall use the combination of "rel" and "type" attribute to select the proper Link.