Page /06/2014HMA-S Final Presentation HMA-S Final Presentation OGC ROSEO Protocol D. Marchionni, Telespazio S.p.A. June 11, 2014

Page 2HMA-S Final Presentation Summary Status of the specification Protocol overview –Interfaces –Requirements Classes –Conformance Classes & Tests

Page 3 Status of ROSEO Specification OGC OGC RESTful Encoding of Ordering Services Framework For Earth Observation Products (ROSEO) –V1.0, Publication Date: 28/04/2014 –Best Practice – What’s delivered: –The document: _OGC_RESTful_Encoding_of_Ordering_Services_Framework_For_ Earth_Observation_Products.pdf –The schema file: roseo.xsd –Many examples XML files: ROSEO generic messages; Sentinel-1, Sentinel-2, Sentinel-3 order options examples Schema file and examples not yet published on the OGC web site HMA-S Final Presentation

Page 4 Status of ROSEO Specification Document History: –Document submitted to OGC on 03/09/2013 (Esrin TC Meeting) –Motion for Electronic Vote approved on 23/09/2013 (BIDS DWG Meeting) –Electronic Vote Started on: 02/02/2014 Completed on: 18/03/2014 (2 weeks extension) Statistics: –YES: 24 –NO: 0 –Not Voted: 67 –Approved Best Practice Document HMA-S Final Presentation

Page 5 Structure of the Document The document has been prepared following the template from OGC (10-176r4_New_OGC_Document_Template_Draft) Overview of the specification is provided at §6 The complete description of the protocol, including URLs, HTTP methods and XML messages is provided at §7 Requirement Classes provided in dedicated sections: –§8: Core Requirements Class –§9: Scene Selection Requirements Class –§10: SubscriptionOrder Requirements Class Conformance Classes & tests provided in section §11: –§11.1: Core Conformance Class tests –§11.2: SceneSelection Conformance Class tests –§11.3: SubscriptionOrder Conformance Class tests HMA-S Final Presentation

Page 6 OGC ROSEO Overview ROSEO is a simplified “RESTful” version of the Ordering ICD (OGC r6) allowing accessing to Ordering functions via appropriate HTTP requests and not via SOAP calls. Ordering functions will be available to Web browsers without the need of more complex infrastructures based on SOAP. ROSEO covers in RESTful way the following HMA Ordering ICD operations: –GetCapabilities –GetOptions –Submit –GetStatus –DescribeResultAccess –Cancel HMA-S Final Presentation

Page 7 OGC ROSEO Overview ROSEO Document approach: The structure has been defined after reviewing other OGC REST specifications: WMTS, WFS REST binding change request, WCS Extension for REST binding. Conclusion: –Structured by Resources: Capabilities, OrderOptions, Order, OrderedProduct. Each resource has a dedicated section including description, URLs, supported HTTP methods, XML schema. –Addressability: each identified resource has specified URLs. –Connectdness: each resource has links (URLs) to the other related resources. –Uniform interface (see next) HMA-S Final Presentation

Page 8 OGC ROSEO Overview –Uniform interface: the operations performed on resources are only the Methods of HTTP protocol: GET for reading a resource; POST for creating a resource with ID defined by the server; PUT for creating / replacing a resource with ID defined by the client; DELETE for deleting a resource. HMA-S Final Presentation

Page 9 OGC ROSEO Overview Simplifications with respect to OSEO (OGC r6): –Removed order of products derived from a programming request. –Removed support for order quotation, function very rarely used from operational implementations of OSEO specification. –Removed support for asynchronous notifications: in fact this document focuses on Web Applications in general and on REST approach in particular, while the asynchronous message exchange is more a SOAP Web Service Oriented function. –Simplified delivery mechanism: only direct download from URL (HTTP GET) is supported HMA-S Final Presentation

Page 10 OGC ROSEO Overview Changes with respect to OSEO: –Capabilities: Removed support for notifications; Added resource URLs in Contents section (connectdness); –OrderOptions: Changed root element removing the reference to the operation (GetOptionsResponse) and putting just OrderOptions; Added URL for linking to OSDD / direct download of the product; –Order: Changed root element removing the reference to the operation (SubmitResponse / GetStatusResponse) and putting just Order; Merged definitions for Order submit and Order monitoring  Order; Added URLs for getting directly the ordered products (sort of DescribeResultAccess call); Added URLs for getting directly the order or the order items. –OrderedProduct: Very minor changes with respect to OSEO:DescribeResultAccessResponse HMA-S Final Presentation

Page 11 ROSEO Resources – Capabilities - schema HMA-S Final Presentation Capabilities resource contains metadata about the ROSEO server e.g.: service identifier, description, restrictions, service provider, supported operations, etc. ROSEO reuses the Capabilities definition provided by OSEO (OGC r6) applying a profiling for setting values compatible with ROSEO purposes.

Page 12 ROSEO Resources – Capabilities – URLs & HTTP Methods HMA-S Final Presentation HTTP MethodURLDefinitionRequest Entity Body Response Entity Body GET It returns the complete Capabilities document. Empty element instance /ServiceIdentificatio n It returns the ServiceIdentification element Empty element instance /ServiceProvider It returns the ServiceProvider element Empty element instance /Contents It returns the Contents element Empty element instance POSTNot used. PUTNot used. DELETENot used. : / /ROSEO/1.0.0

Page 13 ROSEO Resources - OrderOptions Order Options resource describes the parameters that can be set by the clients for customizing an item to order. Depending on the Satellite mission, order options can be defined either at collection level, which means that all EO Products belonging to a specified collection have the same order options, or at product level, in this case each product has potentially different order options. Two Order Options formats have been defined: –The “canonical” XML format, i.e. the XML format directly derived from OSEO; –the OSDD (Open Search Description Document) one, which reports the order options via template URL plus XML block in “canonical” format. HMA-S Final Presentation

Page 14 ROSEO Resources – OrderOptions – XML format HMA-S Final Presentation Almost identical to OSEO: order option groups; SWE Common; processing, delivery and scene selection options. Differences: –renamed tags: OrderOptions, OrderOptionGroup –Added downloadURL element

Page 15 ROSEO Resources – OrderOptions – XML example HMA-S Final Presentation Level 1,Product PRI (ASA_IMP) ESA:EECF:ENVISAT_ASA_IMx_xS:EN XI Order Options for producing ASAR IMP 1P product PRODUCT_ORDER processing Level 1B Processing Option Product Type ASA_IMP_1P Processing Option

Page 16 ROSEO Resources – OrderOptions – OSDD format Order Options in OSDD format includes: –Extension to the OSDD, via the foreign markup mechanism, for including OrderOptions resource in “canonical” XML format. As specified in OpenSearch standard, “OpenSearch Description Documents can be extended with new XML “foreign” elements and attributes provided that all of them are associated with an explicit XML namespace. Clients that encounter unrecognized foreign elements should ignore them and continue to process the document as if these elements did not appear”. –Extension to the Open Search Template URL for including OrderOptions parameters as template parameters. –The namespace of these extensions is the ROSEO one: Prefix: roseo URL: HMA-S Final Presentation

Page 17 ROSEO Resources – OrderOptions – OSDD example HMA-S Final Presentation Order Options OSDD for Order Options open false * UTF-8 UTF-8 Level 1,Product PRI (ASA_IMP) Order Options for producing ASAR IMP 1P product PRODUCT_ORDER processing Level 1B

Page 18 ROSEO Resources – OrderOptions - OSDD OrderOptions declaration (when retrieving options): it is a template parameter in a URL. Example: ? & prclv={roseo:ProcessingLevel} OrderOptions setting (when creating the request): –in case of simple order options i.e. defined using basic types like xs:int, xs:string, xs:dateTime, the setting is straightforward: just replace the Template parameter with the URL encoded value. Example: ? & prclv=1B&prdt=ASA_IMS_1P&qos=STANDARD –in case of structured order options i.e. defined using complex types like: arrays, structures and nested structures the mapping is more complex because a rule has to be defined for encoding the values of sub-parameters. For the sake of simplicity the well known and vastly used JSON syntax has been adopted. Example: ? &sbcc={“RedBand”:“band1”,“GreenBand”:“band6”,“BlueBand”:“b and12”} HMA-S Final Presentation

Page 19 ROSEO Resources – OrderOptions – URL & Methods HMA-S Final Presentation HTTP Method URLDefinitionRequest Entity Body Response Entity Body GET /options/{ID}/{format} It returns the Order Options related to the specified item (product / collection / subscription). Empty element instance. POSTNot used. PUTNot used. DELETENot used. NamesDefinitionData type and value {ID}ID of the resource to get OrderOptions:  either an EO Product  or a collection  or a subscription. xs:string (max 255 chars) URL encoded {format}Required OrderOptions format:  either canonical XML format  or OSDD format xs:string (max 255 chars) Allowed Values:  xml  osdd

Page 20 ROSEO Resources – Order Order resource is the envelope sent from the client to order a set of EO products with the selected order options or for subscribing to an existing EO Product subscription. Additionally the Order resource includes also status information reporting the current status of the order processed by the server. This resource can be accessed as a whole, including the whole order, or in parts by accessing to the various ordered items. HMA-S Final Presentation

Page 21 ROSEO Resources – Order – XML schema HMA-S Final Presentation

Page 22 ROSEO Resources – Order – URLs & HTTP Methods HMA-S Final Presentation HTTP Method URLDefinitionRequest Entity Body Response Entity Body GET /order/{order identifier} It returns the Order related to the specified order identifier. Empty element instance. /order/{order identifier}/{order item identifier} It returns the Order Item within the specified Order Empty element instance. /order?{filter expression} It returns all orders matching the filter expression. Empty element instance. POST /order It allows to submit an order to the ROSEO server. The ID of the submitted order is returned in the Response Entity Body. element instance. with the URL of the created order resource. PUTNot used DELETE /order/{order identifier} To flag as Cancelled the specified Order resource. The Order resource is still on the server. Empty

Page 23 ROSEO Resources – OrderedProducts This resource allows to physically retrieve the ordered products once they are ready for download (almost identical to OSEO:DescribeResultAccess operation) HMA-S Final Presentation

Page 24 ROSEO Resources – OrderedProducts – XML Schema HMA-S Final Presentation

Page 25 ROSEO Resources – OrderedProducts – URLs & HTTM Methods HMA-S Final Presentation HTTP Method URLDefinitionRequest Entity Body Response Entity Body GET /order/{order identifier}/file It returns all Ordered Product resources related to the specified order. Empty element instance. /order/{order identifier}/{order item identifier}/file It returns the Ordered Product resource related to the specified order item. Empty element instance. /order/{order identifier}/file?{filter expression} It returns all Ordered Product resources related to the specified order matching the specified filter. Empty element instance. POSTNot used PUTNot used DELETENot used

Page 26 ROSEO Error Handling In the event that a ROSEO server encounters an error during the access to some resource, then it returns an HTTP response including: –HTTP Status Code: 4XX for errors on the client side; 5XX for errors on server side. –HTTP Entity Body: ows:ExceptionReport element. The specific values for Status Code and ows:ExceptionReport depend on the accessed resource and performed HTTP method. There are dedicated errors for each of them. HMA-S Final Presentation

Page 27 ROSEO Requirement Classes As per OGC policy, Best Practice document must include requirements and conformance classes. HMA-S Final Presentation Requirement Classes: HMA Ordering ICD requirement classes have been reused and simplified: in fact only 3 out of 17 classes have been defined / reused: Core, which specifies the minimum behavior that all ROSEO servers shall implement. It includes the support of ordering of precisely identified Earth Observation Products. SceneSelection, which specifies the additional requirements a ROSEO server has to comply for supporting scene selection. SubscriptionOrder, which specifies the additional requirements a ROSEO server shall implement for supporting subscription orders.

Page 28 ROSEO Requirement Classes - Statistics HMA-S Final Presentation ClassResourceRequirementsTotal CoreCapabilities15 CoreOrderOptions12 CoreOrder20 CoreOrderedProduct7 TOTAL 54 SceneSelectionCapabilities0 SceneSelectionOrderOptions1 SceneSelectionOrder3 SceneSelectionOrderedProduct0 TOTAL 4 SubscriptionOrderCapabilities1 SubscriptionOrderOrderOptions2 SubscriptionOrderOrder2 SubscriptionOrderOrderedProduct2 TOTAL 7

Page 29 ROSEO Conformance Classes Conformance Classes: there is a 1:1 mapping between Requirement Classes and Conformance Classes, so we have: –Core Conformance Class: a server complying with this class provides support for all ROSEO resources and operations, but limited to ordering of precisely identified products. –SceneSelection Conformance Class: with respect to Core class it adds the support for scene selection extraction from requested products. –SubscriptionOrder Conformance Class: a server complying with this class provides full support for automatic download of subscribed products. Conformance Tests: A conformance class is implemented via a set of Conformance Tests, each testing one or more requirements of the corresponding Requirements Class. HMA-S Final Presentation

Page 30 ROSEO Conformance Classes - Statistics HMA-S Final Presentation ClassResourceRequirementsTotal CoreCapabilities5 CoreOrderOptions5 CoreOrder12 CoreOrderedProduct4 TOTAL 26 SceneSelectionCapabilities0 SceneSelectionOrderOptions1 SceneSelectionOrder3 SceneSelectionOrderedProduct0 TOTAL 4 SubscriptionOrderCapabilities1 SubscriptionOrderOrderOptions1 SubscriptionOrderOrder2 SubscriptionOrderOrderedProduct1 TOTAL 5