Publication Date: 2017-04-25
Approval Date: 2016-03-09
Posted Date: 2016-12-02
Reference number of this document: OGC 16-059
Reference URL for this document: http://www.opengis.net/doc/PER/t12-A066
Category: Public Engineering Report
Editor: Stephane Fellah
Title: Testbed-12 Semantic Portrayal, Registry and Mediation Engineering Report
COPYRIGHT
Copyright © 2017 Open Geospatial Consortium. To obtain additional rights of use, visit http://www.opengeospatial.org/
WARNING
This document is an OGC Public Engineering Report created as a deliverable of an initiative from the OGC Innovation Program (formerly OGC Interoperability Program). It is not an OGC standard and not an official position of the OGC membership. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an OGC Standard. Further, any OGC Engineering Report should not be referenced as required or mandatory technology in procurements. However, the discussions in this document could very well lead to the definition of an OGC Standard.
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.
None of the Intellectual Property or underlying information or technology may be downloaded or otherwise exported or reexported in violation of U.S. export laws and regulations. In addition, you are responsible for complying with any local laws in your jurisdiction which may impact your right to import, export or use the Intellectual Property, and you represent that you have complied with any regulations or registration procedures required by applicable law to make this license enforceable.
- 1. Introduction
- 1.1. Scope
- 1.2. Document contributor contact points
- 1.3. Future Work
- 1.3.1. SRIM and ISO 19115 mapping
- 1.3.2. SRIM Layer and Map Profile
- 1.3.3. Pubsub and federation of Registry
- 1.3.4. Web of Vocabulary Ontology and Service
- 1.3.5. Application of Shape Constraint Language (SHACL) for Linked Data
- 1.3.6. Composite Symbology and alternates renderers for Semantic Portrayal Service.
- 1.4. Foreword
- 2. References
- 3. Terms and definitions
- 4. Conventions
- 5. Overview
- 6. Status Quo & New Requirements Statement
- 7. Solutions
- 8. Semantic Registry Service
- 9. Semantic Mediation Service
- 10. Semantic Portrayal Service
- Appendix A: Semantic Registry Information Model (SRIM)
- Namespaces
- Registry Core Ontology
- Overview
- srim:Register
- srim:RegisterEntry
- srim:ItemClass
- srim:Item
- prov:Activity
- vcard:Address
- foaf:Agent
- prov:Attribution
- skos:Concept
- skos:ConceptScheme
- foaf:Document
- vcard:Email
- extent:GeographicExtent
- id:Identifier
- dct:LicenseDocument
- link:Link
- dct:Location
- gr:OpeningHoursSpecification
- org:Organizaton
- dct:PeriodOfTime
- vcard:Phone
- foaf:Project
- dct:ProvenanceStatement
- srim:Release
- dct:RightsStatement
- dct:Standard
- vcard:VCard
- Dataset Application Profile
- Service Application Profile
- Appendix B: SRIM Schema Application Profile
- Appendix C: Semantic Portrayal Ontologies
- Appendix D: Semantic Registry Service REST API v0.1
- Appendix E: Semantic Mediation Service REST API
- Appendix F: Semantic Portrayal Service REST API
- Appendix G: Revision History
- Appendix H: Bibliography
This engineering report documents the findings of the activities related to the Semantic Portrayal, Registry and Mediation components implemented during the OGC Testbed 12. This effort is a continuation of efforts initiated in the OGC Testbed 11. This report provides an analysis of the different standards considered during this effort, documents the rendering endpoints extension added to the Semantic Portrayal Service and the migration of the Portrayal metadata to the Semantic Registry, which is aligned with the DCAT REST Service API. We also discuss the integration of the CSW ebRIM for Application Schema with the Semantic Mediation Service, and document the improvements of the SPARQL Extensions, Portrayal and Semantic Mediation ontologies defined in the previous testbed.
Catalog services usually provide discovery of data and services; however, the ability to discover other related resources that can help applications better understand and render the data are not commonly found. For example, getting available styles for a layer or a feature type. In Testbed 12 it was advanced the use of W3C semantic technologies to better integrate datasets, services, schemas, schema mappings , portrayal information, and layers.
This engineering report is important to the OGC Geosemantics Domain Working Group as it advances the semantic enablement of geospatial information found in catalogs such dataset, service and portrayal metadata potentially providing a bridge between the geospatial and semantic web communities. The testbed also produced a number of ontologies for portrayal, schema management and registry.
ogcdocs, testbed-12, CSW, eb-RIM, catalogue, metadata, SPARQL, RDF, OWL, ontology, semantic web, linked data, DCAT, Portrayal, Schema, Schema Mapping, Hypermedia, REST.
This engineering report will be submitted to the Geosemantics Domain Working Group for review.
1. Introduction
Catalog services usually provide discovery of data and services; however, the ability to discover other related resources that can help applications better understand and render the data are not commonly found. For example, getting available styles for a layer or a feature type. This report captures the work performed in Testbed 12 in setting up three types of semantic services based on W3C semantic technologies to better integrate datasets, services, schemas, schema mappings , portrayal information, and layers.
-
The Semantic Registry Service allows discovering and search of geospatial assets (e.g. datasets, services, schemas, portrayal information, and layers). It is based on: the W3C Data Catalog Vocabulary (DCAT); the W3C PAV - Provenance, Authoring and Versioning ontology; and the Dublin Core Metadata Terms. The Service is based on a new developed ontology called Semantic Registry Information Model (SRIM) which generalizes the DCAT model to accommodate other types of geospatial assets. The service API is an hypermedia-driven and uses JSON-LD, Linked Data and Hypermedia Application Language (HAL).
-
The Semantic Mediation Service provides the ability to perform transformation of data from one schema to another, including chaining of transformation. It is based on a SRIM application profile for describing schemas and schema mappings. The service is an hypermedia-driven REST API.
-
The Semantic Portrayal Service provides the ability to render datasets to multiple output formats (e.g. SVG and PNG) and generate different styling encoding (e.g. SLD, MapCSS, and CartoCSS). It is based a set of portrayal ontologies for styles, symbols and graphics. It uses a SRIM profile to represent portrayal metadata.
1.1. Scope
This OGC document specifies semantic information models and REST APIs for Semantic Registry, Semantic Mediation and Semantic Portrayal Services. It introduces the Semantic Registry Information Model (SRIM), a superset of the W3C DCAT ontology. SRIM can accommodate registry items other than dcat:Dataset, such as Service description, Schema and Schema Mapping description, and Portrayal Information (Styles, Portrayal Rules, Graphics and Portrayal Catalog), Layer, and Map Context. The Semantic Registry Service is used as an integration solution for federating and unifying information produced by different OGC Catalog Service information by providing a simplified access through hypermedia-driven API, using JSON-LD, Linked Data and HAL-JSON. During the testbed, the Semantic Registry was used to store information about geospatial datasets and services, schemas and portrayal information. The Semantic Mediation Service was used to validate and perform transformation between schemas, including transformation chaining. The Semantic Portrayal Service was used as a convenience API to access Portrayal Registry information and perform rendering of geospatial data to different graphic representation (SVG, Raster and other pluggable formats).
1.2. Document contributor contact points
All questions regarding this document should be directed to the editor or the contributors:
Name | Organization |
---|---|
Stephane Fellah |
Image Matters LLC |
Gobe Hobona |
Envitia |
Richard Martell |
Galdos Inc |
Luis Bermudez |
OGC |
1.3. Future Work
1.3.1. SRIM and ISO 19115 mapping
The SRIM ontology in Testbed 12 used Dublin Core Metatada Terms. Future work to enhance SRIM is to map it with ISO 19115. Request for changes to improve the current standard ISO 19115 might also be required to better align with Linked Data. ISO 19115 should provide better use of controlled vocabularies, linked data friendly identifiers, and a better service description that enables automated access to services.
1.3.2. SRIM Layer and Map Profile
There is no standard way to describe metadata for layers and maps. While layers and maps are derived from a Dataset, they have their own specific metadata. Future work could investigate a profile description for layers and maps that extends the Registry Item and relates them to Datasets, Services and Portrayal Information. The description will be used by the Semantic Registry and Semantic Portrayal Service.
1.3.3. Pubsub and federation of Registry
In Testbed 12 , the Semantic Registry harvested information from a federation of CSW services to exercise the Semantic Registry Information Model (RIM) and the REST API. Future work could include improving the efficiency of the harvesting process by investigating the publish/subscribe protocol and versioning management of the register items in the Semantic Registry as they change over time.
1.3.4. Web of Vocabulary Ontology and Service
With the deployment of the Semantic Web and Linked Open Data, data sources have multiplied, as well as, the machine-processable controlled vocabularies that structure and constrain the interpretations of these data. These controlled vocabularies can be ontologies (RDF Schema, OWL), codelists, taxonomies, thesauri (SKOS) sometimes augmented with additional rules (SPARQL/SPIN rules, SWRL, RIF) ,and constraints (SHACL).
Vocabulary directories exist (e.g. LOV), but there is an ever-increasing demand for environments that simplify searching, editing and collaborative contributions to the vocabularies by non-experts of the Semantic Web. This creates a tension between very rich formalisms and a need to democratize participation in the life cycle of controlled vocabularies.
Vocabularies are most likely to be adopted and shared if they are made available easily. Nevertheless, despite successes in the use of SKOS for encoding vocabularies, current standards provide only low-level interfaces to vocabulary data. For example, many vocabularies are published as an RDF document for download. However, if the vocabulary is large, then the download will be commensurately large; if the user only wants to retrieve a single vocabulary term or select a few terms, this option requires processing on the client side. Alternatively, access to vocabularies is often provided at a SPARQL endpoint. SPARQL is the generic RDF query language. While it is powerful, it is also considered a low-level language similar to the relational database query language SQL and normally is only used by database administrators.
Some SKOS vocabularies are published via other HTTP interfaces. However, each implementation uses different protocols and supports a varied set of features (e.g. content-negotiation provided by the GEMET REST interface and NERC Data Grid’s Vocabulary Server SOAP interface). In some cases, one or both of human-readable formats and machine-readable formats are not available. Thus, discovery and access across vocabulary endpoints becomes challenging and ad-hoc.
There is a clear opportunity to design an API to match the SKOS and OWL vocabularies, taking advantage of the fact that most modern vocabulary content is structured using SKOS and OWL classes and predicates. This API can then be used as the basis for various higher-level vocabulary applications (NLP applications, Concept Recommender,Semantic Enricher,etc.) that can be used to enrich for example ISO 19115 metadata and other OGC services using controlled vocabularies in their metadata.
The Testbed 11 and 12 had explored the high-level description of ontologies and schemas to support semantic mediation. Future work can include investigation of the kind of metadata needed to enable search on controlled vocabularies by defining an ontology that addresses the following aspects:
-
Classification of Vocabulary types
-
Relationships to other vocabularies (extensions, imports, specialization, metadata vocabularies,etc).
-
Statistical information about vocabularies (number of concepts, concept schemes, classes, properties, instances, datatypes)
-
Schema encoding (OWL, RDF Schema, SKOS)
-
Expressiveness
-
Preferred prefix
-
Preferred Namespace uri
-
Governance metadata
-
Versioning information
Based on this ontology, we propose to define a standard REST API to search and access vocabulary metadata and their terms using best practices in REST API (hypermedia driven for example).
1.3.5. Application of Shape Constraint Language (SHACL) for Linked Data
The Semantic Registry Information Model (SRIM), developed during Testbed 12, is defined as a superset of W3C DCAT standard and encoded as an OWL ontology. However, the OWL does not capture some of the semantic integrity constraints that are necessary to validate the instance information encoded using the SRIM ontology profiles. This is not an isolated problem. The DCAT ontology, for example, defines a set of classes and properties and reuses a large number of external vocabularies such as Dublin Core, but does not provide any restrictions in the ontology. Users have to read the profile documents such as DCAT-AP or GeoDCAT-AP to know which and how properties should be applied for a given class (mandatory, recommended or optional). For example, a Dataset could have only one title per language, or contact information should have either a person name, organization name or position name, and either email or telephone number. These kind of restrictions cannot be captured with OWL, and until now it required human interpretation to implement the constraints in code.
To fill these gaps, the emerging W3C standard called Shape Constraint Language (SHACL) provides a powerful framework to define the "shape" of the graph data and the ability to define complex integrity constraints using well-defined constraints constructs defined in RDF and SPARQL/Javascript constraints. SHACL is not a replacement of RDFS/OWL, but a complementary technology that is not only very expressive but also highly extensible. While RDFS and OWL are used to define vocabularies terms (classes/properties) and their hierarchies (subclasses, subproperties), as well as the nature of the classes and properties (union, intersection, complement of classes, transitive, inverse, symmetric properties, etc.), SHACL is more appropriate to capture the property constraints (cardinality, valid values or shape values and interdependencies between them) and capable of accommodating multiple profiles by providing different shapes for the same ontology. The SHACL vocabulary is not only defined in RDF itself, but the same macro mechanisms can be used by anyone to define new high-level language elements and publish them on the web. This means that SHACL will not only lead to the reuse of data schemas but also to domain-specific constraint languages. Furthermore, SHACL can be used in conjunction with a variety of languages beside SPARQL, including JavaScript. Complex validation constraints can be expressed in JavaScript so that they can be evaluated client-side. In addition, SHACL can be used to generate validation reports for quality control with potentially suggestions to fix validation errors. Overall, SHACL is a future-proof schema language designed for the Web of Data.While SHACL is not yet a standard, there are already existing implementations using it (e.g. Topbraid) .
Future work could include investigation of the use of SHACL shapes to define application profiles, generation and data entry, data validation, and quality control of linked data information.
1.3.6. Composite Symbology and alternates renderers for Semantic Portrayal Service.
During the Testbed 11, it was introduced the portrayal ontology that focused on point-based symbology (icons for Emergency Management). Testbed 12 extended this work by providing a richer symbolizer and graphics ontology that can accommodate line and area-based symbols along with graphic attributes applicable to these symbols. Future work could extend the ontology to accommodate more complex symbology including composite symbols and symbol templates. The extended ontology will help describe more advanced symbology standards such as the family of MIL2525 symbols.
This Testbed managed to render symbol legend based on their definition, however more work is needed to develop rendering a SVG map based on the portrayal ontology. Future work can lay out the foundation to express styles that have at least the same expressiveness as SLDs. The proposed work can extend the portrayal ontology to represent composite symbols and symbol templates. Related future work can include investigation of other renderer outputs such as JSON encoding of the portrayal information, so they can be handled on the client side in HTML5 Canvas or other rendering libraries such as D3.js. Other renderers may also investigate SLD production from the RDF descriptors and investigate how unsupported features from the portrayal ontology can be supported in less expressive graphic languages than SVG, such as KML.
1.4. Foreword
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.
2. References
The following documents are referenced in 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.
-
OGC 16-062 - OGC® Testbed-12 Catalogue and SPARQL Engineering Report
-
OGC 15-058 - OGC® Testbed-11 Symbology Mediation Engineering Report
-
OGC 15-054 - OGC® Testbed-11 Implementing Linked Data and Semantically Enabling OGC Services Engineering Report
-
OGC 13-084r2, OGC I15 (ISO19115 Metadata) Extension Package of CS-W ebRIM Profile .0, 2014
-
OGC 12-168r6, OGC® Catalogue Services 3.0 - General Model, 2016
-
OGC 11-052r4, OGC GeoSPARQL- A Geographic Query Language for RDF Data, 2011
-
OGC 08-125r1, KML Standard Development Practices, Version 0.6, 2009.
-
OGC 07-147r2, KML Version 2.2.0.2008
-
OGC 07-110r4, CSW-ebRIM Registry Service ebRIM profile of CSW (.0.1), 2009
-
OGC 07-045, OGC Catalogue Services Specification 2.0.2 - ISO Metadata Application Profile (.0.0), 2007
-
OGC 07-006r1, OpenGIS Catalogue Service Implementation Specification 2.0.2, 2007
-
OGC 06-129r1, FGDC CSDGM Application Profile for CSW 2.0 (0.0.12), 2006
-
OGC 06-121r9, OGC® Web Services Common Standard
-
OGC 06-121r3, OpenGIS® Web Services Common Specification, version 1.1.0 with Corrigendum 1 2006
-
OGC 05-078r4, OpenGIS Styled Layer Descriptor Profile of the Web Map Service Implementation Specification, Version 1.1.0, 2006
-
OGC 05-077r4, OpenGIS® Symbology Encoding Implementation Specification, Version 1.1.0, 2006.
-
ISO/TS 19139:2007, Geographic information — Metadata — XML schema implementation
-
ISO 19119:2005, Geographic information — Services
-
ISO 19117:2012, Geographic information — Portrayal
-
ISO 19115:2003, Geographic information — Metadata
-
ISO 19115:2003/Cor 1:2006, Geographic information — Metadata
-
ISO 19115-1:2014, Geographic information — Metadata — Part 1: Fundamentals
-
Dublin Core Metadata Initiative, last visited 12-09-2016, available from http://dublincore.org/
-
NSG Metadata Foundation (NMF) – Part 1: Core, version 2.2, 23 September 2014 https://nsgreg.nga.mil/doc/view?i=4123
-
DGIWG 114, DGIWG Metadata Foundation (DMF),last visited 12-09-2016, available from https://portal.dgiwg.org/files/?artifact_id=9189&format=pdf
-
DoD Discovery Metadata Specification (DDMS),last visited 12-09-2016, available from https://metadata.ces.mil/dse-help/DDMS/index.htm
-
SPARQL Protocol and RDF Query Language (SPARQL),last visited 12-09-2016, available from https://www.w3.org/TR/rdf-sparql-query
-
DCAT, last visited 12-09-2016, available from https://www.w3.org/TR/vocab-dcat/
-
National System for Geospatial Intelligence Metadata Implementation Specification (NMIS) – Part 2: XML Exchange Schema
-
Project Open Data Metadata Schema v1.1 https://project-open-data.cio.gov/v1.1/schema/
-
Asset Description Metadata Schema (ADMS) https://www.w3.org/TR/vocab-adms/
-
JSON-LD 1.0 https://www.w3.org/TR/json-ld/
3. Terms and definitions
For the purposes of this report, the definitions specified in Clause 4 of the OWS Common Implementation Standard [OGC 06-121r9] and in OGC® Abstract Specification Topic TBD: TBD shall apply. In addition, the following terms and definitions apply.
3.1. feature
representation of some real world object or phenomenon
3.2. interoperability
capability to communicate, execute programs, or transfer data among various functional units in a manner that requires the user to have little or no knowledge of the unique characteristics of those units [ISO 19119]
3.3. map
pictorial representation of geographic data
3.4. model
abstraction of some aspects of a universe of discourse [ISO 19109]
3.5. ontology
a formal specification of concrete or abstract things, and the relationships among them, in a prescribed domain of knowledge [ISO/IEC 19763]
3.6. portrayal
portrayal presentation of information to humans [ISO 19117]
3.7. semantic interoperability
the aspect of interoperability that assures that the content is understood in the same way in both systems, including by those humans interacting with the systems in a given context
3.8. semantic mediation
transformation from one or more datasets into a dataset based on a different conceptual model.
3.9. symbol
a bitmap or vector image that is used to indicate an object or a particular property on a map.
3.10. symbology encoding
style description to apply to the digital features being rendered
3.11. syntactic interoperability
the aspect of interoperability that assures that there is a technical connection, i.e. that the data can be transferred between systems
4. Conventions
4.1. Abbreviated terms
-
API Application Program Interface
-
CRS Coordinate Reference System
-
CSW Catalog Services for the Web
-
DCAT Data Catalog Vocabulary
-
DCAT-AP DCAT Application Profile for Data Portals in Europe
-
DCMI Dublin Core Metadata Initiative
-
EARL Evaluation and Report Language EU European Union
-
EuroVoc Multilingual Thesaurus of the European Union
-
GEMET GEneral Multilingual Environmental Thesaurus
-
GML Geography Markup Language
-
GeoDCAT-AP Geographical extension of DCAT-AP
-
IANA Internet Assigned Numbers Authority
-
INSPIRE Infrastructure for Spatial Information in the European Community
-
ISO International Standardisation Organisation
-
JRC European Commission - Joint Research Centre MDR Metadata Registry
-
N3 Notation 3 format
-
NAL Named Authority Lists
-
OGC Open Geospatial Consortium
-
OWL Web Ontology Language
-
RDF Resource Description Framework
-
RFC Request for Comments
-
SE Symbology Encoding
-
SLD Style Layer Descriptor
-
SKOS Simple Knowledge Organization System
-
SPARQL SPARQL Protocol and RDF Query URI Uniform Resource Identifier
-
SVG Scalable Vector Graphics
-
TTL Turtle Format
-
URI Unique Resource Identifier
-
URL Uniform Resource Locator
-
URN Uniform Resource Name
-
W3C World Wide Web Consortium
-
WG Working Group
-
WKT Well Known Text
-
XML eXtensible Markup Language
-
XSLT eXtensible Stylesheet Language Transformations
5. Overview
This engineering report includes the following major sections:
-
Status Quo & New Requirements Statement: This section describes current standards and requirements for developing Semantic Registry, Semantic Mediation and Semantic Portrayal Services.
-
Solutions: This section describes the solution architectures considered by the testbed, as well as the solution architecture implemented by the testbed. We organized the reporting of the activities of this thread around the services implemented.
-
Appendix sections: These sections include semantic models and REST API of each service.
6. Status Quo & New Requirements Statement
6.1. Status Quo
6.1.1. Semantic Registry Service
Current Catalog solutions are highly dependent upon the metadata model employed for the service and data descriptions. Many of today’s service instances and data holdings are based on an ISO 19115 metadata model using XML as the exchange format. These solutions are very document-centric due to the nature of XML Document Object Model (DOM) that are used to populate these catalogs. This is often a challenge when information need to be integrated and be linked together, as it often requires to use complex protocols (XLink, CSW GetRecords operations) to circumvent the lack of global unique identifier system in XML document. This often leads to significant overhead to query across multiple documents and difficulties in reusing and linking information.
Linked Data provides a solution as information are modeled as a Directed Labeled Graph. The nodes of the graph (called resources) and edges (called properties) are identified with globally unique resource identifiers (URIs) which are assigned to a unique meaning (defined in ontologies). While best practices require to have resolvable resource URIs in Linked Data, in practice it is often not the case. Linked Data from different namespaces are usually aggregated in catalogs to facilitate search and discovery and get easy access to these resource descriptions.
The W3C has released the DCAT recommendation in early 2014. “DCAT is an RDF vocabulary designed to facilitate interoperability between data catalogs published on the Web. By using DCAT to describe datasets in data catalogs, publishers increase discoverability and enable applications easily to consume metadata from multiple catalogs. It further enables decentralized publishing of catalogs and facilitates federated dataset search across sites.” (W3C). Thus, DCAT defines a standard way to publish machine-readable metadata about a dataset. It does not make any assumptions about the format of the datasets described in a catalog.
Since then, a number of profiles of DCAT have been created and adopted such as DCAT-AP, GeoDCAT-AP, ADMS and Project Open Data (POD), mostly focused on Dataset description. There is no well-established profile that either generalize or specialize DCAT to describe services, schemas, schema mapping, vocabularies and portrayal information. The Linked Data Query Language SPARQL and its geospatial extension GeoSPARQL are now well-established standards to query Linked Data representation with geospatial information. The SPARQL query Protocol provides a partial answer to access DCAT-related data but it is not sufficient and sometimes too complex to manage and access catalog information through a REST API. CKAN API, an open-source software powering many Open Data Portal have provided recently a plugin to export data in DCAT format. As there is more and more data published in DCAT format in the community, there is a need to have a simple and standardized REST API to manage and access Linked Data describing assets managed by catalogs/registries.
Furthermore, there are many clients that access web services from web browser using protocol based on JSON written in Javascript. The direct use of RDF formats such as RDF/XML, N3, Turtle has proved that they are not easily exploitable by these clients. The new W3C standard JSON-LD is designed to address this gap. It provides the ability to describe Linked Data in JSON and vice versa by leveraging the JSON-LD Context.
The use of REST API in the web community has been widely successfull because it aligns well with web principles and enables rapid integration to build web-based application. A number of effort related to Linked Data and REST API have been conducted such as Linked Data Platform 1.0 (LDP). Recent trends in the industry see the emergence of Hypermedia formats (HAL, Hydra, Collection+JSON, Siren) to support data REST API with hypermedia controls. This introduces a level of decoupling between server and client ecosystem that could enable future evolution of APIs without breaking client ecosystem. The challenge of this testbed is to find out how REST, Hypermedia API, Linked Data representation and APIs, JSON-LD can be combined together to meet the requirements of the service.
6.1.2. Semantic Mediation Service
During the OGC Testbed 11, Image Matters LLC developed the first iteration of the Semantic Mediation Service, demonstrating the transformation of Homeland Security Working Group (HSWG) Incident Ontology to the Canadian Emergency Management Symbology (EMS) Ontology, using a rule engine. The engine was based on the Semantic Mediation Ontology and SPARQL Extension ontology expressing rules and functions of transformations between two semantic models (expressed as ontologies). The transformation from a source ontology to target ontology is called Alignment in the Semantic mediation Ontology.
While semantic transformation in the Testbed 11 was demonstrated on Linked Data representation, there is a large number of messages or documents in the current OGC standards that are based on XML representation. Their structures and syntaxes are defined with XML Schemas (GML, ISO 19139, CSGDM, NMIS). The messages often need to be converted to other XML representation based on another XML schema, typically using XSL Transformations but also by scripts. There is a need to search and discover schema definitions and existing schema mappings and finding optimal transformation paths between two schemas and perform these transformations on demand. The current OGC standards do not provide standard profile to represent schemas and schema mappings in existing OGC Catalog Services. Similary, there is no ontology or DCAT profile capable to describe semantically Schema and Schema Mappings.
There is no existing REST service that enables the search and discovery of schemas and schema mapping, performs validation, calculate optimal transformation paths and perform transformation od message from a schema to another.
6.1.3. Semantic Portrayal Service
The current OGC standards related to Portrayal (Style Layer Descriptor and Symbol Encoding) are based on XML schemas technologies. Styles definition, rules, symbolizers and graphics are defined XML document and do not provide global reusable identifier that allow the reusability and linking of portrayal information to emerge a "web of portrayal information". The standard ISO 19117 that describe portrayal information define an abstract model is mostly designed to be implemented in code but is less adequate to be used a descriptive model.
During the testbed 11, an initial set of portrayal ontologies were defined to describe semantically styles, portrayal rules, point-based symbols and graphics. The information were made accessible through a specialized REST API to be accessible by a WPS to produce SLD documents. The ontologies were limited only on point-based graphic symbols (based on PNG and True type font). The ontology was not able to model line, text and area based symbols and more advanced graphic objects and properties.
A number of attempts have been done in previous testbeds (OWS-8) to represent portrayal information in OGC catalog, but no standard profile has been defined so far and none of them has used a semantic-based approach.
There is a need to manage portrayal information in a catalog that can be related other information such as feature types, layers and taxonomies. This information can be searched and used to perform map portrayal using symbologies from different communities. The initial implementation of the Semantic Portrayal Service in the OGC Testbed 11 did not provide rendering endpoint for the symbology.
6.2. Requirements Statement
6.2.1. Semantic Registry Service
The following were the initial four general RFP requirements on the DCAT as a REST service implementation.
-
It shall be evaluated how DCAT can describe the same service and data sets in RDF as the other catalog services do using XML Schema instance documents compliant to ISO 19115.
-
Demonstrate what role DCAT can play as a heterogeneous catalog integration mechanism and as a possible simplification of the setup and use of catalogs.
-
The DCAT REST implementation shall serve as a Semantic Portrayal Catalog. The Semantic Portrayal Catalog uses an ontology model for managing styles and provides interfaces to access,create,read,update,and delete styles.
-
The DCAT as a REST service shall interface with the Schema Registry. The Schema Registry enables the discovery of XML Schemas, tranformation logic, and ontologies. These items shall be served by the DCAT as a service implementation.
From these initial high-level requirements, we derived and added the following ones:
-
Definition of Common Core Model to represent datasets, services, portrayal information, schema and schema mappings.
-
Demonstrate usage of Linked Data to link heteregeneous Registry Objects
-
Definition of REST API
-
Accomodate Web Client producing and consuming JSON.
-
Ability to evolve API by favoring decoupling between server and client
-
Manage multiple registers (Dataset,Schema, Portrayal Registers)
-
Harvesting API from multiple catalogs (CSW ebRIM, CSW ISO and more)
6.2.2. Semantic Mediation Service
The following items describes the requirements for the Semantic Mediation Service:
-
SRIM Profile for schema and schema mapping
-
Semantic Registry as a service shall interface with the Schema Registry which enables the discovery of XML Schemas, tranformation logic, and ontologies.
-
Support of XML Schema and XSL Transformation
-
Harvesting of Schema and Schema mapping from CSW ebRIM
-
Representation of schema and schema mapping using Linked Data representation
-
Definition of REST API
-
Validation of Document against Schema
-
Transformation from document from Schema A to Schema B.
-
Transformation chaining
6.2.3. Semantic Portrayal Service
The following items describes the requirements for the Semantic Mediation Service
-
Refinement Portrayal ontologies and introduction of Graphic ontology to support line, area, text and composite symbols.
-
Ability to convert of SLD to Semantic Representation
-
The Semantic Registry implementation shall serve as a Semantic Portrayal Catalog. The Semantic Portrayal Catalog uses an ontology model for managing styles and provides interfaces to access, create, read, update, and delete styles.
-
Reusability and linking to existing definition (rules, styles, graphic, symbolizers)
-
REST API for Rendering of Symbols
-
REST API for Rendering of Data using a given style
-
Ability to integrate REST API with Web-based client using JSON.
-
Ability to use portrayal on multiple data representation (Linked Data, GML, JSON).
7. Solutions
This section summarizes the solutions that have been envisioned at the beginning of the testbed, experimented with during the testbed, and that have either been discarded, or implemented, or the decision has been deferred to future activities.
7.1. Targeted Solutions
This first section addresses all solutions that have been discussed during the testbed. They include those possible solutions that have been discarded during the testbed.
7.1.1. Semantic Registry Service Targeted Solutions
The initial requirements of the testbed was to implement a DCAT REST Service that enables the access to DCAT Dataset information. However it quickly emerged that the integration of ISO 19139, NMIS, Services, Schema, Schema Mapping and Portrayal information in the service was not possible using DCAT alone, as DCAT is mostly focused on Dataset description. More generalization was needed to accommodate the different types of information objects in the future (for example Map, Layer, Vocabulary, Sensor).
The closest standard that provides an extensible framework to represent different business objects is the Electronic Business eXtensible Markup Language (ebXML) Registry Information Model (ebRIM). The ebXML registry describes objects that reside in a repository for storage and safekeeping. The information model does not deal with the actual content of the repository. All elements of the information model represent metadata (data type and data relationships) about the content stored in the repository. Such information is used to facilitate ebXML-based Business-to-Business partnerships and transactions. The registry information model provides a high-level schema for the ebXML registry. The ebRIM model has a lot overlapping constructs with the ones defined in RDF and OWL. However we found out that the definition of the classes and properties in ebRIM were often not well aligned with well-established ontologies (with the exception of Dublin Core Terms) and the best practices in the Linked Data community. ebRIM introduces a lot of verbosity to describe simple graph structure thus making very hard to build queries that naturally matches the graph structure. The Linked Data model and the standard SPARQL query language provides a more modern, decentralized approach that lowers the bar of integration and learning curve of manipulating graph-oriented data structure and seems a better match to favor reusability and linkage of information.
By analyzing the ebRIM Model and the ISO 19135 standard, we decided to create a superset of DCAT that support different types of registry items. We borrowed the notion of registers and items from both standards. The proposed solution is a new service called Semantic Registry Service that manages items described semantically and can perform semantic enrichment to better enable search and discovery for information.
Semantic Registry Information Model
We conducted a comparative analysis between different standards related to ISO 19115 profiles and DCAT-related standards (DCAT, DCAT-AP, ADMS, GeoDCAT-AP, Project Open Data). The goal of this analysis was to evaluate how well DCAT can describe the same registry objects (services, datasets, schema, schema mappings and portrayal information) in RDF as the other catalogue services do using XML Schema instance documents. The crosswalk was informed by the work done by the European Commission on developing a geospatial profile for DCAT (alias GeoDCAT). The metadata model provided by DCAT includes classes and attributes for identifying and describing catalogues, datasets, catalogue records, publishing agents and distribution. The metadata model does not include any classes or attributes for identifying or describing services. The absence of classes and attributes for service metadata, portrayal information, schemas and schema mappings in DCAT meant that several ISO service metadata elements did not have equivalent fields in DCAT to map to. To fill the gaps, we determined that a superset of DCAT was needed.
The testbed designed a Semantic Registry Information Model (SRIM) by generalizing the DCAT model to include concepts from ISO 19135, the international standard for procedures for item registration in geographic information systems and core metadata needed to express a large variety of information objects and enable better search and discovery.
Semantic Registry REST API
To facilitate the integration with web-based clients, we decided to implement a REST API that primarily supports JSON_LD output format. However we support also Linked Data Formats for item and register descriptions to enable machine to machine integration. The choice of JSON-LD was based on the fact that it provides a bridge between Linked Data and JSON.
It was also decided that the Semantic Registry REST API will implement both Level 2 and Level 3 (hypermedia REST API) on the Richardson Maturity Model so it can accommodate existing frameworks (such as AngularJS) that build REST API by constructing URL based on well defined url patterns on the client side. The Hypermedia REST API uses the Hypermedia Application Language as it has widespread adoption in the community and demonstrates well the use of hypermedia-control within JSON, and how REST API can evolve independently from the client ecosystem without breaking compatibility.
Semantic Registry Integration with Multi-Catalogs
A number of approaches were considered to integrate multiple catalogues services using different protocols and models (CSW 2.0, 3.0 and ebRIM) with the semantic registry. The different approaches considered during this testbed are described in details in Testbed-12 Catalogue and SPARQL Engineering Report[OGC 16-062].
For practical reasons and due to limited timeframe, we choose to implement a harvester service that convert records from different catalogs to the SRIM model and store them in the Semantic Registry Repository. We also decided to map only the elements of information that were relevant for search and discovery. We also chose to postpone the issue of synchronization of sources for future testbeds. Publish/Subscribe protocols will need to be investigated in the context of the semantic registr in future testbeds.
7.1.2. Semantic Mediation Service Targeted Solutions
The focus of Semantic Mediation Service for this testbed was to focus on transformation of XML document expressed in XML schema using transformation based on XSLT. One of the requirement was to define a ebRIM profile to represent Schema and Schema Mapping served by aebRIM CSW implementation and integrate it with the Semantic Registry. A review of the existing standards to represent schemas and schema mappings in a registry was conducted. Only DCAT and ADMS were found relevant but no profile were defined to accommodate the specificities of schemas and schema mappings such as source and target schema in a mapping. A review of the ebRIM model in CSW was also performed and concluded that an extension was needed to represent schema and schema mapping information in the ebRIM model.
Instead of defining a separate service that manages the schema and schema mapping separately, we decided to extend the core Semantic Registry Information Model by creating a profile to represent them semantically. The benefit of this approach is to test how well the core model can be extended and how well the Semantic Registry REST API can be reused to accomodate different domain models and convenience service APIs. We decided to implement the Semantic Mediation Service as convenience service on top of the Semantic Registy that performs validation and transformation between schemas (including finding a chain of transformation between two schemas). The Semantic Mediation Service would delegate the CRUD operations for schemas, schemas mappings to entirely to the Semantic Registry. We also decided to use a REST API that provide hypermedia controls with JSON-LD representation to lower the bar of integration with web clients, as well as getting Linked Data representation (RDF/XML, Turtle) to describe schemas and schema mappings for machine to machine support.
7.1.3. Semantic Portrayal Service Targeted Solutions
The focus of Semantic Portrayal Service for this testbed was on storing and accessing portrayal information managed by the semantic registry to support symbology mediation and rendering. Instead of defining a separate service that manages the portrayal information separately, we decided to extend the core Semantic Registry Information Model by creating a profile to represent this information semantically. The benefit of this approach is to test how well the core model can be extended and how well the Semantic Registry REST API can be reused to accommodate different domain models. We decided to implement the Semantic Portrayal Service as convenience service on top of the Semantic Registry that performs portrayal information search and rendering. The Semantic Portrayal Service would delegate the Creation/Update/Delete operations for portrayal information entirely to the Semantic Registry. We also decided to use a REST API that provide hypermedia controls with JSON-LD representation to lower the bar of integration with web clients, as well as getting Linked Data representation (RDF/XML, Turtle) to describe portrayal information for machine to machine support.
7.2. Recommendations
This second section summarizes the recommended solution(s) that will be further described in following clauses. It briefly explains the solution(s) and ideally links to relevant sections.
7.2.1. Semantic Registry Service Recommendations
Semantic Registry Information Models
To provide an extensible framework for representing information in a registry, we defined a superset of DCAT called Semantic Information Registry Model (SRIM) that defines the set of core classes and properties that can be used to represent any resources of a domain of interest. The core ontology is extended by defining application profiles. The following profiles were developed during the testbed:
-
Dataset/Service Profile: Used to describe Dataset and Services (such as the one defined in NMIS, ISO 19139). This profile is heavily based on DCAT and GeoDCAT-AP.
-
Schema Application Profile: Used to describe Schema and Schema Mapping (which extends DCAT Dataset) and used by the Semantic Mediation Service
-
Portrayal Application Profile: Used to describe Portrayal information such as Styles, Symbols, Portrayal Rules. This profile was used by the Semantic Portrayal Service.
Semantic Registry REST API
To facilitate the integration of clients with the Semantic Registry Service, we recommended the use of REST API supporting the encoding of the SRIM profiles in Linked Data format using RDF/XML, Turtle, N-Triples and JSON-LD. We also recommended to accommodate Level 2 (Resources with HTTP Verbs) and Level 3 (Hypermedia-driven) of the Richardson Maturity Model. We choose the Level 3 Hypermedia-driven API using the Hypermedia Application Language (HAL+JSON), which is gaining in popularity in the REST community.
Integration of Multi-Catalog REST API
For this testbed, the Semantic Registry service harvested metadata from different OGC Web Catalogs and converted the information to SRIM profiles encoding, but we also allowed for cascading requests to other GeoSPARQL Services that implement the profiles.
7.2.2. Semantic Mediation Service Recommendations
To facilitate the integration of clients with the Semantic Mediation Service, we recommended the use of REST API supporting the encoding of the SRIM Schema Application profile in Linked Data format using RDF/XML, Turtle, N-Triples and JSON-LD. We also recommended to accomodate Level 2 (Resources with HTTP Verbs) and Level 3 (Hypermedia-driven) of the Richardson Maturity Model. We choose the Level 3 Hypermedia-driven API using the Hypermedia Application Language (HAL+JSON), which is gaining in popularity in the REST community. To favor reusability of functionalities, all the CRUD operations of the schemas and schema mappings were implemented by the Semantic Registry. The Semantic Mediation Service was build a convenience service on top of the Semantic Registry to provide search capabilities, validation, transformation path calculation and actual transformation of document based on the path calculated from the schema mappings managed by the registry.
7.2.3. Semantic Portrayal Service Recommendations
To align better with current rendering engine implementation and current descriptive standard for Portrayal (SE, SLD), we decided to align the portrayal ontology closer to the OGC Symbol Encoding (SE)and SVG. We developed the Graphics and Symbolizer ontologies that are closely with these standards, but provide mechanism to support future extensions for more complex stlying scenarios.
The Semantic Portrayal REST Service delegates the CRUD operations on portrayal information to the Semantic Registry which implements the SRIM Portrayal Profile. The Semantic Portrayal Service implements a REST API Level 2 and Level 3 on Richardson Maturity Model. We implemented the Level 3 Hypermedia-driven API using the Hypermedia Application Language (HAL+JSON), which is gaining in popularity in the REST community. The Semantic Portrayal Service should be a convenience service build on top of the Semantic Registry containing Portrayal information by providing search capabilities and rendering points for rendering symbol glyphs for legend and map rendering of geospatial data.
8. Semantic Registry Service
8.1. Overview
Semantic metadata plays a central role in facilitating the discovery and the assessment of geospatial assets (such as datasets, services, portrayal information, schemas, maps, layers), and the integration of these assets in a specific mission. There are a number of standards, formats and APIs that provide the metadata for these assets, but in order to perform efficient search, we need to convert this information into a unified machine readable semantic representation. It is this conversion that enables the discovery of relevant resources that satisfy the mission of the end user. As we increase our understanding of the kind of metadata information needed to perform better and smarter search, we need a model that accommodates extensions over time without breaking the proposed architecture.
During this effort, a number of metadata standards were reviewed (including W3C standard DCAT, DCAT-AP, GeoDCAT-AP, ADMS, Project Open Data 1.1, Dublin Core, ISO 19115, ISO 19119) to identify the common and relevant metadata information needed for search and discovery and to identify any additional metadata information needed to describe dataset, service, portrayal, schema and schema mapping information. It quickly emerged that the DCAT standard and its different application profiles were dataset-centric and insufficient to describe the metadata for portrayal information, schemas, and services. The goal of this effort was not to define a new standard, but to leverage the existing standards to define an application profile of DCAT, with additional properties and fields, that could accommodate the schema, schema mapping, service and portrayal information needed for enhanced search and discovery while still preserving backward compatibility with existing standards.
The effort resulted in a new ontology called Semantic Registry Information Model (SRIM). SRIM is defined as a superset of DCAT and its existing application profiles (DCAT-AP, GeoDCAT-AP,ADMS). It introduces a superclass of dcat:Dataset called srim:Item and the notion of a Register (as defined in ISO 19135). The ontology draws from multiple well-established standards such as W3C DCAT, Project Open Data 1.1, DCAT-AP, GeoDCAT-AP, VCard, Dublin Core, PAV, and ISO 19115, but also addresses some gaps in the standards, such as the description of web services (for example OGC WMS, WFS), richer descriptions of geospatial data, and additional metadata to model schema, schema mapping, and portrayal information, to enable better semantic search of resources that fit with a user’s mission. SRIM enables the integration of different metadata providers (CSW, CKAN, POD WAF, WMS, and WCS) by providing a common core vocabulary to describe resources (data, services, vocabularies, map, layers, schemas, etc.) and by accommodating the specificities of each resource by leveraging the built-in extensibility mechanism of OWL. The integration is done through the use of a semantic bridge that maps the syntactic metadata (JSON, XML based) to the semantic representation based on the SRIM model. The SRIM Core model has been extended by introducing SRIM application profiles to represent other kinds of geospatial assets such as schemas and portrayal information (see sections on Semantic Mediation and Semantic Portrayal Service).
The purpose of the Semantic Registry Service (initially referred to as DCAT REST API) is to define a common interchangeable metadata format for geospatial portals and a REST protocol to access this information. In order to achieve this, SRIM defines a set of classes and properties, which are grouped into mandatory, recommended and optional. Such classes and properties aid interoperability by corresponding to information about register items and registers that is shared by many data portals. Although the Semantic Registry is designed to be independent from its actual implementation, RDF [RDF] and Linked Data [LDBOOK] are the reference technologies that perform the modeling to preserve the semantic fidelity of the conceptual model. However, we wish to facilitate a wide adoption, so we are providing an encoding based on JSON, which could be converted transparently back to a semantic model using a JSON-LD context. The JSON is closely aligned with the Project Open Data metadata schema 1.1 standard, but some extensions and modifications were made when needed to accomodate the Semantic Registry’s requirements. Preferring a decoupling of the server and client ecosystem, the Semantic Registry implementation uses a hypermedia-driven REST API using the Hypermedia Application Language (HAL) with JSON-LD as the payload. Every endpoint of the REST API also provides a Linked Data representation of the resources based on the SRIM ontology.
The following sections describe the different standards that were reviewed, the SRIM model and the implementation details on both the server and the client sides. We also explain the rationale behind some of the design decisions when applicable.
8.2. Review of existing standards
8.2.1. DCAT
DCAT is an RDF vocabulary designed to facilitate interoperability between data catalogs published on the Web. By using DCAT to describe datasets in data catalogs, publishers increase discoverability and enable their applications to easily consume metadata from multiple catalogs. It further enables decentralized publishing of catalogs and facilitates federated dataset search across sites. Aggregated DCAT metadata can serve as a manifest file to facilitate digital preservation.
8.2.2. DCAT-AP
The DCAT Application profile for data portals in Europe (DCAT-AP) is a specification based on the Data Catalogue vocabulary (DCAT) for describing public sector datasets in Europe. Its basic use case is to enable cross-data portal search for data sets and to allow public sector data to be easily searchable across borders and sectors. This can be achieved by the exchange of descriptions of datasets among data portals.
In February 2015, the ISA² programme of the European Commission has started an activity to revise the DCAT-AP, based on experience gained since its development in 2013. The outcome of this effort was the publication of DCAT-AP 1.1.
The European Data Portal is implementing the DCAT-AP as the common vocabulary for harmonizing descriptions of over 258,000 datasets harvested from 67 data portals from 34 countries. The DCAT-AP is used in the Open Data Support service initiated by the European Commission with the purpose of realizing the vision of European data portals.
8.2.3. GeoDCAT-AP
GeoDCAT-AP is defined as an extension of DCAT-AP for describing geospatial datasets, dataset series, and services. It provides an RDF syntax binding for the union of metadata elements defined in the core profile of ISO 19115:2003 and those defined in the framework of the INSPIRE Directive. Its basic use case is to make spatial datasets, data series, and services searchable on general data portals, thereby making geospatial information better searchable across borders and sectors. This can be achieved by the exchange of descriptions of datasets among data portals.
8.2.4. Asset Description Metadata Schema (ADMS)
ADMS is a profile of DCAT that is used to describe semantic assets (or just 'Assets'). These assets are defined as highly reusable metadata (e.g. xml schemata, generic data models) and reference data (e.g. code lists, taxonomies, dictionaries, vocabularies) that are used for eGovernment system development.
The ADMS model is intended to facilitate federation and co-operation. Like DCAT, ADMS has the concepts of a repository (catalog), assets within the repository that are often conceptual in nature, and accessible realizations of those assets, known as distributions. An asset may have zero or multiple distributions. As an example, a W3C namespace document can be considered to be a Semantic Asset that is typically available in multiple distributions, one or more machine processable versions and one in HTML for human consumption. An asset without any distributions is effectively a concept with no tangible realization, such as a planned output of a working group that has not yet been drafted.
ADMS is an RDF vocabulary with an RDF schema available at its namespace http://www.w3.org/ns/adms . The original ADMS specification published by the European Commission [ADMS1] includes an XML schema that also defines all of the controlled vocabularies and cardinality constraints associated with the original document.
8.2.5. Project Open Data (POD)
Project Open Data provides the implementation guide and associated resources for the Federal Executive Order on open data and data management, M-13-13 “Managing Information as an Asset,” which includes the standardized metadata schema that all CFO Act agencies are required to use to publish their enterprise data inventories.
The Project Open Data Metadata Schema is a JSON-based implementation of the W3C DCAT vocabulary. This standard is currently implemented by multiple data catalog platforms as well as state and local governments.
-
Implemented by city, state, and county governments on Data.gov/local
Typically, POD documents are often published in Web Accessible Folder (WOF) and harvested by catalogs such as data.gov. The intent of POD is to lower the bar of complexity neededto represent data information by providing guidelines and recommended metadata. This enables a better search and discovery for datasets within the US goverment.
8.2.6. ISO 19115-1
The standard ISO 19115 defines the schema required for describing geographic information and services that is encoded in XML format. It provides information about the identification, the extent, the quality, the spatial and temporal aspects, the content, the spatial reference, the portrayal, distribution, and other properties of digital geographic data and services. The standard ISO 19115 is applicable to:
-
the cataloguing of all types of resources, clearinghouse activities, and the full description of datasets and services;
-
geographic services, geographic datasets, dataset series, and individual geographic features and feature properties.
ISO 19115-1 defines:
-
mandatory and conditional metadata sections, metadata entities, and metadata elements;
-
the minimum set of metadata required to serve most metadata applications (data discovery, determining data fitness for use, data access, data transfer, and use of digital data and services);
-
optional metadata elements – to allow for a more extensive standard description of resources, if required;
-
a method for extending metadata to fit specialized needs.
Though ISO 19115-1 is applicable to digital data and services, its principles can be extended to many other types of resources such as maps, charts, and textual documents as well as non-geographic data. Certain conditional metadata elements might not apply to these other forms of data.
ISO 19139 defines the XML-based implementation for ISO 19115. ISO 19115-1:2014 [ISO19115-1] has superseded ISO 19115:2003. At the date of publication of this document, the XML-based implementation of ISO 19115-1:2014 (namely, ISO 19115-3), was finalised but not yet officially released.
8.2.7. ISO 19135
This International Standard specifies the procedures to establish, maintain, and publish registers of unique, unambiguous and permanent identifiers and meanings that are define items of geographic information. In order to accomplish this purpose, the standard specifies elements of information that are necessary to provide identification and meaning to the registered items and to manage the registration of these items.
8.2.8. Shapes Constraint Language (SHACL)
SHACL is an RDF vocabulary for describing RDF graph structures. These graph structures are captured as "shapes", which correspond to nodes in RDF graphs. These shapes identify predicates and their associated cardinalities, and datatypes. Additional constraints can be associated with shapes using SPARQL or other languages which complement SHACL. SHACL shapes can be used to communicate data structures associated with a process or interface, to generate or validate data, or to drive user interfaces.
Most applications that share data do so using prescribed data structures. While RDFS and OWL enable one to make logical assertions about the objects in some domain, SHACL (Shapes Constraint Language) describes data structures. Features of SHACL include:
-
An RDF vocabulary to define structural declarations of the property constraints associated with those shapes.
-
Complex constraints that can be expressed in extension languages like SPARQL.
-
The possibility to mix SHACL shapes with other semantic web data, as SHACL is based on RDF and is compatible with Linked Data principles
-
SHACL definitions represented in RDF which can be serialized in multiple RDF formats.
8.3. Semantic Registry Information Model (SRIM)
After analysis of the different standards, we decided to create a superset of the DCAT ontology that defines the set of classes and properties commonly used to represent any item in a register. The SRIM ontology borrows extensively from existing standards such as DCAT, GeoDCAT-AP, Dublin Core Terms, ADMS, PROV-O, PAV ontologies, and ISO 19135. In order to entice high reusability of the ontology, we decided not to enforce any restrictions in the ontology, but just define the list of properties and classes that are related through documentation (see Appendix A ). We classified the set of properties for each class as mandatory, recommended and optional.
To address different domains containing different types of items, the Core SRIM ontology is extended through application profiles. An Application Profile is defined as a set of classes and properties that extends the classes and properties defined in the Core Ontology. During this testbed, we defined three different profiles:
-
Dataset/Service Profile: Used to describe Datasets and Services (such as the one defined in NMIS, ISO 19139). This profile is heavily based on DCAT and GeoDCAT-AP.
-
Schema Application Profile: Used to describe Schemas and Schema Mappings (which extends DCAT Dataset) and used by the Semantic Mediation Service
-
Portrayal Application Profile: Used to describe Portrayal information such as Styles, Symbols, and Portrayal Rules. This profile was used by the Semantic Portrayal Service.
We anticipate that in the future, more profiles will be defined for Maps, Layers, Coverage, Imagery, Feature Catalog, and Vocabularies.
8.4. Implementations
8.4.1. Semantic Mapping to SRIM
One of the primary functions of the Semantic Registry is to support search and discovery on a large variety of items using a unified API. The Semantic Registry was tested to handle different item types including Datasets, Services, Schemas, Schema Mappings, as well as Portrayal information such as Symbols, and Portrayal Rules, and Feature Type Styles. To integrate the different encoding standards of this information, including ISO 19139, NMIS, ebRIM Schema Profile, and DCAT, a number of semantic mappers were implemented. These semantic mappers link each standard to the adequate SRIM profiles, and are used by harvesters to extract information from various sources of information.
We found out that a Linked Data encoding (DCAT) of information is easier to integrate than XML encoding because the latter requires code to explicily define the mapping between the syntactic and semantic encoding. The XML encoding of information based on XML schema tends to be more unforgiving when validating data. Another advantage of using a Linked Data approach is that it favors reusability of information that can be created and managed in a decentralized way using a common encoding framework.
One of the biggest challenges when importing data into the system is the validation of the data. The RDF model provides a powerful framework to express any property of a resource by using vocabularies from different ontologies, and it can accomodate easily to partial/incomplete information. However, this flexibility causes difficulties when attempting to validate the data. Due to the limited time for this testbed, we decided to postpone the exploration of SHACL to address this issue for the next testbed. SHACL can provide a powerful way to validate data, define the shape of graph to be processed by the service.
8.4.2. ISO 19139 Mapping Issues.
This section summarizes the list of issues found when mapping ISO 19139 to a semantic representation with data coming from a variety of CSW sources (including data.gov and Geoplatform.gov). Some of these issues come from malformed metadata and ambiguities in the ISO 19115 standards, while others come from a lack of policies from agencies that publish metadata. These issues impede interoperability and integration of information in addition to search and discovery. The usage of Linked Data instead of XML encoding will address many of these problems, but not the ones related to policies.
Identification of Resources
Issue | Identification of Resources |
---|---|
|
There is no consistent way of defining the identifiers for different resources (e.g. organizations, datasets, services, controlled vocabularies, etc.) |
|
Inability to link information and allow reusability. Resource information (concepts) are duplicated several times in different documents with variations of the same information. Updating this information is difficult to perform across all repositories. Need authoritative unambiguous references. |
|
|
|
A new policy to define URI Sets for US Government assets would provide a consistent means to make these trusted assets available for efficient, widespread discovery and re-use. This will encourage reuse and limit duplication. |
Resolvable URI
Issue | Resolvable URI |
---|---|
|
Identifiers used in the 19139 document are often internal (e.g., a primary key in a store implementation) and not accessible as unambiguous web resources. |
|
The lack of consistent machine-resolvable URIs impedes interoperability and limits automation (concepts must be grounded with unambiguous meaning for services to interpret and respond). Grounded URIs will also help humans better understand important concepts. |
|
|
|
Enables the exploration of a “unified knowledge graph” that links and describes resources. Allows users to search, discover and navigate through “Concept Space”, whereupon each concept is resolvable to a grounded (unambiguous) resource for consistent human and machine understanding. |
Multilingual Support
Issue | Multilingual Support |
---|---|
|
The current standard does not enable the support of translations of human readable text in multiple languages. Language is handled at document level, not field level. |
|
Users who do not understand the language of the information producer will not be able to discover relevant data for their tasks |
|
Opt for an implementation that natively provides multilingual support (such as Linked data) or provide guidelines for how to handle multiple languages (e.g., through JSON protocols). |
External Resource Descriptions
Issue | External Resource Descriptions |
---|---|
|
|
|
External resources modeled as a URL value inhibits the capture of additional information to help the role and meaning of the external (auxiliary) resource in the context of a given resource |
|
|
Invalid XLinks
Issue | Invalid XLinks |
---|---|
|
For some of the ISO 19139, xlink:href are not valid URLs (example #FS Lower 48) |
|
The ISO 19139 documents with invalid xlink reference do not validate with a XML schema validator. |
|
Comply to standard XML Schema for xlink:href using URLs |
|
Correct validation of ISO 19139 |
Controlled Vocabulary Management
Issue | Controlled Vocabulary Management |
---|---|
|
|
|
|
|
|
|
|
Keywords Types
Issue | Keyword Types |
---|---|
|
The list of keyword types in ISO 19115 is limited to a few categories (discipline, strata, topic, place, temporal). |
|
Inability to accommodate new types of concepts such as audience, function, subject, topic, etc.. |
|
|
|
|
Keyword Labeling Inconsistencies
Issue | Keyword Labeling Inconsistencies |
---|---|
|
In some instances, multiple labels are encoded as one keyword (e.g., 'list of all US states' is one keyword). |
|
While this is fine for doing lexical-based text search, it is not sufficient when supporting semantic search, where each concept must be grounded to a unique meaning. |
|
|
|
|
Authority for Controlled Vocabularies
Issue | Authority for Controlled Vocabularies |
---|---|
|
The ISO 19139 uses the list of topic categories in the standard ISO 19115. There is a SKOS encoding available in the European Registry located at: http://inspire.ec.europa.eu/metadata-codelist/TopicCategory. The mapping to Semantic Registry uses this URI to reference dcat:theme. |
|
If no authority are responsible of the management of controlled vocabularies, the vocabularies will not be reused and risk to be duplicated. |
|
|
|
The taxonomy is maintained by the authority that defines the standard and thus will favor reusability of the vocabularies among information producers. |
Place Name Consistency
Issue | Place Name Consistency |
---|---|
|
ISO 19139 uses keywords to define place names that reference a thesaurus that is not accessible online. There is no consistent way to define place names and resolve ambiguities. |
|
The place name can be ambiguous as there are many locations with the same name (e.g. Leesburg, FL versus Leesburg, VA) |
|
|
Contact Point
Issue | Contact Point |
---|---|
|
Contact Point in ISO 19139 is not systematically encoded in the document. The individual’s name is required in POD but is not always present in the ISO document. A generic email reference for the contact role is sometimes used. |
|
When a problem is present in the metadata, a contact point with an email should be available for expedient resolution of issues. |
|
|
|
The use of a generic role-based email for the contact will smoothly handle staff changes. |
Responsible Party without Role
Issue | Responsible Party without Role |
---|---|
|
Some responsible parties are published without a role, while the ISO standard indicates that the role is mandatory |
|
Without a role, we are unable to understand how each party relates to a data source. |
|
Enforce role in ISO 10139 for each responsible party |
|
We are able to discern how each party relates to a metadata item unambiguously. |
Responsible Party Role Encoding
Issue | Responsible Party Role Encoding |
---|---|
|
ISO 19139 outlines a well-defined taxonomy for Responsible Party roles (e.g., Publisher, etc). ISO 19139 refers to a GML document, through a URL and an Xpointer, which contains roles and many other concepts (instead of a unique concept) |
|
|
|
Encode the role taxonomy in SKOS (machine-readable) and use resolvable URIs for roles. |
|
Both machine and human can understand the unambiguous meaning of the concept. |
Organization Hierarchy
Issue | Organization Hierarchy |
---|---|
|
ISO 19139 does not provide support for the subOrganizationOf property (recommended by Project Open Data). |
|
|
|
|
|
When a resource search is performed for a given organization, the hierarchy can also be leveraged to search within suborganizations (using transitive inferencing). |
Inconsistent Usage of OnlineResource in ContactInfo
Issue | Inconsistent Usage of OnlineResource in ContactInfo |
---|---|
|
In some documents, the link to services and distributions (zip files) is put in a responsible party’s contact information (onlineResource) instead of the ServiceIdentification property or the TransferOptions in a Distribution |
|
The ContactInfo’s onlineResource property is being misused semantically. |
|
|
|
Consistency of description of services and distributions in ISO 19139, will help to make a clear distinction between service and distributed content that can be downloaded. |
Service API Standards
Issue | Service API Standards |
---|---|
|
There isn’t a consistent manner of referring to the applicable services API standard, e.g., WMS, WFS, ArcREST |
|
There is no systematic and unambiguous way to identify web services standards. The version of a standard is often not clear (OGC:WMS). Smart software, assisted by people, need to resolve spec confusion. |
|
|
|
Proper classification of service standards, disambiguation, and support of autonomous operations |
Service API Specification
Issue | Service API Specification |
---|---|
|
Absence of industry best practices or standards to refer to machine-processable API specifications (RAML, ALPS, Swagger, WSDL, etc.). |
|
|
|
Semantic Registry should produce a machine-processable API Document. |
|
Integration with the service API can be automated. |
Service Online Resource URL
Issue | Service Online Resource URL |
---|---|
|
The access URL for a service is not consistently encoded. For example in a WMS, some URIs point to a GetCapabilities endpoint, while others point to the base URL of the service |
|
There is no systematic way to access the service endpoint for a given service. Software agents have to analyze the URL to get a normalized form |
|
|
|
Systematic access to a service endpoint. |
Insufficient Service Metadata
Issue | Insufficient Service Metadata |
---|---|
|
The service description associated with a Dataset has minimal metadata, usually limited to an accessURL and format. |
|
|
|
|
|
Enable the discovery of services and invocation of services in an automated way. |
Format and OnlineResource Parity
Issue | Format and OnlineResource Parity |
---|---|
|
The ISO standard decouples Format and OnlineResource. One format can have more than one online resource URL. |
|
Having multiple URLs for a format is ambiguous and not friendly to machines or users. |
|
Enforce parity of OnlineResource with format. |
|
Proper pairing of format with online resource removes ambiguity to both machines and users. |
Download Format Versus Service
Issue | Download Format Versus Service |
---|---|
|
The ISO standard does not clearly distinguish between a download file format and a service API in a Dataset distribution. |
|
Classification of services versus downloads is difficult and not friendly to machines or users. |
|
|
|
|
Format Description
Issue | Format Description |
---|---|
|
There is no consistent way to define the format of services (OGC:WMS). Usage of mime type is not consistent in the standard, and most format descriptions are not machine readible. |
|
Inconsistency of format description makes it difficult for software agents to access data in automatically. |
|
|
|
Enables automation, content negotiation and service selections based on controlled vocabularies. |
Insufficient Map Layer Description
Issue | Insufficient Map Layer Description |
---|---|
|
The ISO standard does not provide enough information to map a dataset to a layer in a map service (WMS, ArcREST). Often multiple layers are provided by the map service and there is no deterministic way to find out which one corresponds to the dataset. |
|
Traceability from dataset to map layer is unavailable. The missing layer metadata is needed to support GeoPlatform search, discovery and proper use. |
|
|
|
Support a vastly improved layer search and map building experience. |
Data-centric Approach
Issue | Data-centric Approach |
---|---|
|
Data Schema Standardization of domain models uses a syntactic approach. Imposing this strict adherence to a standard tends to minimize heterogeneity. |
|
|
|
|
|
|
8.4.3. Semantic Registry Service
The Semantic Registry Service was designed to manage multiple registers that are capable of containing item classes from different application profiles. To support the testbed 12, we implemented three different registers:
-
Datasets and Services Register: Manages datasets and services collected from Compusult, Envitia and ESRI CSW instances
-
Schema and Schema Mapping Register: Manages schemas and schema mappings harvested from Galdos CSW Schema Registry
-
Portrayal Service Register: Manages portrayal information (styles, symbols, symbolSets, and portrayal rules)
Note
|
The partitioning of the registers was done to provide some clarity in the organization of the information. However it is possible to create a register that contains multiple application profiles. The partitioning decision is based on the business requirement of the user. |
These registers were populated by a harvester service which is integrated with the Semantic Registry Service and accessible by a hypermedia-driven REST API. The harvester service was designed to be extensible and to support multiple types of data sources, including documents extracted from a resolvable URL (Project Open Data, DCAT , ISO 19139, FDGC CSGDM documents), and advanced web services such as CSW, CKAN, Web Accessible Folder, and ESRI Web services. These plugins called harvester types describe the list of parameter descriptors needed by the harvester. An instance of a harvester type is called a harvester source and provides binding of the parameters to values. A harvester source can be triggered for harvesting manually or a given schedule, and the harvester results are returned with statistics (number of harvested objects successfully imported, number of failures) as well as the list of item identifiers. Due to limited time for implementation, only synchronous calls to harvesters are supported. Future development will handle asynchronous harvesting with on demand status reports.
The items managed by the service are stored in a NoSQL store, and are indexed and managed in a RDF store to support graph analytics and SPARQL queries.
8.4.4. Semantic Registry Service REST API
The initial objective of the testbed was to provide a DCAT REST API, which focused on the search and discovery of dcat:Datasets. However, promoting the DCAT model to the superset SRIM model also necessitated a promotion of the REST API to manage registers and harvester types and sources, and to handle more general items, including Portrayal items, Schema and Schema Mapping items.
A review of existing implementations that use DCAT datasets showed that the only consensus in how to access the information through a REST API, was the use of a SPARQL query protocol. Using an OGC filter was not considered adequate enough for complex queries of RDF data, as SPARQL provided a more compact and standardized way to query linked data. One of the main considerations when designing the REST API for the Semantic Registry was to make it accessible for web clients, which primarily operate in JSON, and to bridge the gap between linked data and JSON, the Semantic Registry uses the W3C JSON-LD. The use of JSON-LD context allows the conversion of RDF models to JSON representations and vice versa. Another objective of the API was to provide a degree of separation between the server and client implementation, to allow the API to evolve in the future without breaking client ecosystems. To achieve this, the Semantic Registry uses Hypermedia Links which provide a powerful mechanism to decouple clients and servers. This corresponds to the Level 3 REST API on the Richardson Maturity Model.
To implement a Level 3 REST API, we adopted the IETF standard candidate Hypermedia Application Language (HAL), a popular standard candidate which is widely used by JSON hypermedia REST APIs.
We also acknowledge that many web frameworks (such as AngularJS) are designed for Level 2 APIs and construct URLs on the client side to access the different states of a web application. To accomodate these frameworks, we decided to also implement a Level 2 REST API by providing well-defined URL patterns to access the artifacts of the service (registers, items,harvesters types, harvester sources) and a unique identifier for each artifact. The responses of Level 2 are identifical to those of Level 3, except for the exclusion of the hypermedia links to other states. The REST API endpoints URL pattern documented in Appendix D are considered informative only not normative.
In addition to the Level 2 and Level 3 REST APIs that will mostly be used by web clients, we added support for Linked Data API that will mainly be used by machines. Each REST endpoint of the Semantic Registry Service also supports a Linked Data output in RDF/XML, Turtle and N-Triples formats.
Furthermore, each Register endpoint also provides a GeoSPARQL endpoint that permits advanced SPARQL queries on the Linked Data representation of the items managed by each register.
8.4.5. Integration with OGC Catalog Services
To evaluate interoperability aspects in multi-catalog type environments, the testbed considered a number of solutions. Each solution involved various types of catalogue services, for example, CSW featuring ISO based metadata and OpenSearch, other CSW offering a SOAP binding, and support for DCAT using RDF.
Several architectural solutions could be used to establish a multi-catalogue environment, and four key architectural solutions were identified by the Testbed. The identified solutions differ in a variety of ways, including the entry point for client applications and the computational balance between the client application and the services.
The first solution for a multi-catalogue environment includes a client application that can query the various catalogue services directly. This requires the client application to prepare appropriate queries for each catalogue service and to collate the search results when they are returned by the services.
The second solution involves the selection of one of the catalogue services to initiate a distributed search. In this case, the client application only needs to prepare queries to send to the cascading catalogue service. Upon receiving a request from the client, the cascading catalogue service then adapts the request to forward to other catalogue services and returns responses from the other services, as well as results from its own catalogue.
The third solution involves the harvesting of metadata from one or more source catalogue services into a single target catalogue service. Harvesting is ideally conducted at a scheduled time and not when a query is received from the client. The client application can then query the target catalogue service to discover resources published by both the source and target catalogue services.
The fourth solution involves the replication of metadata between a federation of catalogue services. Replication would ideally be conducted at a scheduled time and not when a query is received from the client. The client application can then query any catalogue service to discover resources published by any catalogue service.
For this tesbed, the integration with the OGC Catalog Services was accomplished by using a Harvester Service.
Compusult CSW Integration
We integrated Compusult CSW, which serves a ISO 19139 document, using the CSW 2.0 protocol. The integration could have been done with CSW 3.0, but no open-source clients that supported the CSW 3.0 protocol were available at the time of the testbed 12. However, the Harvester configuration for CSW 3.0 would be very similar to the CSW 2.0 GetRecords operation. To map ISO 19139 to SRIM, we use a semantic mapping using the DCAT profiles. We have not found any issues validating the ISO 19139 document against their XML schema, however we found some issues in the ISO 19139 mapping (explained in Section 1.4 Implementations).
A Harvester Source for the CSW Catalog was defined and harvested on demand. The following figure shows a client displaying the harvester source for Compusult CSW:
The following snippet shows the JSON encoding of the harvester source configuration:
{
"id": "compusultCSW",
"type": "csw",
"title": "Testbed12 Compusult CSW",
"description": "Compusult CSW used for OGC Testbed 12 to harvest ISO19139 documents",
"created": "2016-10-03T22:49:27.311Z",
"modified": "2016-10-03T22:49:27.311Z",
"source": "http://ogc-testbed12.compusult.net/wes/serviceManagerCSW/csw",
"config": {
"resourceType": "http://www.isotc211.org/2005/gmd"
},
"harvestInterval": "MANUAL",
"registerId": "datasets"
}
ESRI CSW Integration
We integrated the ESRI OGC CSW, which serves ISO 19139 documents, by defining a Harvester Source with CSW 2.0. We found out that some of the ISO 19139 documents registered in the CSW were not compliant with the standards (for example missing ScopeCode in HierarchyLevel) The following snippet shows the configuration of the harvester:
{
"id": "esriCSW",
"type": "csw",
"title": "Testbed12 ESRI CSW",
"description": "ESRI CSW used for OGC Testbed 12",
"created": "2016-11-15T18:11:24.203Z",
"modified": "2016-11-15T18:11:24.203Z",
"source": "http://gptogc.esri.com/geoportal/csw",
"config": {
"resourceType": "http://www.isotc211.org/2005/gmd"
},
"harvestInterval": "MANUAL",
"registerId": "datasets"
}
Envitia CSW Integration
Envitia provided a CSW instance with a ebRIM profile. We configured the harvester to collect dataset metadata stored in an object of type: urn:ogc:def:ebRIM-ObjectType:OGC-I15::DataMetadata. The following snippet shows the configuration of the CSW Harvester:
{
"id": "envitiaCSW",
"type": "csw",
"title": "Testbed12 Envitia ebRIM CSW",
"description": "Envitia CSW used harvest ebRIM datasets records",
"created": "2016-11-15T18:11:24.236Z",
"modified": "2016-11-15T18:11:24.236Z",
"source": "http://86.188.147.99:9080/RegistryService/registry",
"config": {
"requestXML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<csw:GetRecords xmlns:env-ebrim=\"http://www.envitia.com/schemas/georegistry/ebrim-ext\"
xmlns:xmime=\"http://www.w3.org/2005/05/xmlmime\" xmlns:dct=\"http://purl.org/dc/terms/\"
xmlns:csw=\"http://www.opengis.net/cat/csw/2.0.2\" xmlns:gml=\"http://www.opengis.net/gml\"
xmlns:wrs=\"http://www.opengis.net/cat/wrs/1.0\" xmlns:ows=\"http://www.opengis.net/ows\"
xmlns:ogc=\"http://www.opengis.net/ogc\" xmlns:dc=\"http://purl.org/dc/elements/1.1/\"
xmlns:xlink=\"http://www.w3.org/1999/xlink\" service=\"CSW\" version=\"2.0.2\"
resultType=\"results\" outputSchema=\"urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0\"
startPosition=\"1\" maxRecords=\"50000\">
<csw:Query typeNames=\"wrs:ExtrinsicObject_coi\">
<csw:ElementSetName typeNames=\"coi\">full</csw:ElementSetName>
<csw:Constraint version=\"1.1.0\">
<ogc:Filter>
<ogc:PropertyIsEqualTo>
<ogc:PropertyName>$coi/@objectType</ogc:PropertyName>
<ogc:Literal>urn:ogc:def:ebRIM-ObjectType:OGC-I15::DataMetadata</ogc:Literal>
</ogc:PropertyIsEqualTo>
</ogc:Filter>
</csw:Constraint>
</csw:Query>
</csw:GetRecords>",
"resourceType": "urn:ogc:def:ebRIM-ObjectType:OGC-I15::DataMetadata"
},
"harvestInterval": "MANUAL",
"registerId": "datasets"
}
CSW ebXML Schema Registry
During the testbed, Galdos provided a CSW 2.0 instance which implemented the ebRIM profile. We extended the profile to accomodate representations of Schemas and Schema Mappings. In addition, we implemented a Semantic Mapper that converts the Schema and Schema Profile to the SRIM Schema Application Profile, and integrated it with a Semantic Registry harvester.
The following shows the Harvester Source Configuration needed to access the Schemas and Schema Mappings from the CSW:
{
"id": "galdosCSW1",
"type": "csw",
"title": "Schema Harvester from Galdos ebRIM CSW ",
"description": "This source harvests schemas stored in ebRIM Model",
"created": "2016-10-03T22:49:27.542Z",
"modified": "2016-10-03T22:49:27.542Z",
"source": "http://ows.galdosinc.com/indicio/query",
"config": {
"requestXML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<csw:GetRecords xmlns:env-ebrim=\"http://www.envitia.com/schemas/georegistry/ebrim-ext\"
xmlns:xmime=\"http://www.w3.org/2005/05/xmlmime\"
xmlns:dct=\"http://purl.org/dc/terms/\"
xmlns:csw=\"http://www.opengis.net/cat/csw/2.0.2\"
xmlns:gml=\"http://www.opengis.net/gml\"
xmlns:wrs=\"http://www.opengis.net/cat/wrs/1.0\"
xmlns:ows=\"http://www.opengis.net/ows\"
xmlns:ogc=\"http://www.opengis.net/ogc\"
xmlns:dc=\"http://purl.org/dc/elements/1.1/\"
xmlns:xlink=\"http://www.w3.org/1999/xlink\"
service=\"CSW\" version=\"2.0.2\"\r\n\tresultType=\"results\" outputSchema=\"urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0\"
startPosition=\"1\" maxRecords=\"50\">
<csw:Query typeNames=\"wrs:ExtrinsicObject\">
<csw:ElementSetName>full</csw:ElementSetName>
<csw:Constraint version=\"1.1.0\">
<ogc:Filter>
<ogc:PropertyIsEqualTo>
<ogc:PropertyName>@objectType</ogc:PropertyName>
<ogc:Literal>urn:ogc:def:ebRIM-ObjectType:OGC:Schema</ogc:Literal>
</ogc:PropertyIsEqualTo>
</ogc:Filter>
</csw:Constraint>
</csw:Query>
</csw:GetRecords>",
"resourceType": "urn:ogc:def:ebRIM-ObjectType:OGC:Schema"
},
"harvestInterval": "MANUAL",
"registerId": "schemas"
}
8.4.6. Integration with Clients
A number of clients were successfully integrated with the Semantic Registry, as illustrated by the following figure:
ESRI Semantic Registry Client
The ESRI Client provides a plugin framework to access a variety of catalog services. For this testbed, ESRI developed a plugin to access the Semantic Registry. The following figure shows the results of a search in the ESRI Semantic Registry Client:
Image Matters GeoSPARQL Semantic Registry Client
To perform a GeoSPARQL query against registers, the Semantic Registry was deployed with a GeoSPARQL client that performs SPARQL validation and execution, and displays the results in a table, pivot table, and a Google Chart if the data table structure is applicable. The following example performs a simple SPARQL query to list schema mappings with title, description, source and target schema:
HAL Browser
The HAL browser was deployed alongside the Semantic Registry to demonstrate the Hypermedia REST API implementation. The HAL browser landing page uses the entry point of the services and provides UI interactions to perform valid operations (GET,POST,PUT, DELETE) on the endpoint exposed by the hyperlinks. The UI shows the embedded items in the collection and the instance in JSON. The following figure shows the entry point of the service:
Image Matters Semantic Registry Client
To support the demonstration of the Semantic Registry, Image Matters developed a client to manage registers and harvester sources, and to perform faceted search and discovery of items. The following figure shows the search page for items with different facets:
Integration with Semantic Mediation Service
The Semantic Mediation Service used the Semantic Registry to store and search for Schemas and Schema Mappings, so we considered the Semantic Mediation as a client since it delegates its CRUD and search operations to Semantic Registry. The following figure shows a schema mapping managed by the Semantic Registry:
Integration with Semantic Portrayal Service
The Semantic Portrayal Service used the Semantic Registry to store and search for Portrayal information such as symbols, symbolizers, portrayal rules and feature type styles. We considered the Semantic Portrayal as a client since it delegates its CRUD and search operations to Semantic Registry. The following figure shows a faceted search for the portrayal register:
The following registry client snapshot shows the details of a symbol stored in the portrayal register:
9. Semantic Mediation Service
9.1. Overview
During the OGC Testbed 11, Image Matters LLC developed the first iteration of the Semantic Mediation Service, demonstrating the transformation of Homeland Security Working Group (HSWG) Incident Ontology to the Canadian Emergency Management Symbology (EMS) Ontology, using a rule engine. The engine was based on the Semantic Mediation Ontology and SPARQL Extension ontology expressing rules and functions of transformations between two semantic models (expressed as ontologies). The transformation from a source ontology to target ontology is called Alignment in the Semantic Mediation Ontology.
For this testbed, the focus was to use a Schema Registry to store information about schemas and schema mappings and to perform transformation of data represented in different schemas. The emphasis for this testbed was to use XML schemas and XSLT transformation, while still being able to accommodate the results from the previous testbed. Another objective of this testbed was to design the Semantic Mediation Service REST API and integrate it with the Semantic Registry and CSW ebRIM profile for Schema Registry.
9.2. Analysis
A review of the existing standards that can represent schemas and schema mappings in a registry was performed. Only DCAT and ADMS were found relevant but no profile were defined to accommodate the specificities of schemas and schema mappings such as source and target schema in a mapping. A review of the ebRIM model in CSW was also performed and concluded that an extension was needed to represent schema and schema mapping information in the ebRIM model.
Very often schemas falls within the scope of a well-known standard name such as GML, WFS, FDGC CSGDM, NMIS, DDMS, etc. A given standard may have multiple releases (GML 1, GML 2, GML 3 for example). Each schema release within the standard is identified with a version or unique namespace. In the case of XML schema, the namespace is different for each version. However in the case of ontologies, the namespace is the same for each release of an ontology, however they often use owl:versionIRI to distinguish each release document. Each of this release can have multiple distributions: the schema document (XML Schema for example), its specification (reference to a PDF document for example). In the case of ontologies, a release may be composed of multiple encoding of the same ontology such as RDF, TTL, or N-TRIPLES. The following diagram shows how the FGDC CSDGM can be encoded using this three-layer approach.
The DCAT model uses a two-layer approach (Dataset/Distribution). The SRIM Model introduces the concept of the srim:Release to accommodate the three-layer view to organization data information. The need of introducing the concept of Release was identified in the ADMS discussion forum, but no solution was proposed. We decided not to enforce one view over another, however we introduced the concept of release to enable users to better represent the organization of their information into three layers (Solution-Release-Distribution).
To enable the integration of Schema and Schema Mapping in the Semantic Registry, we developed during this testbed a SRIM profile for Schema and Schema Mapping. In addition, an ebRIM-Model extension was defined to register Schema and Schema Mapping in CSW ebRIM catalog. The following sections provides an overview of the models, REST API and integration work performed under this task. More details about the SRIM Application Profile and the Semantic Mediation REST API can be found in Appendix B and E.
9.3. SRIM Schema Application Profile
The SRIM Schema Application Profile is defined as an extension of the SRIM Core Model. A Schema and SchemaMapping have been defined a subclass of dcat:Dataset, thus inherits any of its properties when applicable. To enable a better search and discovery of schemas and schema mappings in a registry, we recommend to leverage the metadata recommended by the SRIM and DCAT models, and if possible organize the information into the three-layer approach describe in the previous section when applicable.
The overview of the model is shown in the figure below.
The following example shows how the NMIS v.2.2 XML Schema is encoded in Turtle Format.
@prefix schema: <http://www.opengis.net/ont/testbed12/srim/profile/schema#> .
@prefix adms: <http://www.w3.org/TR/vocab-adms/#> .
@prefix pav: <http://purl.org/pav/> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix org: <http://www.w3.org/ns/org#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2>
a schema:Schema ;
dct:alternative "NGA.STND.0018_2.2" ;
dct:description "An XML encoding of the NMIS logical model (Part 1) that is conformant to ISO 19139 and the XML Data Encoding Specification for Information Security Marking Metadata (DES.ISM.XML.V9)" ;
dct:publisher <http://wwww.nga.mil> ;
dct:title "National System for Geospatial Intelligence Metadata Implementation Specification (NMIS) - Part 2: XML Exchange Schema, Version 2.2." ;
pav:version "2.2" ; (1)
schema:namespace <http://metadata.ces.mil/dse/ns/GSIP/5.0/nas> ; (2)
schema:schemaLanguage <http://www.w3.org/TR/xmlschema-1/> ; (3)
skos:altLabel "NGA.STND.0018_2.2" ;
dcat:distribution
[ a dcat:Distribution ; (4)
dct:description "NGA.STND.0018_2.2 XML schema encoding" ;
dct:title "NGA.STND.0018_2.2 XML Schema" ;
dcat:accessURL <http://schemas.opengis.net/iso/19139/20070417/gmd/gmd.xsd> ; (5)
dcat:mediaType "application/xml" (6)
adms:representationTechnique <http://purl.org/adms/representationtechnique/XMLSchema> (7)
] ;
dcat:keyword "Metadata" , "Geospatial" , "NMIS" , "NGA" , "ISO 19139 Profile" , "XML Schema" .
<http://wwww.nga.mil>
a org:Organization ;
foaf:name "National Geospatial Intelligence Agency (NGA)" .
-
pav:version to denote the version of the schema
-
schema:namespace refers to the namespace URI associated with the schema
-
schema:schemaLanguage refers to a URL uniquely defining the Schema Language used to define the Schema encoding.
-
dcat:Distribution is used to define information to access the Schema
-
dcat:accessURL refers to the endpoint to download the schema
-
The dct:mediaType refers to the mime type of the XML Schema document (application/xml)
-
To distiguish which "flavor" of XML is used, we use the property adms:representationTechnique to refer to the XML Schema url standard.
The following schema shows the definition of the Department of Defense Discovery Metadata Specification (DDMS), Version 2.0".
@prefix schema: <http://www.opengis.net/ont/testbed12/srim/profile/schema#> .
@prefix adms: <http://www.w3.org/TR/vocab-adms/#> .
@prefix pav: <http://purl.org/pav/> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix org: <http://www.w3.org/ns/org#> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<http://metadata.dod.mil/mdr/ns/DDMS/2.0>
a schema:Schema ;
dct:description "Defines discovery metadata elements for resources posted to community and organizational shared spaces" ;
dct:publisher <http://wwww.nga.mil> ;
dct:title "Department of Defense Discovery Metadata Specification (DDMS), Version 2.0" ;
pav:version "2012-07-13" ;
schema:namespace <http://metadata.dod.mil/mdr/ns/DDMS/2.0/> ;
schema:schemaLanguage <http://www.w3.org/TR/xmlschema-1/> ;
dcat:distribution [ a dcat:Distribution ;
dct:description "" ;
dct:title "DDMS Schema file (version 2012-07-13)" ;
adms:representationTechnique <http://purl.org/adms/representationtechnique/XMLSchema> ;
dcat:accessURL <http://schemas.opengis.net/iso/19139/20070417/gmd/gmd.xsd> ;
dcat:mediaType "application/xml"
] ;
dcat:keyword "Metadata" , "Geospatial" , "DDMS" , "XML Schema" .
<http://wwww.nga.mil>
a org:Organization ;
foaf:name "National Geospatial Intelligence Agency (NGA)" .
The following example illustrates a schema mapping between NMIS 2.2 and DDMS 2.0 is defined in Turtle format.
@prefix schema: <http://www.opengis.net/ont/testbed12/srim/profile/schema#> .
@prefix adms: <http://www.w3.org/TR/vocab-adms/#> .
@prefix pav: <http://purl.org/pav/> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix org: <http://www.w3.org/ns/org#> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<http://www.opengis.net/testbed12/schemas#MNIS2DDMS>
a schema:SchemaMapping ;
dct:description "Schema Mapping from NMIS 2.2 to DDMS" ;
dct:publisher <http://wwww.nga.mil> ;
dct:title "NMIS 2.2 to DDMS SchemaMapping" ;
pav:version "2013-12-2" ; (1)
schema:mappingLanguage <https://www.w3.org/TR/xslt20/> ; (2)
schema:sourceSchema <http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2> ; (3)
schema:targetSchema <http://metadata.dod.mil/mdr/ns/DDMS/2.0> ; (4)
dcat:distribution [ a dcat:Distribution ; (5)
dct:description "NGA.STND.0018_2.2 to DDMS SchemaMapping XSLT Distribution" ;
dct:title "NMIS to DDMS SchemaMapping XSLT Distribution" ;
dcat:accessURL <http://ows.galdosinc.com:80/indicio/query?request=GetRepositoryItem&service=CSW-ebRIM&id=urn:uuid:38ffef44-e1ee-4856-8812-d8b82da497a4> ; (6)
dcat:mediaType "application/xml"; (7)
adms:representationTechnique <http://purl.org/adms/representationtechnique/XSLT20> ; (8)
] ;
dcat:keyword "XSLT" , "Geospatial" , "NMIS" , "DDMS" , "NAS" .
<http://wwww.nga.mil>
a org:Organization ;
foaf:name "National Geospatial Intelligence Agency (NGA)" .
-
pav:version to denote the version of the schema mapping
-
schema:mappingLanguage refers to a URL uniquely defining the Schema Mapping Language used to define the Schema Mapping encoding (XSLT in this case)
-
schema:sourceSchema refers to the source schema that this schema mapping accepts (NMIS v2.2 schema defined above).
-
schema:targetSchema refers to the target schema that this schema mapping maps to (DDMS v2.0 schema defined above).
-
dcat:Distribution is used to define information to access the XSLT document
-
dcat:accessURL refers to the endpoint to download the XSLT document
-
The dcat:mediaType refers to the mime type of the XSLT document (application/xml)
-
To distinguish which "flavor" of XML is used, we use the property adms:representationTechnique to refer to the XSLT url standard.
During the testbed, we identified the need to standardize the taxonomies for Schema Language (RIF, RELAX-NG,EXPRESS, Avro Schema, JSON Schema, OWL, RDFS,…), Schema Mapping (RIF,XSLT, Programming language,…) and representation techniques (XSLT, RIF, XML Schema,..). ADMS provides a taxonomy for Representation techniques on the concept scheme: http://purl.org/adms/representationtechnique/. The top concepts of the taxonomy are shown below in RDF/XML format (note that it is missing XSLT, which we added in our example (<http://purl.org/adms/representationtechnique/XSLT20>)
<!-- http://purl.org/adms/representationtechnique/1.0 -->
<owl:NamedIndividual rdf:about="http://purl.org/adms/representationtechnique/1.0">
<rdf:type rdf:resource="&skos;ConceptScheme"/>
<rdfs:label xml:lang="en">Representation Technique</rdfs:label>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/Archimate"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/BPMN"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/CommonLogic"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/DTD"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/Datalog"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/Diagram"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/Genericode"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/HumanLanguage"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/IDEF"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/KIF"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/OWL"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/Prolog"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/RDFSchema"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/RIF"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/RelaxNG"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/RuleML"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/SBVR"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/SKOS"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/SPARQL"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/SPIN"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/SWRL"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/Schematron"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/TopicMaps"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/UML"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/WSDL"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/WSMO"/>
<skos:hasTopConcept rdf:resource="http://purl.org/adms/representationtechnique/XMLSchema"/>
</owl:NamedIndividual>
The DCAT model allows multiple dcat:Distribution for a dcat:Dataset. Thus it is possible that a schema:Schema and schema:SchemaMapping (which are subclasses of dcat:Dataset) to have multiple distributions of the same schema or schema mapping using different representation techniques (for example a schema can be represented in RelaxNG or XML Schema). The use of adms:representationTechnique helps clients to select the distribution that they can support. This makes the schema:schemaLanguage and is less useful. On the other hand, having one distribution per Schema and SchemaMapping will make the use schema:schemaLanguage and schema:mappingLanguage more useful for search. There is however a thin line to distinguish the semantic of schema:schemaLanguage and schema:mappingLanguage with adms:representationTechnique.
To facilitate the integration with web clients that uses JSON, we defined a JSON-LD context to map isomorphically the RDF model to JSON-LD. This means that a JSON-LD document can be transformed to RDF model using the JSON-LD context and vice-versa. This explains the reason we use URI reference extensively in our JSON-LD representation, instead of internal value of particular system (ideally these URIs should be resolvable). This is default encoding used by the semantic registry and semantic mediation service.
The following example is the equivalent encoding of the NMISSchema in JSON-LD
{
"id": "66dcd67e36e93540bc77e4710fd749ad",
"uri": "http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2",
"type": "schema:Schema",
"register": [
"schemas"
],
"title": "National System for Geospatial Intelligence Metadata Implementation Specification (NMIS) - Part 2: XML Exchange Schema, Version 2.2.",
"description": "An XML encoding of the NMIS logical model (Part 1) that is conformant to ISO 19139 and the XML Data Encoding Specification for Information Security Marking Metadata (DES.ISM.XML.V9)",
"alternative": "NGA.STND.0018_2.2",
"created": "2016-10-10T16:09:58.704Z",
"publisher": [{
"name": "National Geospatial Intelligence Agency (NGA)",
"uri": "http://wwww.nga.mil",
"type": "org:Organization"
}],
"keyword": [
"ISO 19139 Profile",
"XML Schema",
"Metadata",
"NGA",
"Geospatial",
"NMIS"
],
"namespace": "http://metadata.ces.mil/dse/ns/GSIP/5.0/nas",
"schemaLanguage": "http://www.w3.org/TR/xmlschema-1/",
"distribution": [{
"title": "NGA.STND.0018_2.2 XML Schema",
"description": "NGA.STND.0018_2.2 XML schema encoding",
"accessURL": "http://schemas.opengis.net/iso/19139/20070417/gmd/gmd.xsd",
"type": "dcat:Distribution",
"representationTechnique": "http://purl.org/adms/representationtechnique/XMLSchema"
}]
}
The following example is the equivalent encoding of the NMISSchema in JSON-LD
{
"id": "2ddf2633f660b1d6f281a989faeec3e6",
"uri": "http://www.opengis.net/testbed12/schemas#MNIS2DDMS",
"type": "schema:SchemaMapping",
"register": [
"schemas"
],
"title": "NMIS 2.2 to DDMS SchemaMapping",
"description": "Schema Mapping from NMIS 2.2 to DDMS",
"created": "2016-10-10T16:10:06.490Z",
"publisher": [{
"name": "National Geospatial Intelligence Agency (NGA)",
"uri": "http://wwww.nga.mil",
"type": "org:Organization"
}],
"keyword": [
"NAS",
"DDMS",
"XSLT",
"Geospatial",
"NMIS"
],
"sourceSchema": "http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2",
"targetSchema": "http://metadata.dod.mil/mdr/ns/DDMS/2.0",
"mappingLanguage": "https://www.w3.org/TR/xslt20/",
"distribution": [{
"title": "NMIS to DDMS SchemaMapping XSLT Distribution",
"description": "NGA.STND.0018_2.2 to DDMS SchemaMapping XSLT Distribution",
"accessURL": "http://ows.galdosinc.com:80/indicio/query?request=GetRepositoryItem&service=CSW-ebRIM&id=urn:uuid:38ffef44-e1ee-4856-8812-d8b82da497a4",
"type": "dcat:Distribution",
"representationTechnique": "http://purl.org/adms/representationtechnique/XSLT20"
}]
}
The full description of the SRIM Schema Application Profile is described in the Appendix [SRIMSchemaProfile]
9.4. Schema Registry CSW-ebRIM profile
The CSW-ebRIM schema registry provided by Galdos is based on the CSW-ebRIM profile (OGC 07-110r4, OGC 07-144r4), with the following extensions:
-
Schema (object type): A formal description of a model expressed using some schema language (e.g. XML Schema, RELAX NG, EXPRESS)
-
Script (object type): An executable sequence of statements written in some scripting language (e.g. XSLT, Python, shell script); it is usually interpreted rather than compiled.
-
SchemaMapping (association type): A relation between two Schema objects that specifies how data structured under the source schema are to be transformed into data structured under the target schema.
-
ImplementedBy (association type): A relation between a SchemaMapping and a Script or Service that implements the mapping in some executable way.
-
Ontology (object type): A formal description of interrelated concepts and their properties that apply to a particular domain of discourse.
Two schemas may be related by a SchemaMapping association, which may be implemented by some script resource (or perhaps by a processing service). The following diagram illustrates the essential concepts.
The Schema and Script resources are shown above with repository items managed by the registry. It is also possible to register resources available elsewhere and link to an external representation using an ExternalLink.
9.5. Implementations
9.5.1. Integration of Galdos Schema Registry with Semantic Registry
To perform the integration of the Galdos Schema Registry with the Semantic Registry, two harvester types were defined in the Semantic Registry:
-
Schema Harvester: harvest schema from CSW-ebRIM schema profile to SRIM Schema Profile.
-
Schema Mapping Harvester: harvest schema mappings from CSW-ebRIM schema profile to SRIM Schema Profile.
Both harvester types were used to defined two harvester sources to the Galdos Schema Registry instance to convert the ebRIM profile to its semantic representation in Semantic Registry (thus can be query by its REST API or SPARQL endpoint). The following figure shows the configuration of the Schema Harvester in the Semantic Registry Client.
The request filter constrains the namespace names of both the source and target schemas. The response includes a tuple (conveyed by the rim:RegistryObjectList element) that contains the matching schema mapping and an implementation (a Script or a Service object). In this case it’s a Script (media type: "application/xslt+xml") resource that can be downloaded from the registry using the URI given by wrs:repositoryItemRef/@xlink:href (a link to the repository item).
<GetRecords xmlns="http://www.opengis.net/cat/csw/2.0.2" xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0" xmlns:wrs="http://www.opengis.net/cat/wrs/1.0" xmlns:ogc="http://www.opengis.net/ogc" service="CSW" version="2.0.2" maxRecords="10" resultType="results"> <Query typeNames="rim:Association_a1_a2 wrs:ExtrinsicObject_e1_e2 rim:RegistryObject_r1"> <ElementSetName typeNames="a1 r1">full</ElementSetName> <Constraint version="1.1.0"> <ogc:Filter> <ogc:And> <ogc:PropertyIsEqualTo> <ogc:PropertyName>$a1/@associationType</ogc:PropertyName> <ogc:Literal>urn:ogc:def:ebRIM-AssociationType:OGC:SchemaMapping</ogc:Literal> </ogc:PropertyIsEqualTo> <ogc:PropertyIsEqualTo> <ogc:PropertyName>$a1/@sourceObject</ogc:PropertyName> <ogc:PropertyName>$e1/@id</ogc:PropertyName> </ogc:PropertyIsEqualTo> <ogc:PropertyIsEqualTo> <ogc:PropertyName>$e1/@objectType</ogc:PropertyName> <ogc:Literal>urn:ogc:def:ebRIM-ObjectType:OGC:Schema</ogc:Literal> </ogc:PropertyIsEqualTo> <ogc:PropertyIsEqualTo> <ogc:PropertyName>$e1/rim:Slot[@name='http://www.opengis.net/cat/wrs/1.0/namespaceName']/rim:ValueList/rim:Value</ogc:PropertyName> <ogc:Literal>http://metadata.ces.mil/dse/ns/GSIP/5.0/nas</ogc:Literal> </ogc:PropertyIsEqualTo> <ogc:PropertyIsEqualTo> <ogc:PropertyName>$a1/@targetObject</ogc:PropertyName> <ogc:PropertyName>$e2/@id</ogc:PropertyName> </ogc:PropertyIsEqualTo> <ogc:PropertyIsEqualTo> <ogc:PropertyName>$e2/@objectType</ogc:PropertyName> <ogc:Literal>urn:ogc:def:ebRIM-ObjectType:OGC:Schema</ogc:Literal> </ogc:PropertyIsEqualTo> <ogc:PropertyIsEqualTo> <ogc:PropertyName>$e2/rim:Slot[@name='http://www.opengis.net/cat/wrs/1.0/namespaceName']/rim:ValueList/rim:Value</ogc:PropertyName> <ogc:Literal>http://metadata.dod.mil/mdr/ns/DDMS/2.0/</ogc:Literal> </ogc:PropertyIsEqualTo> <ogc:PropertyIsEqualTo> <ogc:PropertyName>$a2/@associationType</ogc:PropertyName> <ogc:Literal>urn:ogc:def:ebRIM-AssociationType:OGC:ImplementedBy</ogc:Literal> </ogc:PropertyIsEqualTo> <ogc:PropertyIsEqualTo> <ogc:PropertyName>$a2/@sourceObject</ogc:PropertyName> <ogc:PropertyName>$a1/@id</ogc:PropertyName> </ogc:PropertyIsEqualTo> <ogc:PropertyIsEqualTo> <ogc:PropertyName>$a2/@targetObject</ogc:PropertyName> <ogc:PropertyName>$r1/@id</ogc:PropertyName> </ogc:PropertyIsEqualTo> </ogc:And> </ogc:Filter> </Constraint> </Query> </GetRecords>
<GetRecordsResponse xmlns='http://www.opengis.net/cat/csw/2.0.2' version='2.0.2'> <SearchStatus timestamp='2016-10-13T16:23:04Z'></SearchStatus> <SearchResults numberOfRecordsMatched='1' elementSet='full' numberOfRecordsReturned='1' nextRecord='0'> <RegistryObjectList xmlns='urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0'> <rim:Association xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0" xmlns:wrs="http://www.opengis.net/cat/wrs/1.0" xmlns:csw="http://www.opengis.net/cat/csw/2.0.2" xmlns:xlink="http://www.w3.org/1999/xlink" id="urn:uuid:2c14d651-dc53-4367-91bc-62ca7db6f40c" lid="urn:uuid:2c14d651-dc53-4367-91bc-62ca7db6f40c" objectType="urn:oasis:names:tc:ebxml-regrep:ObjectType:RegistryObject:Association" status="urn:oasis:names:tc:ebxml-regrep:StatusType:Submitted" associationType="urn:ogc:def:ebRIM-AssociationType:OGC:SchemaMapping" sourceObject="urn:uuid:566ff231-e768-41de-bb26-e0def91ceb9b" targetObject="urn:uuid:02200156-4271-4d52-a2e1-47d268680aa7"> <rim:VersionInfo versionName="20160902T192540Z"/> </rim:Association> <wrs:ExtrinsicObject xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0" xmlns:wrs="http://www.opengis.net/cat/wrs/1.0" xmlns:csw="http://www.opengis.net/cat/csw/2.0.2" xmlns:xlink="http://www.w3.org/1999/xlink" id="urn:uuid:38ffef44-e1ee-4856-8812-d8b82da497a4" lid="urn:uuid:38ffef44-e1ee-4856-8812-d8b82da497a4" objectType="urn:ogc:def:ebRIM-ObjectType:OGC:Script" status="urn:oasis:names:tc:ebxml-regrep:StatusType:Submitted" mimeType="application/xslt+xml"> <rim:Slot name="http://www.opengis.net/cat/wrs/1.0/scriptLanguage"> <rim:ValueList> <rim:Value>https://www.w3.org/TR/xslt20/</rim:Value> </rim:ValueList> </rim:Slot> <rim:Slot name="http://purl.org/dc/terms/date" slotType="urn:oasis:names:tc:ebxml-regrep:DataType:Date"> <rim:ValueList> <rim:Value>2016-05-11</rim:Value> </rim:ValueList> </rim:Slot> <rim:Slot name="http://purl.org/dc/terms/extent"> <rim:ValueList> <rim:Value>59 kB</rim:Value> </rim:ValueList> </rim:Slot> <rim:Name> <rim:LocalizedString xml:lang="en" charset="UTF-8" value="NMFtoDDMS2-20160511.xsl"/> </rim:Name> <rim:Description> <rim:LocalizedString xml:lang="en" charset="UTF-8" value="XSLT v2 stylesheet that accepts an NMIS 2.2 document as input and generates a DDMS 2.0 compliant document as output."/> </rim:Description> <rim:VersionInfo versionName="20160902T192540Z"/> <rim:ContentVersionInfo versionName="20160902T192540Z"/> <wrs:repositoryItemRef xlink:type="simple" xlink:href="http://ows.galdosinc.com:80/indicio/query?request=GetRepositoryItem&service=CSW-ebRIM&id=urn:uuid:38ffef44-e1ee-4856-8812-d8b82da497a4"/> </wrs:ExtrinsicObject> </RegistryObjectList> </SearchResults> </GetRecordsResponse>
The conversion to the JSON-LD representation of the SchemaMapping is represented below.
{ "id": "1854365d6a9ea7a88788e3380ff4d770", "uri": "urn:uuid:2c14d651-dc53-4367-91bc-62ca7db6f40c", "type": "schema:SchemaMapping", "register": [ "schemas" ], "created": "2016-10-10T16:21:20.237Z", "sourceSchema": "urn:uuid:566ff231-e768-41de-bb26-e0def91ceb9b", "targetSchema": "urn:uuid:02200156-4271-4d52-a2e1-47d268680aa7", "distribution": [{ "uri": "urn:uuid:38ffef44-e1ee-4856-8812-d8b82da497a4", "type": "dcat:Distribution", "title": "NMFtoDDMS2-20160511.xsl", "titleMap": { "en": "NMFtoDDMS2-20160511.xsl" }, "description": "XSLT v2 stylesheet that accepts an NMIS 2.2 document as input and generates a DDMS 2.0 compliant document as output.", "descriptionMap": { "en": "XSLT v2 stylesheet that accepts an NMIS 2.2 document as input and generates a DDMS 2.0 compliant document as output." }, "representationTechnique": "https://www.w3.org/TR/xslt20/" }] }
In addition to the harvesting of the ebRIM Schema Registry, we populated the registry with additional schemas with more details attributes using RDF encoding and JSON-LD representation (using the Semantic Registry REST API to post items).
9.5.2. Semantic Mediation Service
The Semantic Mediation Service was build as convenience REST API that uses the Semantic Registry to search and discover schemas and schema mappings, but provides additional functionalities such as schema validation and schema transformation.
The REST API of the Semantic Mediation Registry was designed on the same criteria than the Semantic Registry REST API. It supports Level 2 and Level 3 REST API. The Level 3 is implemented with HAL. The payload of the REST API is using JSON that can be converted to Linked Data using a JSON-LD context referred at the entry point of the service. The REST API provides endpoints to search schemas and schema mappings, perform validation and transformation between two schemas. The detailed description of the REST API can be found in Appendix E.
10. Semantic Portrayal Service
10.1. Overview
The initial implementation of the Semantic Portrayal Service during the OGC Testbed 11 focused on defining the styles, portrayal rules, point-based symbols and graphics to enable a Web Processing Service (WPS) to produce a SLD document. The initial ontology was heavily based in ISO 19117 Geographic Information-Portrayal standard. However during of our implementation of style renderers and development of the graphic ontology, we concluded the ISO 19117 was mostly designed for runtime implementation (for example use of portrayal function) than adapted for a declarative approach. The OGC SE standard provides a declarative approach based on XML encoding that is better aligned with modern renderer API (Java Canvas, HTML Canvas, SVG, MapCSS, ESRI Map Renderer, etc.).
We try to take the best ideas for different standards to define our portrayal ontologies and modularize them in such as way that it favors reusability
10.2. Review of symbology graphic formats
A number of existing standards related to Portrayal were considered during this testbed to come out with the portrayal ontologies.
10.2.1. Symbol Encoding (SE)
This Specification defines Symbology Encoding, an XML language for styling information that can be applied to digital Feature and Coverage data. This document is together with the Styled Layer Descriptor Profile for the Web Map Service Implementation Specification the direct follow-up of Styled Layer Descriptor Implementation Specification 1.0.0. The old specification document was split up into two documents to allow the parts that are not specific to WMS to be reused by other service specifications.
10.2.2. OGC Style Layer Descriptors (SLD)
The OpenGIS® Styled Layer Descriptor (SLD) Profile of the OpenGIS® Web Map Service (WMS) Encoding Standard [http://www.opengeospatial.org/standards/wms] defines an encoding that extends the WMS standard to allow user-defined symbolization and coloring of geographic feature and coverage data. SLD addresses the need for users and software to be able to control the visual portrayal of the geospatial data. The ability to define styling rules requires a styling language that the client and server can both understand. The OpenGIS® Symbology Encoding Standard (SE) provides this language, while the SLD profile of WMS enables application of SE to WMS layers using extensions of WMS operations. Additionally, SLD defines an operation for standardized access to legend symbols.
10.2.3. Scalable Vector Graphics (SVG)
SVG has been in development since 1999 by a group of companies within the W3C after the competing standards Precision Graphics Markup Language (PGML, developed from Adobe’s PostScript) and Vector Markup Language (VML, developed from Microsoft’s RTF) were submitted to W3C in 1998. SVG drew on experience from the designs of both those formats. SVG allows three types of graphic objects: vector graphics, raster graphics, and text. Graphical objects, including PNG and JPEG raster images, can be grouped, styled, transformed, and composited into previously rendered objects.
10.2.4. ISO 19117
ISO 19117:2012 specifies a conceptual schema for describing symbols, portrayal functions that map geospatial features to symbols, and the collection of symbols and portrayal functions into portrayal catalogues. This conceptual schema can be used in the design of portrayal systems. It allows feature data to be separate from portrayal data, permitting data to be portrayed in a dataset independent manner.
10.2.5. KML
KML is an XML language focused on geographic visualization, including annotation of maps and images. Geographic visualization includes not only the presentation of graphical data on the globe, but also the control of the user’s navigation in the sense of where to go and where to look.
From this perspective, KML is complementary to most of the key existing OGC standards including GML (Geography Markup Language), WFS (Web Feature Service) and WMS (Web Map Service). Currently, KML 2.2 utilizes certain geometry elements derived from GML 2.1.2. These elements include point, line string, linear ring, and polygon.
10.3. Portrayal Ontologies
The Portrayal Ontologies specify a conceptual model for portrayal data, in particular symbols and portrayal rules. Portrayal rules associate features with symbols for the portrayal of the features on maps and other display media. These ontologies include classes, attributes and associations that provide a common conceptual framework that specifies the structure of and interrelationships between feature types, portrayal rules and symbols. It separates the content of the data from the portrayal of that data to allow the data to be portrayed in a manner independent of the dataset. The graphic description is intended to be format independent but convertible to any target formats (SVG, KML). The ontologies are derived from concepts found in existing portrayal specifications (ISO 19117, OGC Symbology Encoding and Styled Layer Descriptor Profile of WMS, SVG, KML).
To favor reusability, the Portrayal ontologies are decomposed into four microtheories:
-
Style ontology: defines the concept of Style and portrayal rules.
-
Symbol ontology: defines the concept of SymbolSet and Symbol and structural definition of Symbol components.
-
Symbolizer ontology: defines the concepts of Symbolizers defining instructions to render data as graphics.
-
Graphic Ontology: defines graphic elements including graphic objects and attributes.
10.3.1. Style Microtheory
During this testbed, we extended the Style Microtheory designed during the testbed 11 to accomodate contextual information such as the scale range of application of a portrayal and better modeling schema used by the style rules by leveraging the work done for the semantic mediation and schema registry.
The previous Style ontology developed in Testbed 11 uses specialized properties (sparqlCondition, rifCondition,ogcFiterCondition). For this testbed, we modified the ontology to provide an extensible mechanism to express constraint in any language (which is more aligned with the CSW approach). We introduce the concept of style:Constraint. We also added introduce the minScaleDenominator and maxScaleDenominator as property of the RuleCondition,as they are common properties for style.
The details of the style microtheory are described in the Appendix C.
10.3.2. Symbol Microtheory
The Symbology Microtheory is an ontology that defines the conceptual model for defining SymbolSet and Symbol. A Symbol provides a graphic representation that denotes a concept (typically a feature type with specific properties). For this testbed, we extended the Symbol Microtheory designed during the testbed 11 to accomodate text, line, and area based symbol components and formalized binding between data properties (geometry) and graphic properties. The notion of Symbol is missing in the OGC SE standard as symbolizers are directly related to a FeatureTypeStyle. Introducing this intermediary Symbol Concept favors reusability of the symbols between different FeatureTypeStyle but also linking symbols to other concepts such as SymbolSet, concepts that they denote, allowing better search and mediation of symbols between different domains.
Due to the lack of time, we only address symbols that are not parameterizable (except their binding to geometry property). Future extension may address this requirement by introducing subclass of Symbol, such as SymbolTemplate (as introduced in ISO 19117).
10.3.3. Symbolizer Ontology
The Symbolizer ontology defines a set of symbolizers (also called renderers) that defines instructions for rendering data to graphic representation. The ontology is built on top of the Graphic Ontology which defines graphic objects and properties. Symbolizers are referred by symbol:Symbol to describe how conceptual symbol are rendered into graphics. The details of the ontology is described in Appendix C. This section describes an overview of the microtheory, examples and rationale of some of the design decisions.
The OGC Symbology Encoding defines a number of symbolizers that uses SVG parameters defines a key value pair. While this mechanism provides extensibility by accomodate future key value pairs, there is no schema allowing to know which keys are valid for a given symbolizer. We decided to move away from the approach used in the previous testbed 11, based on the ISO 19117 model which introduces symbol definition, symbol components and graphics. We found out that the ISO 19117 was not adequate to represented as semantic descriptive model. The ISO 19117 is more geared toward an implementation which can use function to calculate positioning of symbol components. We decided to align out model more toward main stream map renderer and descriptive standards such as SVG. === Symbolizer Hierarchy
The top concept of the Symbolizer ontology is Symbolizer. A Symbolizer describes how a feature is to appear on a map. The Symbolizer describes not just the shape that should appear but also how visual variables are defined using graphical properties such as color and opacity. A Symbolizer is obtained by specifying one of subclass of Symbolizer and then supplying parameters to override its default behavior. The hierarchy of symbolizer is illustrated in the following figure.
Note that the hierarchy uses similar terminology than the OGC SE specification, except that it introduces an additional class called CompositeSymbolizer that defines a composition of symbolizers applied in a given order and using a composition operation (default is source over). This version of the ontology mostly focused on rendering of feature (vector) data, and is not addressing in depth the Raster Symbolizer, which is introduced as a placeholder for future extension. Other extensions of symbolizer may be defined down the road for more specialized use-cases such as complex symbologies that are difficult to express with graphic descriptors (example MIL 2525 symbology).
Point Symbolizer
A PointSymbolizer is defined as a Symbolizer that is used to draw a “graphic” at a point. If the geometry associated with the PointSymbolizer is not a point, such as a line, polygon, raster, a representative point of the geometry (typically centroid) should be used.
Line Symbolizer
A LineSymbolizer is a Symbolizer that is used to render a "stroke" along a linear geometry type such as string of line segments. Geometry types other than inherently linear types can also be used. If a point geometry is used, it should be interpreted as a line of “epsilon” (arbitrarily small) length with a horizontal orientation centered on the point, and should be rendered with two end caps. If a "area" geometry (for example polygon) is used, then its closed outline is used as the line string (with no end caps). If a raster geometry is used, its coverage-area outline is used for the line, rendered with no end caps.
Polygon Symbolizer
A PolygonSymbolizer is a Symbolizer that is used to render the area enclosed by a polygon. If a polygon has “holes,” then they are not filled, but the borders around the holes are stroked in the usual way. “Islands” within holes are filled and stroked, and so on. If a point geometry is referenced instead of a polygon, then a small, square, ortho-normal polygon should be constructed for rendering. If a line is referenced, then the line (string) is closed for filling (only) by connecting its end point to its start point, any line crossings are corrected in some way, and only the original line is stroked. If a raster geometry is used, then the raster-coverage area is used as the polygon.
Text Symbolizer
A TextSymbolizer is a Symbolizer that is used to render text.
Raster Symbolizer
A RasterSymbolizer is a Symbolizer that is used to render raster. This symbolizer has been introduced as a placeholder for future extensions, as this testbed was primarely focused on symbolization of vector data.
Composite Symbolizer
A CompositeSymbolizer is a symbolizer composed of a list of Symbolizers that applied in a given order using a given composition operation. Default composition operation is src-over composition.
Property
A Property defines a reference to a property name or property path for a given type pointing to a value used for rendering. It can be a simple property name, a XPath (using slash separator) for XML Data Model, a json path (using dot notation) for JSON data model or a SPARQL path for Linked Data Model. The introduction of the class is intended to be a generalization of the ogc:PropertyName and se:Geometry to accomodate different data models (Linked Data, JSON, XML Model).
Graphics Microtheory
The bulk of the effort for this thread was to flush out the Graphics Ontology used to describe the graphic elements of the symbols. The scope of the ontology is to be able to capture the graphic objects and properties expressed in different graphic encodings such as OGC Symbol Encoding (SE), SVG, KML. While the previous Testbed 11 was focused on Point symbology, and introduced PointIcon pointing to external graphics such as Font (HSWG incident symbols) and image-based symbols (Emergency Management Symbology), this effort extended the graphic ontology by addressing the following requirements:
-
Point symbology
-
Line symbology
-
Area symbology
-
Text symbology
-
Graphic properties compatible with SVG
-
Graphic Symbol defined by geometries and marks.
-
Binding of graphic properties to data properties.
-
Rendering to SVG and PNG
The rationale to introduce a Graphic Ontology is to provide a vocabulary describing graphic elements (objects and properties) and encodes them in an independent way. The use of ontology language such as OWL provide a powerful mechanism to express the semantic, classification, relationships and constraints of the graphic elements. The use of Linked data encoding for the graphics enable to build a "Web of Graphics" that could be referenced by other resources and the decentralized distribution of graphics information on the web, favoring reusability of graphics and linkage to application that can go beyond styling application.
Before starting the encoding of the Graphics Ontology, we perform an analysis of the different graphics standards related to the map symbology and graphic drawing in general. We identified the common graphic elements (objects and properties). The following standards were considered in the analysis:
-
OGC Style Layer Description (SLD)
-
OGC Symbology Encoding (SE)
-
Scalable Vector Graphics (SVG)
-
OGC Keyhole Markup Language (KML)
-
ISO 19117 Geographic Information- Portrayal
Our analysis results find out that SVG and CSS graphic elements were the most commonly used among the different standards. SVG provides also the richest set of graphic elements that can accommodate abroad range of graphic drawing applications. We identified a initial list of graphic elements that are the most commonly used for map drawing and we formalized an new ontology as the existing graphic ontologies such as VISO or SVG Graphics Ontology were not adequate as they were too generic or over engineered for map portrayal.
To model the graphic elements of the ontology, we try to use a model that is close to the way graphic properties are defined in CSS and SVG. For example to encode color, the preferred way is to use literal with a CSSColorLiteral datatype that uses the same syntax than CSS and SVG. Similarly length can be expressed using different unit of measures (percent, cm, mm). Instead of introducing a concept of Length and Unit of Measure that could be very verbose, we choose to use introduce a datatype LengthType that is based on the SVG and CSS syntax.
The graphic:GraphicElement concept is the top concept of the Graphic Ontology. It is aligned with the definition introduced in ISO 19117. The range of the graphic:graphicContent property of a symbol:SymbolComponent is a graphic:GraphicElement. A GraphicElement has two subclasses: graphic:GraphicObject and graphic:GraphicProperty (also aligned with the ISO 19117 model).
A graphic:GraphicObject is defined as a graphic:GraphicElement that can be drawn such as a graphic shape (oval, ellipse, rectangle, path) , Raster, Glyphs (text and graphic symbols) .
An overview of the Graphic Ontology hierarchy is shown below:
Graphic properties represents attributes that are used to modify the appearance of the graphic objects such as its size, orientation, color, outline stroke, fill pattern, fonts, font size. Several standards such as ISO 19117 and OGC SE encodes graphic properties as name/value pairs, which provide flexibility for future extensions with new names, but they do not provide any semantic to the name and make it hard to define the adequate restrictions of graphic properties on specific graphic objects. It is also prone to misinterpretation by implementers. The use of ontology provides a clear semantic for each property and relationships to other properties. For example, graphic:font-color, graphic:stroke-color and graphic:fill-color are defined as subproperties of graphic:color. The graphic ontology introduces two ways to model graphic properties. The first one is by defining subproperties of the datatype property graphic:graphicProperty (for example graphic:stroke-width, graphic:stroke-color, graphic:font-size). The second way is by defining a subclass of the graphic:GraphicProperty such as graphic:Stroke, graphic:Color, graphic:Font, graphic:Fill, which are often used as reusable containers for of multiple graphic properties. More details about the Graphic Ontology can be found in Appendix C.
Semantic Portrayal Service REST API
The Semantic Portrayal Service implementation is accessible through a hypermedia-driven REST-based API to access style information (styles, ruleset, symbolsets, symbols) from the service.
-
Hypermedia-driven REST API using Hypermedia Application Language JSON (HAL-JSON) (Level 3 on Richardson Maturity Model)
-
JSON API (Level 2 on Richardson Maturity Model)
-
Linked Data API.
The style information are encoded in following representations: RDF/XML, Turtle, N-Triples, JSON-LD and HAL-JSON. The Semantic Portrayal Service REST API is described in more details in Appendix F.
Appendix A: Semantic Registry Information Model (SRIM)
In the following sections, classes and properties are grouped under headings ‘mandatory’, ‘recommended’ and ‘optional’. These terms have the following meaning.
-
Mandatory class: a receiver of data MUST be able to process information about instances of the class; a sender of data MUST provide information about instances of the class.
-
Recommended class: a sender of data SHOULD provide information about instances of the class; a sender of data MUST provide information about instances of the class, if such information is available; a receiver of data MUST be able to process information about instances of the class.
-
Optional class: a receiver MUST be able to process information about instances of the class; a sender MAY provide the information but is not obliged to do so.
-
Mandatory property: a receiver MUST be able to process the information for that property; a sender MUST provide the information for that property.
-
Recommended property: a receiver MUST be able to process the information for that property; a sender SHOULD provide the information for that property if it is available.
-
Optional property: a receiver MUST be able to process the information for that property; a sender MAY provide the information for that property but is not obliged to do so.
The meaning of the terms MUST, MUST NOT, SHOULD and MAY in this section and in the following sections are as defined in RFC 2119.
In the given context, the term "processing" means that receivers must accept incoming data and transparently provide these data to applications and services. It does neither imply nor prescribe what applications and services finally do with the data (parse, convert, store, make searchable, display to users, etc.).
Classes are classified as Mandatory if they appear as the range of one of the mandatory properties.
Namespaces
Prefix |
Namespace URI |
Schema & Documentation |
adms |
||
dcat |
||
dct |
||
extent |
N/A |
|
foaf |
||
geosparql |
||
gr |
||
id |
N/A |
|
link |
N/A |
|
locn |
||
org |
||
prov |
||
rdf |
Resource Description Framework (RDF): Concepts and Abstract Syntax |
|
rdfs |
||
schema |
||
skos |
||
srim |
N/A |
|
vcard |
||
xsd |
Registry Core Ontology
Overview
To facilitate the integration of geospatial assets (such as datasets, services, portrayal information, schemas, maps, layers), semantic metadata plays a central role in facilitating the discovery and the assessment of fitness of use of these resources for a specific mission. There are a number of standards, formats, and APIs that provide metadata, but in order to perform efficient search we need to convert this information into a unified, machine-readable semantic representation that enables the discovery of relevant resources to satisfy the mission of the end user. As an understanding of the kind of metadata information being searched is needed to perform a better and smarter search, we need a model that accommodates extensions over time without breaking the proposed architecture.
A number of metadata standards have been reviewed, including the W3C standard DCAT, DCAT-AP, GeoDCAT-AP, ADMS, Project Open Data 1.1, Dublin Core, ISO 19115, and ISO 19119 to identify the common and relevant metadata information needed for search and discovery, but also to identify the gaps to address the requirements to describe dataset, service, portrayal information, schema and schema mapping. It quickly emerged that the DCAT standard and its different application profiles were data-centric and insufficient to describe metadata for portrayal information,schemas and services. The goal of this effort was not to define a new standard, but to leverage existing standards to define an application profile of DCAT that could accomodate the schema, service, and portrayal information needed for discovery and filling the gaps by introducing additional properties and fields, all while preserving backward compatibility with existing standards.
This analysis resulted in a new application profile of DCAT called the Semantic Registry Information Model (SRIM) Core Model, referred to later in the document as SRIM Core. SRIM Core is defined as a superset of DCAT and its existing application profiles (DCAT-AP, GeoDCAT-AP, ADMS), and it introduces a superclass of dcat:Dataset called srim:Item. The ontology draws from multiple well-established standards such as W3C, DCAT, Project Open Data 1.1, DCAT-AP, GeoDCAT-AP, VCard, Dublin Core, and PAV, but also addresses some gaps in the standards, such as descriptions of web services (for example OGC WMS, WFS), richer description for geospatial data, additional metadata to model schema, schema mapping, and portrayal information in order to enable better semantic search of resources that fit the mission of the users. The ontology draws also on the geospatial metadata standard ISO 19115. SRIM enables the integration of different metadata providers (CSW, CKAN, POD WAF, WMS, WCS) by providing a common core vocabulary to describe resources (data, services, vocabularies, map, layers, schemas, etc) and accommodate the specificities of each source by leveraging the built-in extensibility mechanism in OWL. The integration is done through the use of a semantic bridge that maps the syntactic metadata (JSON, XML based) to a semantic representation based on the SRIM model. The SRIM Core model has been extended by introducing the SRIM application profile to represent other kinds of geospatial assets such as schemas and portrayal information (see section for Semantic Mediation and Semantic Portrayal Service).
The purpose of SRIM Core is to define a common interchange metadata format for geospatial portals. In order to achieve this, SRIM defines a set of classes and properties, grouped into mandatory, recommended, and optional. Such classes and properties correspond to information on register items and registers that are shared by many data portals, aiding interoperability. Although SRIM is designed to be independent from its actual implementation, RDF [RDF] and Linked Data [LDBOOK] are the reference technologies used to perform the modeling and preserve the semantic fidelity of the conceptual model. However, to facilitate a wide adoption, we provide an encoding based on JSON, which could be converted transparently back to a semantic model using a JSON-LD context. The JSON has been closely aligned with the Project Open Data metadata schema 1.1 standard. However, to accommodate some of the requirements needed by the Semantic Registry Service, we extended, and sometimes modified, the model when needed.
The following part of SRIM Core shows how DCAT is related to the srim:Item. Note the model introduces the first class concept of srim:Service, which inherits from dcat:Distribution and srim:Item, so that we can have a rich description of services that can be leveraged by an agent for the discovery of services and better access to services.
The following sections describe the details of every class in the model.
srim:Register
A Register is a curated collection of metadata about items stored in a repository (registry) used to enable search and discovery of resources. This class is used as a container to exchange registers of resources between registries. The Register is made accessible through a Registry Service.
Rationale: The items are usually organized in catalogs (a synonym of registers). To favor reusability of the registry service for multiple purpose, catalogs can be specialized for a specific register item type (datasets, services, layers, maps, features, vocabularies, etc..) and conform to a specific application profile, or be organized for a specific domain or organization.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
alias |
srim:alias |
rdfs:Literal |
An alias name for the Register that can be used in queries |
1 |
title |
dct:title |
rdfs:Literal |
This property contains a name given to the register. This property can be repeated for parallel language versions of the name. |
1..n |
description |
dct:description |
rdfs:Literal |
This property contains a free-text account of the Register. This property can be repeated for parallel language versions of the description. |
1..n |
publisher |
dct:publisher |
This property refers to an entity (organization) responsible for making the register available |
1 |
|
items |
srim:item |
This property links the Register with a Resource that is part of the register. This can be modeled as hyperlink in implementation. |
1..n |
|
item Class |
srim:itemClass |
This property links the Register to the item classes it supports. |
1..n |
|
application profile |
dct:conformsTo |
URL |
This property refers to an Application Profile that the Register metadata conforms to. |
1 |
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the Register (effort should done to make it resolvable) |
0..1 |
landing page |
dcat:landingPage |
URL |
This property refers to a web page that acts as the main page for the Register. |
0..1 |
language |
dct:language |
URL |
This property refers to a language used in the textual metadata describing titles, descriptions, etc. of the resources in the Register. This property can be repeated if the metadata is provided in multiple languages. |
0..n |
license |
dct:license |
This property refers to the license under which the Register can be used or reused. |
0..1 |
|
release date |
dct:issued |
rdfs:Literal typed as xsd:date or xsd:dateTime |
This property contains the date of formal issuance (e.g., publication) of the Register. |
0..1 |
update/modification date |
dct:modified |
rdfs:Literal typed as xsd:date or xsd:dateTime |
This property contains the most recent date on which the Register was modified. |
0..1 |
theme taxonomies |
dcat:themeTaxonomy |
This property refers to a knowledge organization system (KOS) used to classify the Register’s items |
0..n |
Optional properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
entry |
srim:entry |
This property refers to a RegisterEntry that is part of the Register. This can be modeled as hyperlink in implementation. |
0..n |
|
rights |
dct:rights |
This property refers to a statement that specifies rights associated with the Register |
0..n |
|
spatial/geographic |
dct:spatial |
This property refers to a geographical area covered by the Register |
0..n |
|
temporal |
dct:temporal |
This property refers to a temporal period covered by the register |
0..n |
srim:RegisterEntry
A RegisterEntry provides a description of an Item entry in the Register. The register entry is used to capture provenance information and the status of the register item within the register. This is mostly a supporting class that is used for the administration of the resources within the registry.
Rationale: The Register Entry is a concept needed only for an administrative purpose to manage and understand the lifecycle of the register items. This object is not typically used by end users searching for data (that is why the RegisterEntry is made optional in our model). The Register entry corresponds to the CatalogRecord in DCAT.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
dct:identifier |
string |
Unique identifier identifying the registry entry within the register |
1 |
primaryTopic |
foaf:primaryTopic |
This property links the RegisterEntry to the Item described in the entry. This can be modeled as hyperlink in implementation. |
1 |
|
listing date |
dct:issued |
rdfs:Literal typed as xsd:date or xsd:dateTime |
This property contains the date on which the description of the resource was included in the Register |
1 |
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
update/modification date |
dct:modified |
rdfs:Literal typed as xsd:date or xsd:dateTime |
This property contains the most recent date on which the RegisterEntry was changed or modified. |
0..1 |
provenance |
prov:wasGeneratedBy |
This property refers to provenance information how this registry entry was generated (by harvester, by human editing, by tools). |
0..1 |
|
status |
srim:status |
string |
This property refers to the type of the latest revision of a resource’s entry in the Register. It MUST take one of the values "retired", "superseded", or "valid" depending on whether this latest revision is a result of a creation, update or deprecation. Additional states may be needed for the registry adjudication process such as "proposed" or "unaccepted". |
0..1 |
title |
dct:title |
rdfs:Literal |
This property contains a name given to the RegisterEntry for parallel language versions of the name |
0..n |
description |
dct:description |
rdfs:Literal |
This property contains a free-text account of the entry. This property can be repeated for parallel language versions of the description. |
0..n |
Optional properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the register entry (effort should done to make it resolvable) |
0..1 |
language |
dct:language |
URL |
This property refers to a language used in the textual metadata describing titles, descriptions, etc. of the resources. This property can be repeated if the metadata is provided in multiple languages |
0..n |
source metadata |
dct:source |
rdfs:Resource |
This property refers to the original metadata that was used in creating metadata for the register item |
0..1 |
previous version |
pav:previousVersion |
Previous version of this entry |
0..1 |
srim:ItemClass
An ItemClass represents a class of item that can be managed by the registry service. Examples of item classes are datasets, maps, layers, services, vocabularies, styles, and application schemas. Each Item must be associated with one ItemClass. The Registry Service should provide the list of item classes that are supported, and a register can manage one or more item classes.
Rationale: In order to validate the type of item submitted to the register, we need to classify the register items according to a well-known domain class. The ItemClass corresponds to an ontology class in the RDF world.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the item class, which should be defined by an OWL ontology. Effort should be made to make the URL resolvable. |
1 |
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
name |
srim:name |
rdfs:Literal |
This property defines a unique name for the item class that could be used in API. This property is required for the registry service implementation |
0..1 |
title |
dct:title |
rdfs:Literal |
This property contains a name given to the Register entry for parallel language versions of the name |
0..n |
description |
dct:description |
rdfs:Literal |
This property contains a free-text account of the entry. This property can be repeated for parallel language versions of the description. |
0..n |
Technical standard |
srim:technicalStandard |
This property refers to a technical standard the item class conforms to. For example DCAT ontology, DCAT-AP, etc. |
0..n |
srim:Item
A register Item (also known as register Resource) is the top class of the item hierarchy. It is a subclass of rdfs:Resource. It represents any information entities or services that can be registered in a register.
Rationale: The Item is a generalization of the DCAT Dataset concept. It contains all the common medadata and tradecraft information about any resource of interest for the end-user that needs to be found through a common API.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the resource (effort should done to make it resolvable) |
1 |
type |
rdf:type |
rdfs:Class |
The RDFS Class that the item instantiates |
1 |
title |
dct:title |
rdfs:Literal |
This property contains a name given to the register item. This property can be repeated for parallel language versions of the name. |
1..n |
description |
dct:description |
rdfs:Literal |
This property contains a free-text account of the register item. This property can be repeated for parallel language versions of the description. |
1..n |
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
contactPoint |
dcat:contactPoint |
This property contains contact information that can be used for sending comments about the register item |
0..n |
|
publisher |
dct:publisher |
This property refers to an entity (organization) responsible for making the register item available |
0..n |
|
keyword/tag |
dcat:keyword |
rdfs:Literal |
This property contains a keyword or tag describing the register item. |
0..n |
theme/category |
dcat:theme, subproperty of dct:subject |
This property refers to a category of the register item. A register item may be associated with multiple themes. |
0..n |
|
creation date |
dct:created |
rdfs:Literal typed as xsd:date or xsd:dateTime |
This property contains the date of creation of the register item. |
0..1 |
release date |
dct:issued |
rdfs:Literal typed as xsd:date or xsd:dateTime |
This property contains the date of formal issuance (e.g., publication) of the register item. |
0..1 |
update/modification date |
dct:modified |
rdfs:Literal typed as xsd:date or xsd:dateTime |
This property contains the most recent date on which the register item was modified. |
0..1 |
Optional properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
Third party identifier |
dct:identifier |
xsd:string |
This property contains the main identifier for the register item, e.g. the URI or other unique identifier in the context of the Register. |
0..n |
other identifier |
id:hasIdentifier |
This property refers to a secondary identifier of the register item, such as MAST/ADS18 , DataCite19 , DOI20 , EZID21 or W3ID22 . |
0..n |
|
version |
pav:hasVersion |
This property refers to a version of the register item, and stores a version number and release notes in addition to other version information. |
0..1 |
|
current version |
pav:hasCurrentVersion |
This property refers to the current version of the register item, and stores a version number and release notes in addition to other version information. The current version of the item must also be stored under the previous version property. |
0..n |
|
type |
dct:type (resourceType in JSON) |
This property refers to the type of the register item defined in a controlled vocabulary. |
0..n |
|
spatial/geographic |
dct:spatial |
This property refers to a geographical area covered by the register item. |
0..n |
|
temporal |
dct:temporal |
This property refers to a temporal period covered by the register item |
0..n |
|
landingPage |
dcat:landingPage |
This property refers to a web page that provides access to the register item, its Distributions and/or additional information. It is intended to point to a landing page at the original register item provider, not to a page on a site of a third party, such as an aggregator |
0..n |
|
language |
dct:language |
URL |
This property refers to a language of the register item. This property can be repeated if there are multiple languages in the register item. |
0..n |
owner |
dct:rightsHolder |
This property refers to the owner of the source |
0..n |
|
creator |
dct:creator |
This property refers to the creator of the source |
0..n |
|
contributor |
dct:contributor |
This property refers to a contributor to the source |
0..n |
|
other attributions |
prov:qualifiedAttribution (attribution in JSON) |
This property refers to other responsible parties of the register item playing a role that is different than contactPoint, creator , rightsHolder or publisher. |
0..n |
|
purpose |
srim:purpose |
The purpose of the item |
0..n |
|
audience |
srim:audience |
Intended audience for the item |
0..n] |
|
topic |
srim:topic |
The central topic the item describes |
0..n |
|
project |
srim:project |
The project this item is produced for |
0..n |
|
function |
srim:function |
The function the item is intended for |
0..n |
|
link |
link:hasLink |
This property refers to a resource related to the described register item that is a link to a web page, file, or other such resource on the web. Used when the relationship between the Item and the content of the link is important. |
0..n |
|
Relation |
dct:relation |
rdfs:Resource |
This property is used when this register item has a relation to another resource that is web accessible. If the role of the resource is important, use link:hasLink, or use subproperty of dct:relation |
0..n |
access level |
srim:accessLevel |
string |
Access Level of the Map, Must be one of the following: “public”, “restricted public”, “non-public” |
0..1 |
frequency |
dct:accrualPeriodicity |
URL |
This property refers to the frequency at which the register item is updated. Use the standard vocabulary from http://purl.org/cld/freq (example http://purl.org/cld/freq/irregular) |
0..1 |
Item application profile |
dct:conformsTo |
URL |
This property refers to an Application Profile that the Register item conforms to. |
0..1 |
geographic extent |
extent:hasGeographicExtent |
This property refers to the geographic extent of the metadata held inside the Item. |
0..n |
|
depiction |
foaf:depiction |
This property refers to an image representing the content of the Item. |
0..n |
|
provenance statement |
dct:provenance |
This property refers a provenance statement about the contents of the Item. |
0..n |
prov:Activity
An Activity holds the URI of the source that generated a register entry.
Rationale: Provides provenance information about where the entry came from.
Optional Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the generating activity (effort should done to make it resolvable) |
0..1 |
vcard:Address
To represent address information, we use the well-known ontology VCard.
Rationale: We need a way to describe address information that is based on a well-known standard, so person/organization in charge of resources can be contacted or located.
Recommended Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
street-address |
vcard:street-address |
string |
The street address component of the address |
0..1 |
locality |
vcard:locality |
string |
The locality (city, village) component of the address |
0..1 |
region |
vcard:region |
string |
The region (province/state) component of the address |
0..1 |
postal code |
vcard:postal-code |
string |
The postal code component of the address |
0..1 |
country name |
vcard:country-name |
string |
The country name component of the address |
0..1 |
foaf:Agent
An entity that is associated with Registers and/or Resources. If the Agent is an organization, the use of the Organization ontology is recommended.
Rationale: Defining a standard way to represent agents helps to create hub of information around organizations and people.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
name |
foaf:name |
rdfs:Literal |
This property contains a name of the agent. This property can repeated for different versions of the name (e.g. the name in different languages) |
1..n |
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the agent (effort should done to make it resolvable) |
0..1 |
prov:Attribution
Registered resources are attributed to one or more responsibility parties playing different Attribution roles (contact point,publisher, rights holder, processor…).
Rationale: Needed to understand the role of each contributor of a resources. Provide an extensible mechanism to accommodate new roles.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
agent |
prov:agent |
This property defines the agent of the attribution. |
1 |
|
role |
prov:role |
URL |
The role of the agent in the attribution. Role are typically defined in a taxonomy (such as the one defined in ISO 19115). |
1 |
skos:Concept
A Concept can be viewed as an idea or notion; a unit of thought. However, what constitutes a unit of thought is subjective, and this definition is meant to be suggestive, rather than restrictive.
Rationale: The use of controlled vocabularies helps to organize information at the conceptual level and enable semantic inferencing and classification of information that helps the end-user to find the relevant information that fits better his needs.
Mandatory Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the concept (effort should done to make it resolvable) |
1 |
preferred label |
skos:prefLabel |
rdfs:Literal |
This property contains a preferred label of the concept. This property can be repeated for parallel language versions of the label. |
1..n |
Recommended Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
type |
rdf:type |
rdfs:Class or owl:Class subclass of skos:Concept |
By default the class is skos:Concept. |
0..1 |
scheme |
skos:inScheme |
This property contains the concept scheme in which this concept is defined. |
0..1 |
Optional Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
description |
skos:definition |
rdfs:Literal |
This property contains the definition of the concept. This property can be repeated for parallel language versions of the definition. |
0..n |
skos:ConceptScheme
A concept scheme (e.g. controlled vocabulary) in which the Concept is defined. A concept scheme can be viewed as an aggregation of one or more SKOS concepts. Semantic relationships (links) between those concepts may also be viewed as part of a concept scheme.
Rationale: The use of controlled vocabularies helps to organize information at the conceptual level and enable semantic inferencing and classification of information that helps the end-user to find the relevant information that fits better his needs.
Mandatory Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the concept scheme (effort should done to make it resolvable) |
1 |
title |
dct:title |
rdfs:Literal |
This property contains a title of the concept scheme. This property can be repeated for parallel language versions of the label. |
1..n |
Recommended Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
description |
skos:definition |
rdfs:Literal |
This property contains the definition of the concept scheme. This property can be repeated for parallel language versions of the definition. |
0..n |
foaf:Document
The Document class represents those things which are, broadly conceived, 'documents'. The foaf:Image class is a sub-class of Document, since all images are documents. Document needs to be identified by a resolvable URL on the web.
Rationale: We need a way to describe documents to understand their role in the ecosystem of items managed in the registry.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URL |
The URL of a well-known Document that is resolvable |
1 |
Optional properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
title |
dct:title |
rdfs:Literal |
This property contains a title for the document. This property can be repeated for parallel language versions of the title. |
0..n |
description |
dct:description |
rdfs:Literal |
This property contains a free-text account of the document. This property can be repeated for parallel language versions of the description. |
0..n |
vcard:Email
To represent email information, we use the well-known ontology VCard.
Rationale: We need a way to describe email information that is based on a well-known standard, so the person/organization in charge of a resource can be contacted or located.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
email address |
vcard:hasValue |
URI |
This property holds the email encoded as a URI using the prefix "mailto:" (example mailto:johndoe@example.com) |
1 |
extent:GeographicExtent
GeographicExtent describes the spatial extent of domain of application of an item and is standardized in WGS 84 Lat/Long coordinate system.
Rationale: There is no consensus and common vocabulary to describe spatial in the community. GML Envelope was proposed by it is too cumbersome to process. We introduce four separates fields for each bound (west, east, north and south) that removes any ambiguity and make it easy to query in any spatial index.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
northBoundLatitude |
extent:northBoundLatitude |
xsd:decimal |
North bound latitude in decimal degrees |
1 |
southBoundLatitude |
extent:southBoundLatitude |
xsd:decimal |
South bound latitude in decimal degrees |
1 |
westBoundLongitude |
extent:westBoundLongitude |
xsd:decimal |
West bound longitude in decimal degrees |
1 |
eastBoundLongitude |
extent:eastBoundLongitude |
xsd:decimal |
East bound longitude in decimal degrees |
1 |
id:Identifier
An Identifier provides a mechanism to uniquely identify a resource using a given codespace and defined by an authority.
Rationale: The support of identifiers helps to find items based on some well-know identification systems (ISBN for example).
Mandatory Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
code |
id:code |
string |
The unique code associated with the identifier |
1 |
codespace |
id:codespace |
string |
The codespace in which the code is defined (ISBN for example) |
1 |
Recommended Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
authority |
id:authority |
URL |
The authority defining the identifier scheme |
0..1 |
dct:LicenseDocument
Recommended Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the license document (effort should done to make it resolvable) |
0..1 |
description |
dct:description |
string |
This property stores the content of the license document as a string |
0..1 |
link:Link
A Link contains information about a resource that is related to an Item or another entity and that can be found on the Internet.
Rationale: A Link is useful as a container for a rdfs:Resource that can store the relationship of a link to its parent item as well as information about what is on the other side of the URL.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
link to resource |
link:href |
rdfs:Resource |
This property stores a link to whatever content is being referenced. |
1 |
relationship to Item |
link:rel |
This property refers to a Concept representing the relationship between the linked resource and the Link’s parent Item |
1 |
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
title |
dct:title |
string |
This property refers to the name given to a link. |
0..1 |
description |
dct:description |
rdfs:Literal |
Refers to the description given to a link. This property can be repeated for parallel language versions of the description. |
0..n |
format |
dct:format |
dct:MediaType |
This property refers to the format of the link’s content. |
0..1 |
Optional properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
media type |
link:mediaType |
string |
MIME media type of the link’s content. |
0..1 |
language |
link:hrefLang |
string |
Language of a link’s content. This property can be repeated if there is more than one language. |
0..n |
dct:Location
Location represents a place that is related to the item stored in the register. Each location should a geographic extent expressed in WGS84 to enable spatial search in consistent way. We use dct:Location as the base class for Location.
Rationale: Essential for spatial scoping of data. Location should be referred as much as possible with resolvable URI that points to a controlled vocabulary of place names (Gazetteer). This allows spatial reasoning using place part-of relationships. We try to keep the definition of Location to a bare minimum. More complex geometry can be added down the road. We may use W3c Location ontology to extend the model.
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the location (effort should done to make it resolvable) defined in a gazetteer such as Geonames or DBPedia |
0..1 |
location name |
locn:geographicName |
rdfs:Literal |
A geographic name is a proper noun applied to a spatial object. This property can be repeated for parallel language versions of the place name. |
0..n |
description |
dct:description |
string |
This property contains a free-text account of the location. This property can be repeated for parallel language versions of the description. |
0..n |
gr:OpeningHoursSpecification
An OpeningHoursSpecification describes the hours that a business or other organization is open during the week. It is based in the well-known GoodRelations vocabulary.
Rationale: Having a standard way to capture the opening hours of a business or organization helps understand when it is best to visit or otherwise contact said business or organization.
Optional properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
label |
rdfs:label |
string |
This property stores opening hours information when it cannot be converted to a standardized format. |
0..1 |
opens |
gr:opens |
xsd:time |
This property stores the time at which the organization opens. |
0..1 |
closes |
gr:closes |
xsd:time |
This property stores the time at which the organization closes. |
0..1 |
opening days of week |
gr:hasOpeningHoursDayOfWeek |
gr:DayOfWeek |
This property stores the days of the week on which the organization is open. These are stored as elements of the controlled gr:DayOfWeek vocabulary. |
0..n |
org:Organizaton
An Organization represents a collection of people organized together into a community or other social, commercial or political structure. The group has some common purpose or reason for existence which goes beyond the set of people belonging to it and can act as an Agent. Organizations are often decomposable into hierarchical structures. An Organization is a specialization of an Agent. It is strongly advised that the Organization provides a URL that is shareable and stable according to the best practices of Linked Data.
Rationale: Defining a standard way to represent organizations helps to create hub of information around organizations.
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
parent organization |
org:subOrganizationOf |
The parent organization of the organization |
0..1 |
dct:PeriodOfTime
A PeriodOfTime denotes the temporal scope of a register item. We use dct:PeriodOfTime as the base class, and a time period has startDate and/or endDate. If they are the same, they represent a temporal instant (point in time). A PeriodOfTime can also refer to a URI that can be resolvable and is defined by a well-known taxonomy of periods of time.
Rationale: Essential for temporal scoping of data.
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
Start Date |
schema:startDate |
xsd:date |
The start date of the time period |
0..1 |
End Date |
schema:endDate |
xsd:date |
The end date of the time period |
0..1 |
Optional properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the location (effort should done to make it resolvable) defined in a controlled vocabulary such as Getty |
0..1 |
vcard:Phone
To represent phone information, we use the well-known ontology VCard.
Rationale: We need a way to describe phone information that is based on a well-known standard, so the person/organization in charge of a resource can be contacted or located.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
phone number |
vcard:hasValue |
URI |
This property holds the telephone number encoded as a URI using the prefix "tel:" (example tel:+1 999-999-999) |
1 |
foaf:Project
A project for which data was generated or collected. Uses the well-known foaf:Project ontology.
Rationale: Provides a way to store the project for which the metadata in the register item was generated.
Recommended Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
id |
rdf:id |
URI |
The URI of the generating project (effort should done to make it resolvable) |
0..1 |
name |
foaf:name |
rdfs:Literal |
This property contains a title of the project. This property can be repeated for parallel language versions of the title. |
0..n |
dct:ProvenanceStatement
Statement containing a provenance statement about the origin of a register item. Based on the well-known DCTerms provenance statement (dct:ProvenanceStatement).
Rationale: Provides a way to store free-form provenance information.
Mandatory Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
description |
dct:description |
rdfs:Literal |
This property contains a provenance statement in free-text form. This property can be repeated for parallel language versions of the description. |
0..n |
Optional Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
title |
dct:title |
string |
This property stores the title of the provenance statement. |
0..1 |
identifier |
rdf:id |
URI |
The URI of the provenance statement (effort should done to make it resolvable) |
0..1 |
srim:Release
A Release contains information detailing a specific version of an item.
Rationale: In order to keep track of versioning in sufficient detail, we need to have a class that stores version information such as version number and release notes.
Mandatory Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the resource (effort should done to make it resolvable) |
1 |
version |
pav:version |
string |
This property refers to the version number of the release. |
1 |
Recommended Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
version notes |
adms:versionNotes |
rdfs:Literal |
Version notes pertaining to the release. This property can be repeated for parallel language versions of the notes. |
0..n |
release date |
dct:issued |
rdfs:Literal typed as xsd:date or xsd:dateTime |
This property contains the date of formal issuance (e.g., publication) of the release. |
0..1 |
Optional Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
parent item |
pav:versionOf |
URI |
Unique identifier of the item to which this release pertains. |
0..1 |
dct:RightsStatement
A statement about the intellectual property rights (IPR) held in or over a resource, a legal document giving official permission to do something with a resource, or a statement about access rights.
Rationale: Important legal information protecting intellectual properties.
Recommended Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
description |
skos:definition |
rdfs:Literal |
This property contains the definition of the rights statement. This property can be repeated for parallel language versions of the definition. |
0..n |
Optional Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of a well-known rights statement that is resolvable. |
0..1 |
dct:Standard
A Standard provides a basis for comparison; a reference point against which other things can be evaluated.
Rationale: This is an important concept that is used to understand how register items conforms to standards.
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the standard (effort should done to make it resolvable) |
0..1 |
Optional properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
title |
dct:title |
string |
This property refers to the title of the standard |
0..1 |
version |
pav:version |
string |
This property refers to a specific version of this standard |
0..1 |
description |
dct:description |
rdfs:Literal |
This property contains a description of the standard. This property can be repeated for parallel language versions of the standard. |
0..n |
vcard:VCard
To represent contact information, we use the well-known ontology VCard.
Rationale: We need a way to describe contact information that is based on a well-known standard, so person/organization in charge of resources can be contacted to perform corrections or status information when necessary.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
full name |
vcard:fn |
string |
The name of the person who is the main contact point |
1 |
vcard:hasEmail |
URL |
The email address encoded as a URL starting with the prefix "mailto:" (mailto:foo@example.com). It is strongly recommended to set this property to have a way to contact the person in charge of a register item |
1..n |
Optional properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the vcard |
0..1 |
organization-name |
vcard:organization-name |
String |
The name of the organization of the contact |
0..1 |
telephone |
vcard:hasTelephone |
This property contains a Phone object that holds the telephone number encoded as a URL using the prefix tel: (example tel:+1 999-999-999) |
0..n |
|
title |
vcard:title |
string |
The title (position) of the contact |
0..1 |
landing page |
dcat:landingPage |
URL |
A URL pointing to the landing page of the contact point. |
0..1 |
address |
vcard:address |
The address associated with the Vcard |
0..1 |
|
opening hours |
gr:hasOpeningHoursSpecification |
The opening hours of the organization described in the vcard. |
0..1 |
Dataset Application Profile
dcat:Dataset
A Dataset is a collection of data, published or curated by a single agent and available for access or download in one or more formats.
Rationale: A register item may be a dataset, in which case it is necessary to store information about the dataset and the data inside it.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
distribution |
dcat:distribution |
This property refers to distributions relevant to the dataset |
1..n |
dcat:Distribution
A Distribution is piece of data or metadata than can be accessed via a URL and is relevant to a Dataset.
Rationale: If a register item is a dataset, it is necessary to store information about the data inside it.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
access URL |
dcat:accessURL |
URL |
This property stores a URL pointing to the content of the distribution |
1 |
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
media type |
dcat:mediaType |
string |
This property holds the media type of the contents of the distribution. |
0..1 |
description |
dct:description |
string |
This property stores a description of the distribution. Cardinality is unbounded to allow for multiple languages. |
0..n |
standard |
dct:conformsTo |
The standard a distribution conforms to. |
0..1 |
Optional properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
title |
dct:title |
string |
The title of the distribution. Cardinality is unbounded to allow for multiple languages. |
0..n |
byte size |
dcat:byteSize |
integer |
The size of the distribution file in bytes, if applicable. |
0..1 |
language |
dct:language |
URL |
This property refers to a language used in the distribution describing titles, descriptions, etc. This property can be repeated if the distribution is provided in multiple languages. |
0..n |
format |
dct:format |
The file format of the distribution, if applicable. |
0..1 |
|
document |
foaf:page |
A document relevant to the distribution. |
0..n |
|
license document |
dct:license |
A license document pertaining to the distribution, specifying under what circumstances it can be used or reused. |
0..n |
|
rights statement |
dct:rights |
A rights statement pertaining to the distribution. |
0..n |
|
representation technique |
adms:representationTechnique |
This property refers to the technique used to represent the distribution. |
0..n |
dct:FileFormat
A FileFormat stores information about a file format and is defined by the well-known DCTerms (Dublin Core) vocabulary.
Rationale: Distributions are often stored as a downloadable file, and it is important to keep track of what format each file is in.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
format name |
rdfs:label |
string |
This property stores the name of the file format |
1 |
Optional properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
format version |
pav:version |
string |
The version of the format that is being used |
0..1 |
Service Application Profile
srim:Service
A Web Service is a service offered by an electronic device to another electronic device, communicating with each other via the World Wide Web. In a web service, web technology such as the HTTP, originally designed for human-to-machine communication, is utilized for machine-to-machine communication, more specifically for transferring machine readable file formats such as XML and JSON. Service has all the properties of both a Distribution and an Item.
Rationale: An important aspect of the registry model is to support a service description that can be accessed automatically by machines. We want a core minimal set of properties that enables this automation.
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
relevant Item |
srim:operatesOn |
This property contains the Item that the service operates on. |
0..n |
srim:APIDocument
An APIDocument describes a web accessible document that describes the API of the service. Rationale: To be able to automate the access to a service that is not adhering to a well-known standard (such OGC WMS, ArcREST), we need a mechanism to point out to human and machine processable API document such as (RAML, Swagger, HAL Profile, ALPS profile).
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
Access URL |
dcat:accessURL |
URL |
This property contains the URL to access the API document that can be processed by client |
1 |
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
Media type |
dcat:mediaType |
Mime type string |
This property contains the media type for the API document |
0..1 |
Optional properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
format |
dcat:format |
This property contains a human description of the format |
0..1 |
|
title |
dct:title |
rdfs:Literal |
This property contains a title of the API documentation. This property can be repeated for parallel language versions of the label. |
0..n |
description |
dct:description |
rdfs:Literal |
This property contains a free-text account of the API documentation. This property can be repeated for parallel language versions of the description. |
0..n |
Appendix B: SRIM Schema Application Profile
In the following sections, classes and properties are grouped under headings ‘mandatory’, ‘recommended’ and ‘optional’. These terms have the following meaning.
-
Mandatory class: a receiver of data MUST be able to process information about instances of the class; a sender of data MUST provide information about instances of the class.
-
Recommended class: a sender of data SHOULD provide information about instances of the class; a sender of data MUST provide information about instances of the class, if such information is available; a receiver of data MUST be able to process information about instances of the class.
-
Optional class: a receiver MUST be able to process information about instances of the class; a sender MAY provide the information but is not obliged to do so.
-
Mandatory property: a receiver MUST be able to process the information for that property; a sender MUST provide the information for that property.
-
Recommended property: a receiver MUST be able to process the information for that property; a sender SHOULD provide the information for that property if it is available.
-
Optional property: a receiver MUST be able to process the information for that property; a sender MAY provide the information for that property but is not obliged to do so.
The meaning of the terms MUST, MUST NOT, SHOULD and MAY in this section and in the following sections are as defined in RFC 2119.
In the given context, the term "processing" means that receivers must accept incoming data and transparently provide these data to applications and services. It does neither imply nor prescribe what applications and services finally do with the data (parse, convert, store, make searchable, display to users, etc.).
Classes are classified as Mandatory if they appear as the range of one of the mandatory properties.
Semantic Mediation Ontology
Overview
schema:Schema
A Schema in this context is a specific format used to represent information. Schema extends dcat:Dataset.
Rationale: Because the same data can be represented in a number of different ways, we want to be able to determine what schema is being used and convert from one schema to another.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the resource (effort should done to make it resolvable) |
1 |
type |
rdf:type |
rdfs:Class |
The RDFS Class that the item instantiates (schema:Schema or future subclasses) |
1 |
title |
dct:title |
rdfs:Literal |
This property contains a title given to the schema. This property can be repeated for parallel language versions of the name. |
1..n |
description |
dct:description |
rdfs:Literal |
This property contains a free-text account of the schema. This property can be repeated for parallel language versions of the description. |
1..n |
Recommended properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
namespace |
schema:namespace |
string |
This property store the namespace of the schema when available |
0..1 |
schema language |
schema:schemaLanguage |
This property holds the language used in the schema if applicable. |
1 |
|
distribution |
dcat:distribution |
This property stores distributions held within or otherwise relevant to the schema |
1..n |
Example
@prefix org: <http://www.socialml.org/ontologies/organization#> .
@prefix link: <http://www.opengis.net/ont/link#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix schema-org: <http://schema.org/> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix gr: <http://www.heppnetz.de/ontologies/goodrelations/v1#> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix srim: <http://www.opengis.net/ont/testbed12/srim#> .
@prefix locn: <http://www.w3.org/ns/locn#> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<https://www.fgdc.gov/schemas/metadata/fgdc-std-001-1998>
a schema:Schema ;
dct:created "2016-10-10T16:10:01.213Z"^^xsd:dateTime ;
dct:description "The objectives of the standard are to provide a common set of terminology and definitions for the documentation of digital geospatial data. The standard establishes the names of data elements and compound elements (groups of data elements) to be used for these purposes, the definitions of these compound elements and data elements, and information about the values that are to be provided for the data elements." ;
dct:identifier "FGDC-STD-001-1998" ;
dct:publisher <http://wwww.fgdc.gov> ;
dct:title "Content Standards for Digital Geospatial Metadata Version 2.0" ;
schema:schemaLanguage <http://www.w3.org/TR/xmlschema-1/> ;
dcat:distribution [ a dcat:Distribution ;
dct:description "This is the XML Schema for formal metadata, metadata conforming to the Content Standards for Digital Geospatial Metadata of the Federal Geographic Data Committee. This schema corresponds to the June,\t 1998 version of the standard, FGDC-STD-001-1998.\t This file is the primary XML Schema and loads the definitions for sections 1-10 of the standard from separate schema modules." ;
dct:title "FGDC CSDGM 2.0 Metadata XML Schema" ;
adms:representationTechnique <http://www.w3.org/TR/xmlschema-1/> ;
dcat:accessURL <https://www.fgdc.gov/schemas/metadata/fgdc-std-001-1998.xsd>
] ;
dcat:keyword "FGDC" , "XML Schema" , "CSGDM" , "Geospatial" .
<http://wwww.fgdc.gov>
a org:Organization ;
foaf:name "Federal Geographic Data Committee (FGDC)" .
schema:SchemaMapping
A SchemaMapping is a mapping used to convert a piece of data from one schema to another. SchemaMapping extends dcat:Dataset.
Rationale: Because there is a need to transform data from one scheme to another, it is useful to be able to keep track of the schemas being mapped between.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the resource (effort should done to make it resolvable) |
1 |
type |
rdf:type |
rdfs:Class |
The RDFS Class that the item instantiates (schema:SchemaMapping or future subclasses) |
1 |
title |
dct:title |
rdfs:Literal |
This property contains a title given to the schema. This property can be repeated for parallel language versions of the name. |
1..n |
description |
dct:description |
rdfs:Literal |
This property contains a free-text account of the schema. This property can be repeated for parallel language versions of the description. |
1..n |
source schema |
schema:source |
This property stores the schema being mapped from. |
1 |
|
target schema |
schema:target |
This property holds the schema being mapped to. |
1 |
|
mapping language |
schema:mappingLanguage |
This property stores the language used to create a schema mapping. |
1 |
Example
@prefix schema: <http://www.opengis.net/ont/testbed12/srim/profile/schema#> .
@prefix extent: <http://www.opengis.net/ont/extent#> .
@prefix adms: <http://www.w3.org/TR/vocab-adms/#> .
@prefix pav: <http://purl.org/pav/> .
@prefix org: <http://www.socialml.org/ontologies/organization#> .
@prefix link: <http://www.opengis.net/ont/link#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix schema-org: <http://schema.org/> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix gr: <http://www.heppnetz.de/ontologies/goodrelations/v1#> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix srim: <http://www.opengis.net/ont/testbed12/srim#> .
@prefix locn: <http://www.w3.org/ns/locn#> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<http://www.opengis.net/testbed12/schemas#MNIS2DDMS>
a schema:SchemaMapping ;
dct:created "2016-10-10T16:10:06.490Z"^^xsd:dateTime ;
dct:description "Schema Mapping from NMIS 2.2 to DDMS" ;
dct:publisher <http://wwww.nga.mil> ;
dct:title "NMIS 2.2 to DDMS SchemaMapping" ;
schema:mappingLanguage <https://www.w3.org/TR/xslt20/> ;
schema:sourceSchema <http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2> ;
schema:targetSchema <http://metadata.dod.mil/mdr/ns/DDMS/2.0> ;
dcat:distribution [ a dcat:Distribution ;
dct:description "NGA.STND.0018_2.2 to DDMS SchemaMapping XSLT Distribution" ;
dct:title "NMIS to DDMS SchemaMapping XSLT Distribution" ;
adms:representationTechnique <https://www.w3.org/TR/xslt20/> ;
dcat:accessURL <http://ows.galdosinc.com:80/indicio/query?request=GetRepositoryItem&service=CSW-ebRIM&id=urn:uuid:38ffef44-e1ee-4856-8812-d8b82da497a4>
] ;
dcat:keyword "NAS" , "DDMS" , "XSLT" , "Geospatial" , "NMIS" .
<http://wwww.nga.mil>
a org:Organization ;
foaf:name "National Geospatial Intelligence Agency (NGA)" .
schema:SchemaLanguage
A SchemaLanguage is the language that a schema is written in. SchemaLanguage extends skos:Concept.
Rationale: It is important to keep track of what language a schema is written in so that the dataset using that schema can later be processed.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the resource (effort should done to make it resolvable) |
1 |
schema:SchemaMappingLanguage
A SchemaMappingLanguage is the language that defines a schema mapping. SchemaMappingLanguage extends skos:Concept.
Rationale: It is important to keep track of what language is being used to transform a dataset from one schema to another.
Mandatory properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the resource (effort should done to make it resolvable) |
1 |
schema:SchemaRelease
A SchemaRelease is a single release (version) of a schema. SchemaRelease extends srim:Release.
Rationale: It is necessary to keep track of past releases of a schema in case backwards compatability is needed.
Mandatory Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
identifier |
rdf:id |
URI |
The URI of the resource (effort should done to make it resolvable) |
1 |
version |
pav:version |
string |
This property refers to the version number of the release. |
1 |
Recommended Properties
Property | URI | Range | Usage Note | Cardinality |
---|---|---|---|---|
version notes |
adms:versionNotes |
rdfs:Literal |
Version notes pertaining to the release. This property can be repeated for parallel language versions of the notes. |
0..n |
release date |
dct:issued |
rdfs:Literal typed as xsd:date or xsd:dateTime |
This property contains the date of formal issuance (e.g., publication) of the release. |
0..1 |
Appendix C: Semantic Portrayal Ontologies
A.1 Overview
The Portrayal Ontologies specify a conceptual model for portrayal data, in particular symbols and portrayal rules. Portrayal rules associate features with symbols for the portrayal of the features on maps and other display media. These ontologies include classes, attributes and associations that provide a common conceptual framework that specifies the structure of and interrelationships between feature types, portrayal rules and symbols. It separates the content of the data from the portrayal of that data to allow the data to be portrayed in a manner independent of the dataset. The graphic description is intended to be format independent but convertible to any target formats (SVG, KML). The ontologies are derived from concepts found in existing portrayal specifications (ISO 19117, OGC Symbology Encoding, Styled Layer Descriptor Profile of WMS, SVG, KML, CartoCSS, MapCSS).
To favor reusability, the Portrayal ontologies are decomposed into four microtheories, each one addressing an orthogonal aspect of portrayal:
-
Style ontology: defines the concept of Style and portrayal rules.
-
Symbol ontology: defines the concept of SymbolSet and Symbol and structural definition of Symbol components.
-
Symbolizer ontology: defines the concepts of Symbolizers defining instructions to render data as graphics.
-
Graphic Ontology: defines graphic elements including graphic objects and attributes.
Style Ontology
The Style Ontology defines concept of Style, Portrayal Rule Set, Portrayal Rule, Rule Condition and PortrayalContext. The Figure below shows an overview of the model in UML.
Style
The Style concept is the central concept of the Style ontology. It associates symbol sets with portrayal rule sets, which define the mapping of feature types to symbols. The Style also captures descriptive metadata and tradecraft information such as the audience for the style, scope of application and field of application.The following table summarizes the properties of the Style class.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
name |
Name identifier of the style. |
String |
One |
dct:title |
Multilingual human-readable title for the style |
1..n (one per language) |
|
dct:description |
Multilingual human-readable description for the style |
String |
1..n (one per language) |
hasRule |
PortrayalRule or ordered PortrayalRuleList associated with the Style. |
PortrayalRule or PortrayalRuleList |
1..n |
dct:audience |
The intended audience of this style. |
foaf:Group |
0..n |
scope |
Descriptive definition of the scope of application of the style |
String |
0..1 |
language |
Language associated with the style |
String |
0..n |
style:symbolSet |
SymbolSet associated with the style |
SymbolSet |
0..n |
fieldOfApplication |
The field of application of this style, where values are defined as SKOS concept in a taxonomy. |
skos:Concept |
0..n |
FeatureTypeStyle
A FeatureTypeStyle is a style that is applied for a specific feature:FeatureType. FeatureTypeStyle inherits all properties from Style.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
name |
Name identifier of the style. |
String |
One |
dct:title |
Multilingual human-readable title for the style |
1..n (one per language) |
|
dct:description |
Multilingual human-readable description for the style |
String |
1..n (one per language) |
featureType |
FeatureType associated with the style |
1..n |
hasRule |
The following example shows the definition of the EMS Style with audience information organized as a hierarchy.
@prefix : <http://www.opengis.net/testbed/12/portrayal/ems/style#> .
@prefix feature: <http://www.opengis.net/ont/feature#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix ems: <http://www.opengis.net/testbed11/ont/incident/ems#> .
@prefix style: <http://www.opengis.net/ont/portrayal/style#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix group: <http://www.socialml.org/ontologies/group#> .
:EMSIncidentStyle a style:FeatureTypeStyle ;
dct:audience <http://ows.usersmarts.com/ldapp/audiences/community/CanadianEmergencyAndDisasterManagement> ;
dct:description "Style defining the set of rules for mapping incident types from EMS to symbology" ;
dct:title "EMS Incident Type Style" ;
style:featureType ems:EMSIncident ;
style:hasRule :ems.incident.hazardousMaterial.radiologicalHazard-portrayal-rule , :ems.incident.temperature.windChill-portrayal-rule, :ems.incident.health-portrayal-rule , :ems.incident.hazardousMaterial-portrayal-rule .
ems:EMSIncident a feature:FeatureType ;
rdfs:comment "Incident defined for Canadian Emergency Management System" ;
rdfs:label "EMSIncident" ;
feature:gmlName "ems:EMSIncident" .
<http://ows.usersmarts.com/ldapp/audiences/community/EmergencyAndDisasterManagement>
a foaf:Group , group:Group ;
rdfs:label "Emergency and Disaster Management Community" ;
foaf:name "Emergency and Disaster Management Community" .
CoverageStyle
A CoverageStyle is a style that is applied for a Coverage. CoverageStyle inherits all properties from Style. This concept is introduced as a placeholder for future extension.
PortrayalRuleSet
A portrayal rule set describes a function set which maps the feature types of a feature catalog to a symbol. It is composed of one or more portrayal rules, which in turn maps an individual feature type to a symbol. The table below provides a summary of the PortrayalRuleSet.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
dct:title |
Multilingual human-readable name for the PortrayalRuleSet |
string |
0..n (one per language) |
dct:description |
Multilingual human-readable description for the PortrayalRuleSet |
string |
0..n (one per language) |
hasRule |
PortrayalRule member of this PortrayalRuleSet. |
PortrayalRule |
0..n |
The following is a sample of the PortrayalRuleSet defined for the EMS Style.
:EMSRuleSet a style:PortrayalRuleSet ;
dct:description "Set of rules for mapping incident types from EMS to symbology" ;
dct:title "EMS Portrayal Rule Set" ;
style:hasRule :ems.incident.temperature.windChill-portrayal-rule ,
:ems.incident.roadway.hazardousRoadConditions-portrayal-rule ,
:ems.incident.civil-portrayal-rule ,
:ems.incident.roadway.trafficReport-portrayal-rule ,
:ems.incident.meteorological.waterspout-portrayal-rule ,
:ems.incident.geophysical.lahar-portrayal-rule ,
:ems.incident.meteorological-portrayal-rule ,
:ems.incident.meteorological.stormSurge-portrayal-rule ,
:ems.incident.aviation-portrayal-rule ,
:ems.incident.hazardousMaterial.radiologicalHazard-portrayal-rule ,
:ems.incident.crime.bomb-portrayal-rule .
PortrayalRule
A PortrayalRule defines a rule that associates a feature type (feature:FeatureType) to a symbol (symbol:Symbol) satisfying a certain condition (PortrayalRuleCondition) in a given context (PortrayalContext). The Table below summarizes its properties.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
dct:title |
Multilingual human-readable title for the PortrayalRule |
string |
0..n (one per language) |
dct:description |
Multilingual human readable description for the PortrayalRule. |
string |
0..n (one per language) |
hasCondition |
The conditions that needs to be satisfied by the rule |
PortrayalRuleCondition |
0..n |
maxScaleDenominator |
The maximum scale denominator to which the rule applies |
integer |
0..1 |
minScaleDenominator |
The minimum scale denominator to which the rule applies |
integer |
0..1 |
portrayalContext |
The context of application of the PortrayalRule (placeholder for future extension) |
PortrayalContext |
0..n |
symbol |
The symbol associated with the rule |
symbol:Symbol |
1 |
The listing below shows an example of PortrayalRule for Windchill. The PortrayalRule applied on the ems:EMSIncident featureType and associates the EMS symbol for Windchill defined by the URL: http://www.opengis.net/testbed/11/cci/ems/symbols#ems.incident.temperature.windChill-symbol
:ems.incident.temperature.windChill-portrayal-rule
a style:PortrayalRule ;
dct:description "Portrayal rule for incident type ems.incident.temperature.windChill" ;
dct:title "Wind Chill incident portrayal rule" ;
style:hasRuleCondition :ems.incident.temperature.windChill-portrayal-rule-condition;
style:maxScaleDenominator "100000.0"^^xsd:double ;
style:minScaleDenominator "0.0"^^xsd:double ;
style:symbol <http://www.opengis.net/testbed/12/ems/symbols#ems.incident.temperature.windChill-symbol> .
RuleCondition
The RuleCondition defines the condition in which a portrayal rule applies for a given feature. The RuleCondition can be encoded using multiple encodings. The Table below summarizes the properties of PortrayalRuleCondition.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
dct:title |
Multilingual human-readable name for the RuleCondition |
string |
0..n (one per language) |
dct:description |
Multilingual human-readable description for the RuleCondition |
string |
0..n (one per language) |
hasConstraint |
The encoding of the constraint defining the condition |
Constraint |
0..n |
To provide an extensible mechanism to express constraints for the condition, we modified the previous ontology in Testbed 11, which uses specialized properties (sparqlCondition, rifCondition,ogcFiterCondition)
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
constraintLanguage |
The constraint language used to encode the constraint. The following constraint languages URLs are currently recommended: |
URL |
1 |
body |
The constraint body expressed in the constraint language |
String |
1 |
The following example demonstrates the encoding of the portrayal rule condition for the Portrayal rule for the symbol Windchill. The condition applies on the feature property ems:incidentType. If the value of this property is equals to http://www.opengis.net/taxonomy/ems#ems.incident.temperature.windChill then the rule is applicable.
:ems.incident.temperature.windChill-portrayal-rule-condition
a style:RuleCondition ;
style:hasConstraint
[ style:Constraint ;
style:body "PREFIX ems: <http://www.opengis.net/testbed11/ont/incident/ems#>\nASK \nWHERE { ?this ems:incidentType <http://www.opengis.net/taxonomy/ems#ems.incident.temperature.windChill>.\n}" ;
style:constraintLanguage <http://www.w3.org/ns/sparql-service-description#SPARQL11Query>
] ;
style:hasConstraint
[ a style:Constraint ;
style:body "<ogc:Filter><ogc:PropertyIsEqualTo><ogc:PropertyName>incidentType</ogc:PropertyName><ogc:Literal>http://www.opengis.net/taxonomy/ems#ems.incident.temperature.windChill</ogc:Literal></ogc:PropertyIsEqualTo></ogc:Filter>" ;
style:constraintLanguage <http://schemas.opengis.net/filter>
] ;
style:hasConstraint
[ a style:Constraint ;
style:body "Prefix(ems <http://www.opengis.net/testbed11/ont/incident/ems#>)\nExists ?this ( ems:incidentType(?this <http://www.opengis.net/taxonomy/ems#ems.incident.temperature.windChill>) )" ;
style:constraintLanguage <http://www.w3.org/2007/rif>
]
The rule is expressed in three different encodings: OGC Filter, SPARQL and RIF.
The SPARQL query is formulated as a ASK query which returns a boolean value. The variable ?this is bound to the current instance of featureType that is being tested.
PREFIX ems: <http://www.opengis.net/testbed11/ont/incident/ems#>
ASK
WHERE {
?this ems:incidentType
<http://www.opengis.net/taxonomy/ems#ems.incident.temperature.windChill>.
}
The equivalent RIF condition is expressed as:
Prefix(ems <http://www.opengis.net/testbed11/ont/incident/ems#>)
Exists ?this
( ems:incidentType(?this <http://www.opengis.net/taxonomy/ems#ems.incident.temperature.windChill>) )
The Constraints expressed in SPARQL and RIF can be used by a semantic portrayal rule engine that consumes feature data represented as Linked Data (recommendation for next testbed). We foresee that the portrayal catalog containing these rules can be extended with a rendering service that will apply the rules on a set of linked data compatible with the style and generates the portrayal rendering to a number of target formats (SVG, KML etc..). We suggest we experiment this capability in the next testbed.
To perform the bridge between the Linked Data representation of the FeatureType and GML representation we annotated the FeatureType and FeatureProperty with the attribute gmlName to indicate what is the mapping between the conceptual definition and the GML syntactic definition based on XML schema.
The following example shows the feature type definition for EMSIncident with the gmlName annotations.
ems:EMSIncident a feature:FeatureType ;
rdfs:comment "Incident defined for Canadian Emergency Management System" ;
rdfs:label "EMSIncident" ;
feature:gmlName "ems:EMSIncident" .
ems:incidentType a feature:FeatureProperty ;
rdfs:label "incidentType" ;
feature:gmlName "ems:incidentType" .
The following example shows the feature type definition for HSWGIncident with the gmlName annotations.
hswg:HSWGIncident a feature:FeatureType ;
rdfs:comment "Incident defined for Homeland Security Working Group" ;
rdfs:label "HSWGIncident" ;
feature:gmlName "hswg:HSWGIncident" .
hswg:incidentType a feature:FeatureProperty ;
rdfs:label "incidentType" ;
feature:gmlName "hswg:incidentType" .
PortrayalRuleList and RuleItem
In some instance, rules needs to be executed in a given order with support of fallback rules.The PortrayalRuleList defines a ordered list of RuleItem instances. The PortrayalRuleList is implemented by an rdf:List.
The RuleItem defines a placeholder referring indirectly to a portrayal rule. However it can also provides a reference to fallback portrayal rules (elseRule) if the rule is not applicable. The RuleItem is used when the order of application of the rules is important. The RuleItem are used as element of PortrayalRuleList.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
rule |
The rule associated with the rule item |
PortrayalRule |
1 |
Symbology Ontology
The Symbology Ontology is a microtheory that defines the conceptual model for defining SymbolSet and Symbol with their structural components called Symbolizer.
The Figure below shows an overview of the model.
SymbolSet
SymbolSet collects symbols into sets of symbols that are used together. Symbols can be shared among symbol sets. A Symbol set can be equated with legend of a map. The Table below summarizes the SymbolSet properties.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
dct:identifier |
Unique identifier for the symbol set mainly used by machine. |
string |
One |
dct:title |
Multilingual human-readable title for the SymbolSet |
string |
0..n (one per language) |
dct:description |
Multilingual human-readable description for the SymbolSet |
string |
0..n (one per language) |
specification |
Cites the specification standard for the SymbolSet |
Resource |
0..1 |
symbol |
Symbol member of this SymbolSet |
Symbol |
0..n |
The following example shows a sample of the EMS SymbolSet.
@prefix : <http://www.opengis.net/testbed/11/cci/ems/symbols#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix graphic: <http://www.opengis.net/ont/portrayal/graphic#> .
@prefix symbol: <http://www.opengis.net/ont/portrayal/symbol#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
:EMSSymbolSet a symbol:SymbolSet ;
dct:description "Standard Canadian Emergency Mapping Symbology (EMS) SymbolSet version 1.0" ;
dct:title "Canadian Emergency Mapping Symbology (EMS) SymbolSet (version 1.0)" ;
symbol:symbol :ems.incident.roadway.roadwayClosure-symbol , :ems.incident.temperature.windChill-symbol , :ems.incident.temperature.heatWave-symbol , :ems.incident.civil.looting-symbol , :ems.incident.civil.dignitaryVisit-symbol , :ems.incident.civil.displacedPopulations-symbol , :ems.incident.publicService-symbol ;
symbol:specification <https://cms.masas-x.ca.s3.amazonaws.com/EMS_Symbology_v1.0.pdf> .
Symbol
A Symbol is the type used to define symbol classes. Symbols are collected into symbol sets. A symbol has one machine readable identifier. It is described by a title, description and can refer to a formal specification document. A symbol can denote a concept defined in a SKOS taxonomy. The table below summarizes the Symbol properties.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
dct:identifier |
Machine readable name for the symbol. The identifier should be unique |
string |
1 |
dct:title |
Multilingual human-readable title for the Symbol |
string |
0..n (one per language) |
dct:description |
Multilingual human-readable description for the Symbol |
string |
0..n (one per language) |
specification |
Reference to the full details of the portrayal symbol |
Resource |
0..1 |
browseGraphic |
Reference a graphic representing the symbol |
Resource |
0..1 |
denotes |
Concept that is denoted by the symbol |
skos:Concept |
0..n |
symbolizer:symbolizer |
Defines the symbolizer rendering the symbol |
symbolizer:Symbolizer |
0..n |
symbolSet |
The SymbolSet which this symbol belongs to. |
SymbolSet |
0..n |
skos:notation |
Notation used to refer the symbol as defined in a notation system. Use a custom datatype if multiple notations are used |
string |
0..n |
The following listing shows the encoding in Turtle for the WindChill symbol belonging to the EMS SymbolSet.
:ems.incident.roadway.roadwayClosure-symbol
a symbol:Symbol ;
dct:title "roadwayClosure" ;
symbol:browseGraphic <http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.roadway.roadwayClosure.png> ;
symbol:denotes <http://www.opengis.net/taxonomy/ems#ems.incident.roadway.roadwayClosure> ;
symbol:specification <https://cms.masas-x.ca.s3.amazonaws.com/EMS_Symbology_v1.0.pdf> ;
symbol:symbolName "ems.incident.roadway.roadwayClosure" ;
symbol:symbolSet :EMSSymbolSet ;
symbolizer:symbolizer :ems.incident.roadway.roadwayClosure-pointSymbolizer .
:ems.incident.roadway.roadwayClosure-pointSymbolizer
a symbolizer:PointSymbolizer ;
dct:title "PointSymbolizer for roadwayClosure symbol" ;
graphic:graphicSymbol [ a graphic:GraphicSymbol ;
graphic:externalGraphic <http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.roadway.roadwayClosure.png>
] .
<http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.roadway.roadwayClosure.png>
a graphic:ExternalGraphic ;
dct:description "icon for ems.incident.roadway.roadwayClosure" ;
dct:title "ems.incident.roadway.roadwayClosure icon" ;
graphic:format "image/png" ;
graphic:onlineResource <http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.roadway.roadwayClosure.png> .
Symbolizer Microtheory
The Symbolizer ontology defines a set of symbolizers (also called renderers) that defines instructions for rendering data to graphic representation. The ontology is built on top of the Graphic Ontology which defines graphic objects and properties. Symbolizers are referred by symbol:Symbol to describe how conceptual symbol are rendered into graphics. The details of the ontology is described in Appendix C. This section describes an overview of the microtheory, examples and rationale of some of the design decisions.
The OGC Symbology Encoding defines a number of symbolizers that uses SVG parameters defines a key value pair. While this mechanism provides extensibility by accomodate future key value pairs, there is no schema allowing to know which keys are valid for a given symbolizer. We decided to move away from the approach used in the previous testbed 11, based on the ISO 19117 model which introduces symbol definition, symbol components and graphics. We found out that the ISO 19117 was not adequate to represented as semantic descriptive model. The ISO 19117 is more geared toward an implementation which can use function to calculate positioning of symbol components. We decided to align out model more toward main stream map renderer and descriptive standards such as SVG. ==== Symbolizer Hierarchy
The top concept of the Symbolizer ontology is Symbolizer. A Symbolizer describes how a feature is to appear on a map. The Symbolizer describes not just the shape that should appear but also how visual variables are defined using graphical properties such as color and opacity. A Symbolizer is obtained by specifying one of subclass of Symbolizer and then supplying parameters to override its default behavior. The hierarchy of symbolizer is illustrated in the following figure.
Note that the hierarchy uses similar terminology than the OGC SE specification, except that it introduces an additional class called CompositeSymbolizer that defines a composition of symbolizers applied in a given order and using a composition operation (default is source over). This version of the ontology mostly focused on rendering of feature (vector) data, and is not addressing in depth the Raster Symbolizer, which is introduced as a placeholder for future extension. Other extensions of symbolizer may be defined down the road for more specialized use-cases such as complex symbologies that are difficult to express with graphic descriptors (example MIL 2525 symbology).
Symbolizer
Symbolizer is the top class of all the symbolizer and provides properties that are inherited by all subclasses.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
name |
symbolizer name |
xsd:string |
0..1 |
dct:title |
title of the symbolizer |
xsd:string |
0..1 |
dct:description |
description of the symbolizer |
xsd:string |
0..1 |
:uom |
Unit of measure that applies to all elements included inside a Symbolizer such as stroke-width, Size, fontsize, Gap, InitialGap, Displacement and PerpendicularOffset. If no uom is set inside of Symbolizer, all units are measured in pixel. |
URI |
0..1 |
Point Symbolizer
A PointSymbolizer is defined as a Symbolizer that is used to draw a “graphic” at a point. If the geometry associated with the PointSymbolizer is not a point, such as a line, polygon, raster, a representative point of the geometry (typically centroid) should be used.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
graphic:graphicSymbol |
graphic symbol |
graphic:GraphicSymbol |
0..1 |
:geometryProperty |
Geometric Property associated with the point symbolizer |
:Property |
0..n |
Line Symbolizer
A LineSymbolizer is a Symbolizer that is used to render a "stroke" along a linear geometry type such as string of line segments. Geometry types other than inherently linear types can also be used. If a point geometry is used, it should be interpreted as a line of “epsilon” (arbitrarily small) length with a horizontal orientation centered on the point, and should be rendered with two end caps. If a "area" geometry (for example polygon) is used, then its closed outline is used as the line string (with no end caps). If a raster geometry is used, its coverage-area outline is used for the line, rendered with no end caps.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:geometryProperty |
Geometric Property associated with the symbolizer |
:Property |
0..n |
graphic:stroke |
Stroke associated with the line symbolizer |
graphic:Stroke |
0..1 |
graphic:perpendicularOffset |
Perpendicular offset |
xsd:decimal |
0..1 |
Polygon Symbolizer
A PolygonSymbolizer is a Symbolizer that is used to render the area enclosed by a polygon. If a polygon has “holes,” then they are not filled, but the borders around the holes are stroked in the usual way. “Islands” within holes are filled and stroked, and so on. If a point geometry is referenced instead of a polygon, then a small, square, ortho-normal polygon should be constructed for rendering. If a line is referenced, then the line (string) is closed for filling (only) by connecting its end point to its start point, any line crossings are corrected in some way, and only the original line is stroked. If a raster geometry is used, then the raster-coverage area is used as the polygon.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:geometryProperty |
Geometric Property associated with the symbolizer |
:Property |
0..n |
graphic:stroke |
Stroke associated with the polygon symbolizer |
graphic:Stroke |
0..1 |
graphic:fill |
Fill associated with the polygon symbolizer |
graphic:Fill |
0..1 |
graphic:perpendicularOffset |
Perpendicular offset |
xsd:decimal |
0..1 |
graphic:displacement |
Displacement |
graphic:Translation |
0..1 |
Text Symbolizer
A TextSymbolizer is a Symbolizer that is used to render text.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:geometryProperty |
Geometric Property associated with the symbolizer |
:Property |
0..n |
graphic:font |
Font associated with the text symbolizer |
graphic:Font |
0..1 |
graphic:fill |
Fill associated with the text symbolizer |
graphic:Fill |
0..1 |
graphic:halo |
Halo associated with the text symbolizer |
graphic:Halo |
0..1 |
graphic:labelPlacement |
LabelPlacement associated with the text symbolizer (could be PointPlacment or LinePlacement for example) |
graphic:LabelPlacement |
0..1 |
Raster Symbolizer
A RasterSymbolizer is a Symbolizer that is used to render raster. This symbolizer has been introduced as a placeholder for future extensions, as this testbed was primarely focused on symbolization of vector data.
Composite Symbolizer
A CompositeSymbolizer is a symbolizer composed of a list of Symbolizers that applied in a given order using a given composition operation. Default composition operation is src-over composition.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:comp-op |
Composition operator valid values are " "src-over", "dest-out", "dest-over |
xsd:string |
0..1 |
:items |
List of Symbolizer rendered in the order of the list |
rdf:List of Symbolizers |
1 |
Graphics Microtheory
Context
This document is prepared in the context of the Semantic Portrayal Service - a true semantic-enabled service that demonstrates semantic integration and interoperability accross disparate portrayal catalogues.
Scope
The objective of this ontology is to define vocabulary terms describing graphic elements (objects and properties) using Linked Data encoding. The use of ontology language such as OWL provides a powerful mechanism to express the semantic, classification, relationships and constraints of the graphic elements. The Linked data encoding for the graphics enables to build a "Web of Graphics" that could be referenced by other resources and the decentralized distribution of graphics information on the web, favoring reusability of graphics and linkage to application that can go beyond styling application. In the case of map portrayal application, the graphic ontology is used by symbolizers to instruct renderers the way to render features on a map.
To model the graphic elements of the ontology, we try to use a model that is close to the way graphic properties are defined in CSS and SVG. For example to encode color, the preferred way is to use literal with a CSSColorLiteral datatype that uses the same syntax than CSS and SVG. Similarly length can be expressed using different unit of measures (percent, cm, mm). Instead of introducing a concept of Length and Unit of Measure that could be very verbose, we choose to use introduce a datatype LengthType that is based on the SVG and CSS syntax.
Terminology used in the Graphics Ontology
The Graphics Ontology reuses terms from various existing specifications. The default namespace used in the documentation of the ontology is http://www.opengis.net/ont/portrayal/graphic#. The preferred prefix for this namespace is graphic. Classes and properties in the next sections that have been taken from the following namespaces.
Prefix | Namespace |
---|---|
dct |
|
geosparql |
|
owl |
|
rdf |
|
rdfs |
|
xsd |
Graphics Ontology Classes
This figure shows a UML Diagram of all classes and properties included in the Graphics Ontology.
Graphic Element
The :GraphicElement concept is the top concept of the Graphic Ontology. It is aligned with the definition introduced in ISO 19117. :GraphicElement is the abstract root for the graphic elements, as defined in a graphic specification language (such as SVG or OGC SE), that defines a symbol. The graphic elements may be graphic objects, such as shapes, texts or graphic properties such as colour, stroke, fill, font. A :GraphicElement has two subclasses: :GraphicObject and :GraphicProperty.
Graphic Object
A :GraphicObject is an abstract class defined as a :GraphicElement that can be drawn such as a graphic shape (oval, ellipse, rectangle, path) , Raster, Glyphs (text and graphic symbols) .
Note
|
The term SY_GraphicObject is defined in ISO 19117 as "an abstract specialization of SY_GraphicElement as a graphic object defined in a graphic specification language. Graphic objects are graphic elements, such as ovals, rectangles, or paths. A graphic object in turn has properties, such as location attributes, size attributes, colour attributes, etc." |
The :GraphicObject is the base class of a hierarchy illustrated below. The detail of each subclass is described in next sections.
Shape
A :Shape is a :GraphicObject defining a geometric figure.
Note
|
The term :Shape is defined in SVG as an element defined by some combination of straight lines and curves. Specifically:path, rect, circle, ellipse, line, polyline, and polygon. |
The description of the geometry of the shape can be defined in different geometry description language such as GML, WKT and SVG. The ontology reuses the definition of GeoSPARQL geosparql:asWKT, geosparql:asGML to represent respectively geometry encoded in WKT and GML. GeoSPARQL introduces two datatypes to validate the encoding (geosparql:WKTLiteral and geosparql:GMLLiteral). To accommodate more complex path, the graphic ontology introduces an additional property (asSVGPath) and datatype for encoding SVG Path (:svgPathLiteral), which uses the syntax of path defined in SVG.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
geosparql:asWKT |
Define the geometry using Well-Known-Text Encoding |
geosparql:wktLiteral |
0..1 (optional) |
geosparql:asGML |
Define the geometry using GML Geometry Encoding |
geosparql:gmlLiteral |
0..1 (optional) |
svgPath |
specifies a path of the shape using SVG graphic language |
:svgPathLiteral |
0..1 (optional) |
Graphic Symbol
A :GraphicSymbol is a :GraphicObject with an inherent shape, color(s), and possibly size. A :GraphicSymbol can be very informally defined as “a little picture” and can be of either a raster or vector-graphic source type. The term “GraphicSymbol” is used since the term “symbol” is similar to “Symbolizer” which is used in a different context in SE."
Note
|
The term :GraphicSymbol is synonymous to Graphic in the SE Implementation Specification, which is defined as a “graphic symbol” with an inherent shape, color(s), and possibly size. A “graphic” can be very informally defined as “a little picture” and can be of either a raster or vector-graphic source type. The term “graphic” is used since the term “symbol” is similar to “Symbolizer” which is used in a different context in SE." |
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:externalGraphic |
external graphics contained a graphic symbol |
:ExternalGraphic |
0..1 (optional) |
:mark |
Marks contained in a graphic symbol |
:Mark |
0..1 (optional) |
:opacity |
opacity of the color or the content the current object is filled with |
xsd:decimal (0.0 to 1.0), representing percent opacity |
0..1 (optional) |
:size |
Absolute size |
xsd:decimal, Non-negative real number in pixels |
0..1 (optional) |
:anchorPoint |
The location inside object to use for anchoring to main geometry point |
AnchorPoint |
0..1 (optional) |
External Graphic
An ExternalGraphic gives a reference to an external raster or vector graphical object. It allows a reference to be made to an external graphic file with a Web URL or to in-line content. The :onlineResource property gives the URL and the :format property identifies the expected document MIME type of a successful fetch. Knowing the MIME type in advance allows the styler to select the best-supported format from the list of URLs with equivalent content. The :inlineContent property allows the content of an external graphic object to be included in-line as a xsd:base64Binary datatype.
Note
|
The term ExternalGraphic is defined in the SE Implementation Specification as an element that "allows a reference to be made to an external graphic file with a Web URL or to in-line content." |
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:onlineResource |
URL of external graphic |
URL |
0..1 (conditional) |
:inlineContent |
Content of external graphic |
xsd:base64Binary |
0..1 (conditional) |
:format |
MIME type of external graphic |
xsd:string |
1 (mandatory) |
Mark
A :Mark is a :GraphicObject that describes a graphic symbol based on a shape with coloring applied to it.
Note
|
The term :Mark is defined in SE as an element that defines a “shape” which has coloring applied to it. The Mark element serves two purposes. It allows the selection of simple shapes, and, in combination with the capability to select and mix multiple external-URL graphics and marks, it allows a style to be specified that can produce a usable result in a best-effort rendering environment, provided that a simple Mark is included at the bottom of the list of sources for every Graphic. |
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:fill |
Mark fill |
:Fill |
0..1 (optional) |
:stroke |
Marks contained in a graphic symbol |
:Mark |
0..1 (optional) |
:shape |
The shape associated with the Mark |
:Shape |
0..1 (conditional) |
:onlineResource |
URL of the graphic symbol |
URI |
0..1 (conditional) |
:inlineContent |
Content of the graphic symbol |
xsd:base64Binary |
0..1 (conditional) |
:format |
format or MIME type |
xsd:string |
0..1 (conditional) |
:markIndex |
Index to an individual mark in a mark archive; include when needed to uniquely identify mark. |
xsd:string |
0..1 (optional) |
Text
A :Text is a :GraphicObject that describes a graphic symbol based on a shape with coloring applied to it.
Note
|
The term :Text is defined in SVG as a "graphic element consisting of text. The attributes and properties on the text element indicate such things as the writing direction, font specification and painting attributes which describe how exactly to render the characters." |
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:font |
The font information for the label |
:Font |
0..1 (optional) |
:graphicSymbol |
A graphic symbol to be displayed behind the label text |
:GraphicSymbol |
0..1 (optional) |
:textLabel |
The text content for the label |
xsd:string |
0..1 (optional) |
:labelPlacement |
sets the position of the label relative to its associated geometry. |
:LabelPlacement |
0..1 (conditional) |
:halo |
Creates a colored background around the label text, for improved legibility. |
:cssColorLiteral |
0..1 (optional) |
:fill |
The fill style of the label text |
:Fill |
0..1 (optional) |
Graphic Datatypes
The Graphic ontology introduces a couple of datatypes that are used to indicate RDF processor how to convert and validate string literal to internal value.
cssColorLiteral
Graphic Properties
GraphicProperty
A :GraphicProperty is defined as a :GraphicElement that represents attributes that are used to modify the appearance of the graphic objects, such as its size, orientation, color, outline stroke, fill pattern, fonts, font size. While in several standards such as ISO 19117 and OGC SE, graphic properties are encoded as name/value pairs, which provide flexibility to add future extensions with new names, they do not provide any semantic to the name and make hard to define the adequate restrictions of graphic properties on specific graphic objects. It is also prone to misinterpretation by implementers.
The use of ontology provides a clear semantic for each property and relationships to other properties. For example, :font-color, :stroke-color and :fill-color are defined as subproperties of :color. The graphic ontology introduces two ways to model graphic properties. The first one is by defining subproperties of the datatype property :graphicProperty (for example :stroke-width, :stroke-color, :font-size). The second way is by defining a subclass of the :GraphicProperty such as :Stroke, :Color, :Font, :Fill, which are often used as reusable containers for of multiple graphic properties.
Note
|
The term GraphicProperty is defined in ISO 19117 as "a templatized specialization of SY_GraphicElement used to define graphic properties, such as location attributes, size attributes, colour attributes, etc. As such it shall implement all inherited attributes, operations and associations. " |
AnchorPoint
A :AnchorPoint gives the locaiton inside of a Graphic Object to use for anchor the graphic object to the main-geometry point. The coordinates are give as two floating-point numbers in th AnchorPointX and AnchorPointY elements each with values between 0.0 and 1.0 inclusive. The default point is X=0.5, Y=0.5, which is at the middle height and middle length of the graphic/label text.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:anchorPointX |
The x-coordinate location inside object to use for anchoring to main geometry point |
AnchorPoint |
0..1 (optional) |
:anchorPointY |
The y-coordinate location inside object to use for anchoring to main geometry point |
AnchorPoint |
0..1 (optional) |
Stroke
A :Stroke is a :GraphicProperty that describes a linear stroke. The :GraphicStroke element describes graphics repeated linearly and is described below. There are three basic types of strokes: solid-color, GraphicFill (stipple), and repeated linear GraphicStroke. A repeated linear graphic is plotted linearly and has its graphic Symbolizer bent around the curves of the line string, and a graphic fill has the pixels of the line rendered with a repeating area-fill pattern. If neither a GraphicFill nor GraphicStroke element is given, then the LineStyle will render a solid color.
Note
|
The term :Stroke is defined in SE as a "graphical element of the LineSymbolizer that encapsulates the graphical-Symbolization parameters for linear geometries." |
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:graphicStroke |
A graphic to be used instead of a stroke |
:GraphicStroke |
0..n (optional) |
:graphicFill |
A graphic to be repeated in the area instead of a solid fill color |
:GraphicFill |
0..1 (optional) |
:stroke-color |
Color |
xsd:cssColorLiteral |
0..1 (optional) |
:hasStrokeColor |
Color |
:Color |
0..1 (optional) |
:stroke-opacity |
Opacity |
xsd:decimal, 0.0 to 1.0, representing percent opacity |
0..1 (optional) |
:stroke-width |
Width |
xsd:decimal, Non-negative real number in pixels. |
0..1 (optional) |
:stroke-linecap |
Linecap |
xsd:string, either “butt”, “round”, or “square” |
0..1 (optional) |
:stroke-linejoin |
Linejoin |
:Linejoin, either "miter", "round", or "bevel" |
0..1 (optional) |
:stroke-dasharray |
Dash array – a sequence of distances (dash, space, dash, etc.) to draw |
xsd:string of separated non-negative real numbers in pixels |
0..1 (optional) |
:stroke-dashoffset |
Dash offset – the distance into the dasharray at which to start drawing |
xsd:decimal, Non-negative real number in pixels |
0..1 (optional) |
GraphicStroke
A :GraphicStroke is a :GraphicProperty that describes a graphic symbol repeated linearly. It contains a Graphic symbol and may contain an InitialGap and/or Gap if relevant. The :graphicSymbol specifies the linear :GraphicSymbol. Proper stroking with a linear graphic symbol requires two “hot-spot” points within the space of the graphic symbol to indicate where the rendering line starts and stops. In the case of raster images with no special mark-up, this line will be assumed to be middle pixel row of the image, starting from the first pixel column and ending at the last pixel column. GraphicStrokes should not be used for Strokes that are part of Marks
Note
|
The term :GraphicStroke is defined in SE with the same definition. |
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:graphicSymbol |
The linear graphic symbol to be drawn |
:GraphicSymbol |
1..n (mandatory) |
:initialGap |
How far away the first graphic symbol will be drawn relative to the start of the rendering line |
xsd:decimal, Non-negative real number in pixels |
0..n (optional) |
:gap |
Distance between two graphic symbols |
xsd:decimal, Non-negative real number in pixels |
0..n (optional)) |
Fill
A :Fill is a :GraphicProperty that describes a graphic symbol repeated linearly. It contains a Graphic symbol and may contain an InitialGap and/or Gap if relevant. The :hasGraphicSymbol specifies the linear :GraphicSymbol. Proper stroking with a linear graphic symbol requires two “hot-spot” points within the space of the graphic symbol to indicate where the rendering line starts and stops. In the case of raster images with no special mark-up, this line will be assumed to be middle pixel row of the image, starting from the first pixel column and ending at the last pixel column. GraphicStrokes should not be used for Strokes that are part of Marks
Note
|
The term :Fill is defined in SE with the same definition. |
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:hasFillColor |
Color |
:Color |
0..1 (optional) |
:fill-color |
Color |
:cssColorLiteral |
0..1 (optional) |
:fill-opacity |
Opacity |
xsd:decimal, 0.0 to 1.0, representing percent opacity |
0..1 (optional) |
GraphicFill
A :GraphicFill is a :GraphicProperty that describes the graphic that will be used to fill the area of a polygon. GraphicFills should not be used for Strokes that are part of Marks.
Note
|
The term :GraphicFill is defined in SE with the same definition. |
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:graphicSymbol |
The linear graphic symbol to be drawn. |
:GraphicSymbol |
1..n (mandatory) |
Font
A :Font is a :GraphicProperty used to represent text or symbols.
Note
|
The term :Font is defined in SE as an element that "identifies a font of a certain family, style, and size". Four types of SvgParameter are allowed, “font-family”, “font-style”, “font-weight”, and “font-size”. |
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:font-family |
gives the family name of a font to use |
:FontFamily |
0..n (optional) |
:font-style |
gives the style to use for a font. |
xsd:string, with the allowed values being “normal”, “italic”, and “oblique” |
0..1 (optional) |
:font-size |
gives the size to use for the font in pixels |
xsd:decimal |
0..1 (optional) |
:font-weight |
gives the amount of weight or boldness to use for a font |
xsd:string, with allowed values being "normal" or "bold" |
0..1 (optional) |
:hasFillColor |
Color |
:Color |
0..1 (optional) |
:fill-color |
Color |
:cssColorLiteral |
0..1 (optional) |
LabelPlacement
The :LabelPlacement element is used to position a label relative to a graphic object. It is superclass of :PointPlacement and :LinePlacement.
LinePlacement
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:initialGap |
How far away the first label will be drawn relative to the start of the rendering line |
xsd:decimal, Non-negative real number in pixels |
0..1 (optional) |
:gap |
Distance between two labels |
xsd:decimal, Non-negative real number in pixels |
0..1 (optional)) |
:perpendicularOffset |
gives the perpendicular distance away from a line to draw a label |
:uoms |
0..1 (optional)) |
:generalizeLine |
The boolean generalizeLine property allows the actual geometry, be it a linestring or polygon to be generalized for label placement. This is for example useful for labeling polygons inside their interior when there is need for the lavel to ressemble the shape of polygon. (See OGC Symbology Encoding) |
xsd:booolean |
0..1 (optional)) |
:isAligned |
boolean indicating is the label is aligned with the line |
xsd:boolean |
0..1 (optional)) |
:isRepeated |
If IsRepeated is 'true', the label will be repeatedly drawn along the line with InitialGap and Gap defining the spaces at the beginning and between labels. |
xsd:boolean |
0..1 ) |
PointPlacement
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:rotation |
Clockwise rotation about the graphic object’s anchor point |
xsd:decimal (real number in degrees) |
0..1 (optional) |
:anchorPointX |
The x-component of the location inside object to use for anchoring to main geometry point |
xsd:decimal |
0..1 (optional) |
:anchorPointY |
The y-component of the location inside object to use for anchoring to main geometry point |
xsd:decimal |
0..1 (optional) |
:displacementX |
The x-component of the displacement from “hot-spot” point |
xsd:decimal |
0..1 (optional) |
Halo
A :Halo is a type of Fill that is applied to the backgrounds of font glyphs. The use of halos greatly improves the readability of text labels. .Properties of the Halo Class
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:fill |
Halo fill |
:Fill |
0..1 (optional) |
:radius |
ves the absolute size of a halo radius in pixels encoded as a floating-point number. |
xsd:decimal |
0..1 (optional) |
Transformation
A :Transformation is a :GraphicProperty used to apply a type of transformation, such as scaling, translation, or rotation, to a graphic object.
The Size element gives the absolute size of the graphic object in uoms encoded as a floating-point number. The default size for an object is context-dependent. Negative values are not allowed. The default size of an image format (such as GIF) is the inherent size of the image. The default size of a format without an inherent size (such as SVG which are not specially marked) is defined to be 16 pixels in height and the corresponding aspect in width. If a size is specified, the height of the graphic object will be scaled to that size and the corresponding aspect will be used for the width. An expected common use case will be for image graphics to be on the order of 200 pixels in linear size and to be scaled to lower sizes. On systems that can resample these graphic objects “smoothly,” the results will be visually pleasing.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:scaleX |
Scale factor on the X-axis direction." The default value is 0.0 |
xsd:decimal |
1 |
:scaleY |
Scale factor on the Y-axis direction." The default value is 0.0 |
xsd:decimal |
1 |
The Rotation element is a basic transformation that gives the rotation of a graphic object in the clockwise direction about its center point in decimal degrees, encoded as a floating-point number. Negative values mean counter-clockwise rotation. The default value is 0.0 (no rotation). Note that there is no connection between source geometry types and rotations; the point used for plotting has no inherent direction. Also, the point within the graphic object about which it is rotated is format dependent. If a format does not include an inherent rotation point, then the point of rotation should be the centroid.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:rotation |
Rotation angle in the clockwise direction about its center point in decimal degrees, encoded as a floating-point number. Negative values mean counter-clockwise rotation. The default value is 0.0 (no rotation). |
xsd:decimal |
1 |
The Translation gives the X and Y displacements from the “hot-spot” point. This element may be used to avoid over-plotting of multiple graphic objects used as part of the same point symbol. The displacements are in units of measure above and to the right of the point. The default displacement is X=0, Y=0. If Displacement is used in conjunction with Size and/or Rotation then the graphic object shall be scaled and/or rotated before it is displaced. The term displacement, in this case, is synonymous to translation.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:displacementX |
Displacement on the X-axis direction." The default value is 0.0 |
xsd:decimal |
1 |
:displacementY |
Displacement on the Y-axis direction." The default value is 0.0 |
xsd:decimal |
1 |
A composite transformation is two or more transformations performed one after the other in order of the list.
Property | Usage Note | Range | Multiplicity and use |
---|---|---|---|
:operations |
Transformation operation list executed in order of the list |
rdf:List of Transformation instance |
1 |
Appendix D: Semantic Registry Service REST API v0.1
Overview
This document describes the initial version of RESTful Semantic Registry Service API. We anticipate that a variety of clients may be using the Semantic Registry Service, and as a consequence it is difficult to accommodate the needs of every type of client. It is almost certain that the REST API will evolve and be modified as more requirements and features are added to the service. The hypermedia-driven API provides a robust approach to evolve the API without breaking the client ecosystem, as long as the clients are using the semantics of the link relation types. For this reason, the service has adopted a hypermedia-driven RESTful API by default, which meets level 3 of the Richardson Maturity Model.
The default serialization of the information model in the service is JSON, as it is understood by most programming languages. However, to support machine-processable information, we enforce the JSON to be compatible with Linked data by using JSON-LD Context. In this way, data can be converted to Linked Data Representation and be reasoned on and linked to other information expressed as Linked Data. The REST API does support content negotiation to return a response in Linked Data Format (RDF/XML, Turtle, NTriple) when applicable (Register and Item at this point of time). This REST API provides the core minimum functionalities that are based on the Semantic Registry Information Model (SRIM) Application Profile.
The Semantic Registry Service provides a set of core resources (Registers, Items, SPARQL endpoint). This set of core resources has been extended to support a Harvester service that enables the population of the registry by collecting information from multiple sources such as OGC Catalog Services, CKAN, or Web Accessible Folder (WAF).
Note
|
The example URL used in this documentation uses the baseURL http://localhost:8080. This baseURL should be replaced by the entry point (baseURL) of the service that you want to access in the format: http://{hostname}:{port}/{rootPath} |
HTTP Verbs
The RESTful API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs. The following HTTP verbs are used by the Service.
Verb | Usage |
---|---|
|
Used to retrieve a resource |
|
Used to create a new resource |
|
Used to update an existing resource |
|
Used to delete an existing resource |
HTTP Status Codes
The Service REST API tries to adhere as closely as possible to the standard HTTP and REST conventions in its use of HTTP status codes. The following table summarizes the status codes and usage.
Status code | Usage |
---|---|
|
The request completed successfully |
|
A new resource has been created successfully. The resource’s URI is available from the response’s
|
|
An update to an existing resource has been applied successfully |
|
The request was malformed. The response body will include an error providing further information |
|
The requested resource did not exist |
|
A request was made of a resource using a method not supported by that resource; for example, using GET on a form which requires data to be presented via POST, or using PUT on a read-only resource. |
|
The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. |
|
The server is refusing to service the request because the method on the requested resource does not accept a request in that format. |
|
The web server encountered an unexpected condition that prevented it from fulfilling the request. |
Headers
Every response has the following header:
Name | Description |
---|---|
|
The Content-Type of the payload, e.g. |
Future headers may be added for managing access control to the resources managed by the service.
Errors
Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:
Path | Type | Description |
---|---|---|
|
Number |
The HTTP status code, e.g. |
|
String |
The HTTP error that occurred, e.g. |
|
String |
A description of the cause of the error |
|
String |
The path to which the request was made |
|
String |
The date and time at which the error occurred |
For example, a request that attempts to apply a non-existent resource to a register item will produce the
400 Bad Request
response:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 189
{
"status" : 400,
"error" : "Bad Request",
"message" : "The resource item 'http://localhost:8080/items/123' does not exist",
"path" : "/items",
"timestamp" : "2016-09-30T18:37:25.119+0000"
}
Paging and Sorting
Paging
Rather than returning everything from a large result set, the REST API recognizes some URL parameters that will influence the page size (size
parameter), the starting page number (page
parameter), and the sorting of the result set (sort
parameter).
See the following example, where we set the page size to 5 and request the third page (page 2) as page numbers are zero-indexed:
GET items?page=2&size=5 HTTP/1.1
Host: localhost
The request returns the following paginated results in HAL format:
{
"_embedded": {
...data...
},
"_links": {
"self": {
"href": "http://localhost:8080/items"
},
"first": {
"href": "http://localhost:8080/items?page=0&size=5"
},
"prev": {
"href": "http://localhost:8080/items?page=1&size=5"
},
"next": {
"href": "http://localhost:8080/items?page=3&size=5"
},
"last": {
"href": "http://localhost:8080/items?page=5&size=5"
},
},
"page": {
"size": 5,
"totalElements": 27,
"totalPages": 6,
"number": 2
}
}
Each paged response will return links to the first, previous, next, and last page of results based on the current page using the IANA defined link relations first
,
prev
,
next
, and
last
. If you are currently at the first page of results, no prev
link will be rendered. The same is true for the last page of results: no next
link will be rendered.
The paginated results also have extra data about the page settings , including the size of a page, total elements, total pages, and the page number you are currently viewing. This extra information makes it very easy for the consumer to configure UI tools like sliders or indicators to reflect the overall position the user is in viewing the data.
Sorting
The REST API recognizes sorting parameters. To have your results sorted on a particular property, add a sort
URL parameter with the name of the property you want to sort the results on. You can control the direction of the sort by appending a ,
to the the property name plus either asc
or desc
.
The following examples will sort results by title in ascending order:
GET /items?sort=title,asc HTTP/1.1
Host: localhost
To sort the results by more than one property, keep adding as many sort=PROPERTY
parameters as you need. They will be added in the order they appear in the query string.
Search Results
A number of endpoints of the service return search results.They usually supports Level 2 (JSON) and Level 3 response (HAL+JSON). The search results contains the collection of matched items, paging information and optionally faceted aggregation results. The following describes the response structure for each format.
HAL+JSON Search Results
Path | Type | Description |
---|---|---|
|
|
The HAL _embedded field that contains a collection of instances |
embedded._collectionName[] |
|
The array of items instances defined a given JSON schema. The collectionName may varied depending of the types of items contained in the collection. |
|
|
The aggregation results as defined in the Aggregation JSON Schema. This field is optional is no faceted search is performed on the endpoint. |
|
|
The name of the aggregation (or facet) |
|
|
The metrics object containing global statistics of the object |
|
|
The total count of the aggregation |
|
|
The array of buckets of the aggregation |
|
|
The label of the bucket |
|
|
The count of the label for the bucket |
|
|
Links to other states |
|
|
The page state. See <<_paging,Paging section> |
|
|
The page size |
|
|
The total elements matched by the search request |
|
|
The total number of pages in the results |
|
|
The current page number (starts at 0) |
|
|
Array of hypermedia links to other reachable states. |
JSON Search results
When the JSON or JSON-LD response is retrieved, the matched items are placed in an array referred by the results field. Aggregations results are present only faceted search is performed and paging information are returned.
Path | Type | Description |
---|---|---|
|
|
The array of vocabulary instances that matches the search criteria |
|
|
The aggregation results as defined in the Aggregation JSON Schema. This field is optional is no faceted search is performed on the endpoint. |
|
|
The name of the aggregation (or facet) |
|
|
The metrics object containing global statistics of the object |
|
|
The total count of the aggregation |
|
|
The array of buckets of the aggregation |
|
|
The label of the bucket |
|
|
The count of the label for the bucket |
|
|
The page state. See <<_paging,Paging section> |
|
|
The page size |
|
|
The total elements matched by the search request |
|
|
The total number of pages in the results |
|
|
The current page number (starts at 0) |
Aggregation JSON Schema
In many use cases, it is useful to aggregate the search results according some facets values (number of items per topic, per publisher, etc). Each facet is composed of a name, global metrics (right now only total count is supported), a set of buckets containing a label (unique value of the facet) and the total count for each label within the context of the facet and search results. The JSON schema of the Aggregation results is defined in the following table.
Path | Type | Description |
---|---|---|
|
|
The aggregation results |
|
|
The name of the aggregation (or facet) |
|
|
The metrics object containing global statistics of the object |
|
|
The total count of the aggregation |
|
|
The array of buckets of the aggregation |
|
|
The label of the bucket |
|
|
The count of the label for the bucket |
Resources Summary
The following resources are the core resources supported by the Semantic Registry Service. Details of these resources are described in the Semantic Registry Resources section.
Resources | Description | Operations |
---|---|---|
Capabilities |
This resource describes the capabilities of the service |
|
Registers |
Represents a collection of registers which can be searched through based on search criteria. Also supports creation of a register instance. |
|
Register |
This resource supports retrieval update, and deletion of a register instance |
|
Items |
Represents a collection of register items which can be searched through based on search criteria. Also supports creation of an item instance. |
|
Item |
This resource supports retrieval update, and deletion of an item instance |
|
JSON-LD Context |
This resource returns the JSON-LD context associated with the JSON representation returned by the service |
|
SPARQL |
This resource provides a SPARQL service query endpoint |
|
The following resources are the core resources supported by the Harvester Service. Details of these resources are described in the Harvester Service Resources section.
Resources | Description | Operations |
---|---|---|
Harvester Types |
This resource represents the collection of harvester types supported by the service. An harvester type provides the parameter definitions needed to configure a harvester source |
|
Harvester Type |
This resource represents a harvester type definition, from which Harvester Source instance can be created. |
|
Harvester Sources |
This resource represents the collection of harvester sources that describe the source to be harvested. A harvester source defines the parameter values needed to configure the harvester source |
|
Harvester Source |
This resource represents an instance of a harvester source |
|
Link Relation Types
The following table describes the list of link relation types used by the Semantic Registry Service when using a Hypermedia format such as HAL. We use the OGC namespace to define the relationships that can be reused by other services such as apiDocumentation, jsonldContext, and sparql endpoints. The links specific to the semantic registry service have the following relation type URI template: http://www.opengis.net/rels/registry/{rel}.
Relation type | URI | Description |
---|---|---|
|
Reference to the capabilities of the service |
|
|
Reference to the registers collection |
|
|
Reference to a register |
|
|
Reference to an item collection |
|
|
Reference to an item |
|
|
Reference to the harvester service |
|
|
Reference to a SPARQL Service Endpoint ** |
|
|
Reference to the JSON-LD context, that when applied to the JSON Content, transforms it to Linked Data |
|
|
Reference to the REST documentation of the service |
The following table describes the list of link relation types used by the Harvester Service used to populate the registry. The links specific to the harvester service have the following relation type URI template: http://www.opengis.net/rels/harvester/{rel}.
Relation type | URI | Description |
---|---|---|
|
Reference to the harvester service |
|
|
Reference to the harvester type collection |
|
|
Reference to the harvester type instance associated with a harvester source |
|
|
Reference to the harvest operation associated with a harvester source |
|
|
Reference to the harvester sources collection |
|
|
Reference to the harvester results collection (future extension) |
|
|
Reference to the harvester objects collection (future extension) |
Level 2 REST Endpoints
The following table describes the endpoint URL paths for each resource. These paths are considered NON-NORMATIVE but rather INFORMATIVE, as changes of path templates may occur in the future, requiring updates of clients and version control of APIs. The use of hypermedia REST API is advised to be isolated from these changes. However we provide this information to support frameworks that work with Level 2 REST API (such as AngularJS)
Path | HTTP Methods | Consume | Produce |
---|---|---|---|
/ |
GET,HEAD |
application/hal+json |
|
/capabilities |
GET,HEAD |
|
|
/harvesters |
GET,HEAD |
application/hal+json |
|
/harvesters/harvest |
POST |
application/json |
|
/harvesters/sources |
GET,HEAD |
|
|
/harvesters/sources |
POST |
application/json |
|
/harvesters/sources/{id} |
DELETE |
||
/harvesters/sources/{id} |
GET,HEAD |
|
|
/harvesters/sources/{id} |
PUT |
application/json |
|
/harvesters/sources/{id}/harvest |
GET,HEAD |
|
|
/harvesters/types |
GET,HEAD |
|
|
/harvesters/types/{id} |
GET,HEAD |
|
|
/items |
GET,HEAD |
|
|
/items |
POST |
|
|
/items/instance |
GET,HEAD |
|
|
/items/{id} |
DELETE |
application/hal+json |
|
/items/{id} |
GET,HEAD |
|
|
/items/{id} |
PUT |
application/json |
|
/registers |
GET,HEAD |
|
|
/registers |
POST |
application/json |
|
/registers/{id} |
DELETE |
||
/registers/{id} |
GET,HEAD |
|
|
/registers/{id} |
PUT |
application/json |
|
/registers/{id}/items |
GET,HEAD |
|
|
/registers/{id}/items |
POST |
application/json |
|
/registers/{id}/sparql |
GET,HEAD |
|
|
/registers/{id}/sparql |
POST |
|
|
/registers/{registerId}/items/{itemId} |
DELETE |
||
/registers/{registerId}/items/{itemId} |
PUT |
||
/sparql |
GET,HEAD |
|
|
/sparql |
POST |
|
|
Content Negotiation
Many of the resources can serve multiple representations including:
Format | Mime type | Description |
---|---|---|
HAL+JSON |
|
It is the default format of the service. The JSON payload is compatible with JSON-LD and is aligned with the SRIM Core Ontology. |
JSON-LD |
|
Compliant with the SRIM Core Ontology using the JSON-LD context. |
RDF/XML |
|
Compliant with the SRIM Core Ontology |
Turtle |
|
Compliant with the Core SRIM Application Profile Ontology |
N-Triples |
|
Compliant with the Core SRIM Application Profile Ontology |
Semantic Registry Resources
This section describes the list of resources made accessible by the Semantic Registry Service. The RESTful API has an entry point (service root) which provides links that represent the current state transitions supported by the service.
Service Root
The root is the entry point of the RESTful Semantic Registry service. When the client consumes the API for the first time, it comes in contact with the root. If the HATEOAS constraint is to be considered and implemented throughout by clients, then this is the place to start. The root endpoint provides a set of links with well-defined relation types that correspond to the supported capabilities of the service. As the Semantic Registry Service API evolves in the future, there may be additional links, each with its own semantics defined by the type of link relation.
The API is considered RESTful as it is fully discoverable from the root with no prior knowledge – meaning the client should be able to navigate the API by doing a GET on the root. Moving forward, all state changes are driven by the client using the available and discoverable transitions that the REST API provides in representations (hence Representational State Transfer).
Accessing the root endpoint
To get access to the root of the service and get the list of links, a GET
request is sent to the base url of the service.
Request Structure
This request sends a 'GET' request to the base url of the service. Here the HTTP request returns the list of links supported by the service:
GET / HTTP/1.1
Host: localhost
Query Parameters
None
Response Structure
The request returns a HAL response (application/hal+json) with a _links object that contains links associated with relation types (used as property names in JSON).
Path | Type | Description | Card. |
---|---|---|---|
|
|
ItemClass of the registry (always srim:Service) |
1 |
|
|
Human readable title of the registry service |
1 |
|
|
Human readable description of the registry service |
1 |
|
|
Current version of the registry service |
1 |
|
|
URL of the category of the registry service. Set right now to fixed value: http://www.opengis.net/specs/testbed12/semanticRegistry. |
1 |
|
|
Information about the publisher(s) of this software |
0..1 |
|
|
URI identifier for the publisher |
0..1 |
|
|
Name of the publisher |
1 |
|
|
Type of the publisher (org:Organization or foaf:Person) |
1 |
Links
The following table describes the current link relation types supported by the service when using Hypermedia REST format (such as HAL).
Relation | Description |
---|---|
|
Refers to the capabilities of the service |
|
Refers to the item search endpoint |
|
Refers to the SPARQL search endpoint |
|
Refers to the JSON context of the items in the registry |
|
Refers to the register search endpoint |
|
Refers to the harvesters endpoint |
|
Refers to this endpoint. |
|
Refers to the curies defined for the links |
Example Response
The following example response in HAL+HJSON shows the response of the get operation at the service entry point.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1148
{
"type" : "srim:Service",
"title" : "Semantic Registry Service",
"description" : "Semantic Registry Service prototype for OGC Testbed12",
"category" : [ "http://www.opengis.net/specs/testbed12/semanticRegistry" ],
"publisher" : [ {
"name" : "Image Matters LLC",
"uri" : "http://www.imagemattersllc.com",
"type" : "org:Organization"
} ],
"version" : "0.1",
"_links" : {
"registry:capabilities" : {
"href" : "http://localhost:8080/capabilities"
},
"registry:items" : {
"href" : "http://localhost:8080/items"
},
"registry:sparql" : {
"href" : "http://localhost:8080/sparql"
},
"registry:jsonldContext" : {
"href" : "http://localhost:8080/context"
},
"registry:registers" : {
"href" : "http://localhost:8080/registers"
},
"registry:harvester" : {
"href" : "http://localhost:8080/harvesters"
},
"self" : {
"href" : "http://localhost:8080"
},
"curies" : [ {
"href" : "http://www.opengis.net/rels/registry/{rel}",
"name" : "registry",
"templated" : true
} ]
}
}
Capabilities
This resource describes the capabilities of the service, including the supported application profiles, formats, and languages.
Query Parameters
None.
Example Request
The following is an example of a GET Request performed on the Capability resource.
GET /capabilities HTTP/1.1
Host: localhost
Response Structure
The response of a Capability request has the following structure:
Path | Type | Description |
---|---|---|
|
|
ItemClasses supported by the registry |
|
|
The ID of the ItemClass |
|
|
The URI of the ItemClass |
|
|
The RDF type of the ItemClass (always srim:ItemClass) |
|
|
The human readable title of the ItemClass |
|
|
The human readable description of the ItemClass |
|
|
Application profiles supported by the registry |
|
|
The URI of the application profile |
|
|
The human readable label of the application profile |
|
|
The human readable description of the application profile |
|
|
The supported languages (dct:LinguisticSystem) supported by the vocabulary manager |
|
|
The uri of the language. This uri should be used as reference in the vocabulary metadata |
|
|
The RDF type of the Linguistic System (always dct:LinguisticSystem) |
|
|
The human readable label of the language |
|
|
The ISO 639-1 code (2 letter code) |
|
|
The ISO 639-2 code (3 letter code) |
|
|
The hypermedia links to other states |
Links
The following table describes the current link relation types in the HAL capabilities response
Relation | Description |
---|---|
|
TODO |
|
TODO |
|
Refers to this endpoint. |
|
Refers to the curies defined for the links |
Example Response
The following is an example of the response from a GET Request performed on the Capability Resource.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 30456
{
"itemClasses" : [ {
"id" : "dcat:Dataset",
"uri" : "http://www.w3.org/ns/dcat#Dataset",
"type" : "srim:ItemClass",
"title" : "Dataset",
"description" : "Dataset class"
}, {
"id" : "srim:Service",
"uri" : "http://www.opengis.net/ont/testbed12/srim#Service",
"type" : "srim:ItemClass",
"title" : "Service",
"description" : "Service class"
}, {
...
The response is quite lengthy, so has been truncated here. The full response is available in separate document.
JSON-LD Context
The JSON produced by the Semantic Registry Service is compatible with the SRIM Application Profile by using JSON-LD context. The context is made accessible through an endpoint, so it can be referred and imported by a JSON-LD processor. The processor can then convert the context into a Linked Data representation adhering to the SRIM Profile. The JSON-LD context should be updated to accomodate the mapping of the different profiles supported by the service.
Query Parameters
None
Example Request
The following is an example of a GET Request performed on the JSON-LD context resource.
GET /context HTTP/1.1
Host: localhost
Response Structure
The response of the JSON-LD Context conformst to the JSON-LD standard.
Path | Type | Description |
---|---|---|
|
|
Context for Item objects in the register |
Example Response
The following example response shows a JSON-LD context of the service.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 10757
{
"@context": {
"pav": "http://purl.org/pav/",
"dct": "http://purl.org/dc/terms/",
"owl": "http://www.w3.org/2002/07/owl#",
"xsd": "http://www.w3.org/2001/XMLSchema#",
"skos": "http://www.w3.org/2004/02/skos/core#",
"srim": "http://www.opengis.net/ont/testbed/12/srim#",
"rdfs": "http://www.w3.org/2000/01/rdf-schema#",
"dcat": "http://www.w3.org/ns/dcat#",
"iso639-2": "http://id.loc.gov/vocabulary/iso639-2/",
"lingvoj": "http://www.lingvoj.org/ontology#",
"foaf": "http://xmlns.com/foaf/0.1/",
"ldp": "http://www.w3.org/ns/ldp#",
"locn": "http://www.w3.org/ns/locn#",
"adms": "http://www.w3.org/TR/vocab-adms/#",
"extent": "http://www.opengis.net/ont/extent#",
"idvoc": "http://www.opengis.net/ont/identifier#",
"link": "http://www.opengis.net/ont/link#",
"gr": "http://www.heppnetz.de/ontologies/goodrelations/v1#",
"org": "http://www.socialml.org/ontologies/organization#",
"schema": "http://www.opengis.net/ont/testbed12/srim/profile/schema#",
"vcard": "http://www.w3.org/2006/vcard/ns#",
"type": "@type",
"uri": {
"@id": "rdf:id",
"@container": "@language"
},
"value": "@value",
"lang": "@language",
"results": "ldp:contains",
"title": "dct:title",
"titleMap": {
"@id": "dct:title",
"@container": "@language"
},
"description": "dct:description",
"descriptionMap": {
"@id": "dct:description",
"@container": "@language"
},
"prefLabel": "skos:prefLabel",
"prefLabelMap": {
"@id": "skos:prefLabel",
"@container": "@language"
},
"notation": "skos:notation",
"notationMap": {
"@id": "skos:notation",
"@container": "@language"
},
"category": {
"@id": "dct:type",
"@type": "@id"
},
"hasVersion": "pav:hasVersion",
"hasCurrentVersion": {
"@id": "pav:hasCurrentVersion",
"@type": "@id"
},
"version": "pav:version",
"creator": {
"@id": "dct:creator",
"@type": "@id"
},
"versionNotes": "adms:versionNotes",
"versionNotesMap": {
"@id": "adms:versionNotes",
"@container": "@language"
},
"versionOf": {
"@id": "pav:versionOf",
"@type": "@id"
},
"contributor": {
"@id": "dct:contributor",
"@type": "@id"
},
"publisher": {
"@id": "dct:publisher",
"@type": "@id"
},
"language": {
"@id": "dct:language",
"@type": "@id"
},
"iso2Code": "lingvoj:iso1",
"iso3Code": "lingvoj:iso2",
"label": "rdfs:label",
"name": "foaf:name",
"nameMap": {
"@id": "foaf:name",
"@container": "@language"
},
"sameAs": {
"@id": "owl:sameAs",
"@type": "@id"
},
"distribution": {
"@id": "dcat:distribution",
"@type": "@id"
},
"license": {
"@id": "dct:license",
"@type": "@id"
},
"created": "dct:created",
"issued": "dct:issued",
"modified": "dct:modified",
"accessURL": {
"@id": "dcat:accessURL",
"@type": "@id"
},
"mediaType": "dcat:mediaType",
"country-name": "vcard:country-name",
"region": "vcard:region",
"locality": "vcard:locality",
"postal-code": "vcard:postal-code",
"street-address": "vcard:street-address",
"format": {
"@id": "dct:format",
"@type": "@id"
},
"agent": {
"@id": "prov:agent",
"@type": "@id"
},
"role": {
"@id": "prov:role",
"@type": "@id"
},
"inScheme": {
"@id": "skos:inScheme",
"@type": "@id"
},
"byteSize": "dcat:byteSize",
"conformsTo": {
"@id": "dct:conformsTo",
"@type": "@id"
},
"page": {
"@id": "foaf:page",
"@type": "@id"
},
"rights": {
"@id": "dct:rights",
"@type": "@id"
},
"representationTechnique": {
"@id": "adms:representationTechnique",
"@type": "@id"
},
"hasValue": {
"@id": "vcard:hasValue",
"@type": "@id"
},
"northBoundLatitude": "extent:northBoundLatitude",
"southBoundLatitude": "extent:southBoundLatitude",
"westBoundLongitude": "extent:westBoundLongitude",
"eastBoundLongitude": "extent:eastBoundLongitude",
"code": "id:code",
"codespace": {
"@id": "id:codespace",
"@type": "@id"
},
"authority": {
"@id": "id:authority",
"@type": "@id"
},
"landingPage": {
"@id": "dcat:landingPage",
"@type": "@id"
},
"accrualPeriodicity": {
"@id": "dct:accrualPeriodicity",
"@type": "@id"
},
"purpose": "srim:purpose",
"accessLevel": {
"@id": "srim:accessLevel",
"@type": "@id"
},
"itemClass": {
"@id": "srim:itemClass",
"@type": "@id"
},
"keyword": "dcat:keyword",
"identifier": "dct:identifier",
"hasLink": {
"@id": "link:hasLink",
"@type": "@id"
},
"theme": {
"@id": "dcat:theme",
"@type": "@id"
},
"audience": {
"@id": "dct:audience",
"@type": "@id"
},
"function": {
"@id": "srim:function",
"@type": "@id"
},
"subject": {
"@id": "dct:subject",
"@type": "@id"
},
"project": {
"@id": "foaf:project",
"@type": "@id"
},
"hasIdentifier": {
"@id": "id:hasIdentifier",
"@type": "@id"
},
"depiction": {
"@id": "foaf:depiction",
"@type": "@id"
},
"provenance": {
"@id": "dct:provenance",
"@type": "@id"
},
"contactPoint": {
"@id": "dcat:contactPoint",
"@type": "@id"
},
"hasGeographicExtent": {
"@id": "extent:hasGeographicExtent",
"@type": "@id"
},
"temporal": {
"@id": "dct:temporal",
"@type": "@id"
},
"spatial": {
"@id": "dct:spatial",
"@type": "@id"
},
"accessRights": {
"@id": "dct:accessrights",
"@type": "@id"
},
"qualifiedAttribution": {
"@id": "prov:qualifiedAttribution",
"@type": "@id"
},
"rightsHolder": {
"@id": "dct:rightsHolder",
"@type": "@id"
},
"servicedBy": {
"@id": "srim:servicedBy",
"@type": "@id"
},
"operatesOn": {
"@id": "srim:operatesOn",
"@type": "@id"
},
"relation": {
"@id": "dct:relation",
"@type": "@id"
},
"technicalStandard": {
"@id": "srim:technicalStandard",
"@type": "@id"
},
"hrefLang": {
"@id": "link:hrefLang",
"@type": "@id"
},
"href": {
"@id": "link:href",
"@type": "@id"
},
"rel": {
"@id": "link:rel",
"@type": "@id"
},
"geographicName": "locn:geographicName",
"opens": "gr:opens",
"closes": "gr:closes",
"hasOpeningHoursDayOfWeek": "gr:hasOpeningHoursDayOfWeek",
"subOrganizationOf": {
"@id": "org:subOrganizationOf",
"@type": "@id"
},
"startDate": "schema:startDate",
"endDate": "schema:endDate",
"alias": "srim:alias",
"themeTaxonomy": {
"@id": "dcat:themeTaxonomy",
"@type": "@id"
},
"entry": {
"@id": "srim:entry",
"@type": "@id"
},
"item": {
"@id": "srim:item",
"@type": "@id"
},
"status": "srim:status",
"previousVersion": {
"@id": "pav:previousVersion",
"@type": "@id"
},
"wasGeneratedBy": {
"@id": "pav:wasGeneratedBy",
"@type": "@id"
},
"source": {
"@id": "schema:source",
"@type": "@id"
},
"primaryTopic": {
"@id": "foaf:primaryTopic",
"@type": "@id"
},
"itemType": {
"@id": "srim:itemType",
"@type": "@id"
},
"organization-name": "vcard:organization-name",
"address": {
"@id": "vcard:address",
"@type": "@id"
},
"fn": "vcard:fn",
"hasEmail": {
"@id": "vcard:hasEmail",
"@type": "@id"
},
"vcardTitle": "vcard:title",
"hasTelephone": {
"@id": "vcard:hasTelephone",
"@type": "@id"
},
"hasOpeningHoursSpecification": {
"@id": "gr:hasOpeningHoursSpecification",
"@type": "@id"
},
"target": {
"@id": "schema:target",
"@type": "@id"
},
"mappingLanguage": {
"@id": "schema:mappingLanguage",
"@type": "@id"
},
"namespace": {
"@id": "schema:namespace",
"@type": "@id"
},
"alternative": "dct:alternative",
"releaseIssued": "dct:issued",
"characterSet": {
"@id": "srim:characterSet",
"@type": "@id"
},
"source": {
"@id": "dct:source",
"@type": "@id"
}
}
}
Registers
A Register is a curated collection of metadata about items stored in a repository (registry) to enable search and discovery of items. The Registers Resource represents a collection of Register instances, and it is used to create and list registers. For example, one register can contain datasets with associated services, while another manages schema and schema mappings, and another manages portrayal information.
Register JSON Schema
The JSON representation of the Register instance is defined by the following JSON schema that are accessible at the following endpoints:
Path | Type | Description |
---|---|---|
|
|
Internal identifier for the register, used by the registry |
|
|
Unique identifier for the register |
|
|
Alias (alternate name) for the register |
|
|
The RDF type of the register |
|
|
The title of the register |
|
|
The title map for each language of the title |
|
|
The description of the register |
|
|
The description map for each language of the description |
|
|
The date of creation of the register in the service (XSD datetime format) |
|
|
The date of the last modification of the register in the service (XSD datetime format) |
|
|
The date of publication of the register (XSD datetime format) |
|
|
URL pointing to the landing page of the register |
|
|
Languages of the register |
|
|
Theme taxonomy of the register (array of ConceptSchemes) |
|
|
The non-Item entries in the register |
|
|
The ItemClasses of the items in the register |
|
|
The items in the register |
|
|
The agent that published the register |
|
|
The rights statement associated with the register |
|
|
Period of time relevant to the register |
|
|
Locations relevant to the register |
|
|
Standard the register conforms to |
|
|
License document associated with the register |
|
|
The hypermedia links to other states |
Search registers
A GET
request on the Registers resource provides a list of all of the registers currently managed by the service.
Query Parameters
Parameter | Description |
---|---|
|
Text to search in textual fields |
|
One or more categories |
|
One or more languages |
|
One or more URIs of register instances |
|
One or more id of register instances |
|
Boolean or list of facet names to include for aggregation computation. If the value is true, include all facets supported by the server. If only a subset of the facets are needed, a comma delimited of field names can be set. |
|
Constraint values of a given facet field name |
|
A constraint expressed in CQL. This is used to express more advanced query filtering |
|
One or more fields to be included in the response. Use JSON path dot notation for referrence paths (ex: publisher.name) |
|
The number of the current page as defined in the Paging section |
|
The count of items on the current page as defined in the Paging section |
|
The sorting parameters as defined in the Sorting section. |
Example request
The following is an example of a GET Request performed on the Registers resource requesting the first page composed of 3 items, which is sorted by title in ascending order.
GET /registers?sort=title%2Casc HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response is structured according to the Register JSON Schema. The default response returns a summary of the register with references to id and title.
Links
The following link relation types are provided in the response to allow the transition to other states from the register collection embedded in the response.
Relation | Description |
---|---|
|
Refers to the registers list itself |
|
Refers to the root of the registry |
|
Refers to the curies defined for the links |
|
The first page of results |
|
The last page of results |
|
The next page of results |
|
The previous page of results |
Example response
======= HAL Representation
The embedded objects in the response of the request conform to the Register Model defined in the Registry JSON Schema. Tne rest of the response return paging information and links to other states. The HAL defined container for the collection of results is called registry:registers and is placed under the HAL _embedded property.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 502
{
"_embedded": {
"registry:registers": [{
"id": "portrayal",
"type": "srim:Register",
"title": "Portrayal Register",
"description": "OGC Testbed 12 Register for portrayal information",
"_links": {
"self": {
"href": "http://localhost:8080/registers/portrayal"
}
}
}, {
"id": "schemas",
"type": "srim:Register",
"title": "Schema Register",
"description": "Register for schemas",
"_links": {
"self": {
"href": "http://localhost:8080/registers/schemas"
}
}
}, {
"id": "datasets",
"type": "srim:Register",
"title": "Testbed12 Datasets Register",
"description": "Testbed 12 catalog for datasets and services harvested from multiple CSW instances",
"_links": {
"self": {
"href": "http://localhost:8080/registers/datasets"
}
}
}]
},
"_links": {
"self": {
"href": "http://localhost:8080/registers?sort=title,asc"
},
"registry:service": {
"href": "http://localhost:8080"
},
"curies": [{
"href": "http://www.opengis.net/rels/registry/{rel}",
"name": "registry",
"templated": true
}]
},
"aggregations": [],
"page": {
"size": 20,
"totalElements": 3,
"totalPages": 1,
"number": 0
}
}
======= JSON Representation
The JSON Representation defines the same content as HAL without the links and the _embedded tag. The content is placed in the results array.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 352
{
"results": [{
"id": "portrayal",
"type": "srim:Register",
"title": "Portrayal Register",
"description": "OGC Testbed 12 Register for portrayal information"
}, {
"id": "schemas",
"type": "srim:Register",
"title": "Schema Register",
"description": "Register for schemas"
}, {
"id": "datasets",
"type": "srim:Register",
"title": "Testbed12 Datasets Register",
"description": "Testbed 12 catalog for datasets and services harvested from multiple CSW instances"
}],
"page": {
"size": 20,
"number": 0,
"totalElements": 3
}
}
Creating a Register
A POST
request is used to create a new Register. The response from this request should have a status code of 201 Created
and contain a
Location
header whose value is the URI of the newly created register. To access the register’s details, either perform a GET
Request on the URI in the Location
header of the response, or just access the details of the register in the body of the response. We decided to have the API return the created representation in the response to prevent an API consumer from having to hit the API again for the newly created representation.
Request structure
The JSON body of the POST request adheres to the Register JSON Schema. The fields are detailed in the following table:
Path | Type | Description |
---|---|---|
|
|
Internal identifier for the register, used by the registry |
|
|
Unique identifier for the register |
|
|
Alias (alternate name) for the register |
|
|
The RDF type of the register |
|
|
The title of the register |
|
|
The title map for each language of the title |
|
|
The description of the register |
|
|
The description map for each language of the description |
|
|
The date of creation of the register in the service (XSD datetime format) |
|
|
The date of the last modification of the register in the service (XSD datetime format) |
|
|
The date of publication of the register (XSD datetime format) |
|
|
URL pointing to the landing page of the register |
|
|
Languages of the register |
|
|
Theme taxonomy of the register (array of ConceptSchemes) |
|
|
The non-Item entries in the register |
|
|
The ItemClasses of the items in the register |
|
|
The items in the register |
|
|
The agent that published the register |
|
|
The rights statement associated with the register |
|
|
Period of time relevant to the register |
|
|
Locations relevant to the register |
|
|
Standard the register conforms to |
|
|
License document associated with the register |
Example request
The following POST request creates a new Register with the title 'NGDA Datasets Register`
POST /registers HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Host: localhost
Content-Length: 202
{
"id" : "urn:example-register-44",
"uri" : "urn:example-register-44",
"type" : "srim:Register",
"title" : "Vocabulary Register",
"description" : "Register for Controlled Vocabularies"
}
Example response
The response returns the URI of the newly created Register in the Location
header with a '201 Created' status code as well as the created Register details in the response body.
HTTP/1.1 201 Created
Location: http://localhost:8080/registers/urn:example-register-44
Content-Type: application/hal+json
Content-Length: 895
{
"id" : "urn:example-register-44",
"uri" : "urn:example-register-44",
"type" : "srim:Register",
"title" : "Vocabulary Register",
"description" : "Register for Controlled Vocabularies",
"issued" : "2016-10-17",
"created" : "2016-10-17T19:28:38.664Z",
"modified" : "2016-10-17T19:28:38.664Z",
"_links" : {
"self" : {
"href" : "http://localhost:8080/registers"
},
"registry:registers" : {
"href" : "http://localhost:8080/registers"
},
"registry:registry" : {
"href" : "http://localhost:8080"
},
"registry:sparql" : {
"href" : "http://localhost:8080/sparql"
},
"registry:items" : {
"href" : "http://localhost:8080/registers/items"
},
"curies" : [ {
"href" : "http://www.opengis.net/rels/registry/{rel}",
"name" : "registry",
"templated" : true
} ]
}
}
Register
The Register resource is used to retrieve, update, and delete a register instance. A Register
is defined as a curated collection of metadata about items stored in a repository (registry) to enable search and discovery of resources. This class is used as a container to exchange registers of resources between registries. Registers can manage different types of resource items such as datasets, map layers or services.
Retrieve a register
A HTTP GET
Request will retrieve a particular instance of register.
Query Parameters
None
Example request
The following HTTP request performs a GET Request to get an instance of a register:
GET /registers/schemas HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response is structured according to the Register JSON Schema.
Links
The following table shows the link relation types accessible from a register instance that provide transitions to other states related to the register instance.
Relation | Description |
---|---|
|
Refers to this item itself |
|
Refers to registers search endpoint |
|
Refers to the root of the registry |
|
Refers to the items within the registry |
|
Refers to the SPARQL endpoint |
|
Refers to the curies defined for the links |
Example responses
======= HAL Representation The response of the request conforms to the Register JSON Schema with additional links.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 895
{
"id": "schemas",
"type": "srim:Register",
"title": "Schema Register",
"description": "Register for schemas",
"issued": "2016-11-08",
"created": "2016-11-08T02:51:42.981Z",
"modified": "2016-11-08T02:51:42.981Z",
"publisher": [{
"name": "Image Matters LLC",
"uri": "http://www.imagemattersllc.com",
"type": "org:Organization"
}],
"itemClass": [
"schema:SchemaMapping",
"schema:Schema"
],
"_links": {
"self": {
"href": "http://localhost:8080/registers/schemas"
},
"registry:registers": {
"href": "http://localhost:8080/registers"
},
"registry:registry": {
"href": "http://localhost:8080"
},
"registry:sparql": {
"href": "http://localhost:8080/schemas/sparql"
},
"registry:items": {
"href": "http://localhost:8080/registers/schemas/items"
},
"curies": [{
"href": "http://www.opengis.net/rels/registry/{rel}",
"name": "registry",
"templated": true
}]
}
}
======= JSON Representation
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 523
{
"id": "schemas",
"type": "srim:Register",
"title": "Schema Register",
"description": "Register for schemas",
"issued": "2016-11-08",
"created": "2016-11-08T02:51:42.981Z",
"modified": "2016-11-08T02:51:42.981Z",
"publisher": [{
"name": "Image Matters LLC",
"uri": "http://www.imagemattersllc.com",
"type": "org:Organization"
}],
"itemClass": [
"schema:SchemaMapping",
"schema:Schema"
]
}
======= Turtle Representation
HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Length: 1366
@prefix org: <http://www.socialml.org/ontologies/organization#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix srim: <http://www.opengis.net/ont/testbed12/srim#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix schema: <http://www.opengis.net/ont/testbed12/srim/profile/schema#> .
[ a srim:Register ;
dct:created "2016-10-10T16:08:19.979Z"^^xsd:dateTime ;
dct:description "Register for schemas" ;
dct:issued "2016-10-10T16:08:19.979Z"^^xsd:date ;
dct:modified "2016-10-10T16:08:19.979Z"^^xsd:dateTime ;
dct:publisher <http://www.imagemattersllc.com> ;
dct:title "Schema Register" ;
srim:itemClass <schema:SchemaMapping> , <schema:Schema>
] .
<http://www.imagemattersllc.com>
a org:Organization ;
foaf:name "Image Matters LLC" .
======= RDF/XML Representation
HTTP/1.1 200 OK
Content-Type: application/rdf+xml
Content-Length: 1609
<?xml version='1.0'?>
<rdf:RDF
xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
xmlns:org='http://www.socialml.org/ontologies/organization#'
xmlns:dct='http://purl.org/dc/terms/'
xmlns:srim='http://www.opengis.net/ont/testbed12/srim#'
xmlns:schema='http://www.opengis.net/ont/testbed12/srim/profile/schema#'
xmlns:dcat='http://www.w3.org/ns/dcat#'
xmlns:foaf='http://xmlns.com/foaf/0.1/'
xmlns:xsd='http://www.w3.org/2001/XMLSchema#'>
<srim:Register>
<dct:title>Schema Register</dct:title>
<dct:description>Register for schemas</dct:description>
<dct:issued rdf:datatype='http://www.w3.org/2001/XMLSchema#date'
>2016-11-07T21:51:42.981-05:00</dct:issued>
<dct:modified rdf:datatype='http://www.w3.org/2001/XMLSchema#dateTime'
>2016-11-07T21:51:42.981-05:00</dct:modified>
<dct:created rdf:datatype='http://www.w3.org/2001/XMLSchema#dateTime'
>2016-11-07T21:51:42.981-05:00</dct:created>
<srim:itemClass rdf:resource='schema:SchemaMapping'/>
<srim:itemClass rdf:resource='schema:Schema'/>
<dct:publisher>
<org:Organization rdf:about='http://www.imagemattersllc.com'>
<foaf:name>Image Matters LLC</foaf:name>
</org:Organization>
</dct:publisher>
</srim:Register>
</rdf:RDF>
Update a Register
A HTTP PUT
request, with a body containing a JSON representation of the Register instance that adheres to the Register JSON Schema, is used to update a Register instance. The response of the request returns the HTTP Status Code 202 (accepted) if the update is accepted.
Request Structure
The request body of the register instance is defined by the Register JSON Schema.
Example Request
The following HTTP request performs a register update using the JSON representation of the register:
PUT /registers/urn:example-register-18 HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Host: localhost
Content-Length: 315
{
"id" : "urn:example-register-18",
"uri" : "urn:example-register-18",
"type" : "srim:Register",
"title" : "New updated title",
"description" : "Register for Controlled Vocabularies",
"issued" : "2016-10-17",
"created" : "2016-10-17T19:28:16.168Z",
"modified" : "2016-10-17T19:28:16.168Z"
}
Example Response
======= HAL+JSON Representation
The response of the request returns the HTTP Status Code 202 (accepted) if the update is accepted, as well as the updated item object so the client can avoid making a second call to get the register. The server shoud add or update the modified field.
HTTP/1.1 202 Accepted
Content-Type: application/hal+json
Content-Length: 893
{
"id" : "urn:example-register-18",
"uri" : "urn:example-register-18",
"type" : "srim:Register",
"title" : "New updated title",
"description" : "Register for Controlled Vocabularies",
"issued" : "2016-10-17",
"created" : "2016-10-17T19:28:16.168Z",
"modified" : "2016-10-17T19:28:16.181Z",
"_links" : {
"self" : {
"href" : "http://localhost:8080/registers"
},
"registry:registers" : {
"href" : "http://localhost:8080/registers"
},
"registry:registry" : {
"href" : "http://localhost:8080"
},
"registry:sparql" : {
"href" : "http://localhost:8080/sparql"
},
"registry:items" : {
"href" : "http://localhost:8080/registers/items"
},
"curies" : [ {
"href" : "http://www.opengis.net/rels/registry/{rel}",
"name" : "registry",
"templated" : true
} ]
}
}
======= JSON Representation
The JSON response of the request returns the HTTP Status Code 202 (accepted) if the update is accepted, and the updated item object without the hypermedia links. The server shoud add or update the modified field.
HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: 315
{
"id" : "urn:example-register-36",
"uri" : "urn:example-register-36",
"type" : "srim:Register",
"title" : "New updated title",
"description" : "Register for Controlled Vocabularies",
"issued" : "2016-10-17",
"created" : "2016-10-17T19:28:33.740Z",
"modified" : "2016-10-17T19:28:33.759Z"
}
Delete a Register
A DELETE
request is used to delete a register. The deletion will remove all the dependent
resources from the registry (entries and resource items, harvesters). If the
delete operation is successful, the response returns the HTTP code 200 and if the delete operation is unsuccessful, the response returns the HTTP code 404 (Not Found). This functionality is available only for authorized users.
Example request
The following HTTP request performs a HTTP Delete request on a register instance URL.
DELETE /registers/urn:example-register-12 HTTP/1.1
Host: localhost
Example response
If the register is successfully deleted the response will return the code 200 shown below.
HTTP/1.1 200 OK
Items
The Items Resource is used to create and list items. An Item is the top class of the SRIM hierarchy. It is a subclass of the class rdf:Resource
. It represents any information entities or services that can be registered in a register. Each srim:Item is associated with an ItemClass that is supported by the service. Example of ItemClasses include dcat:Dataset, srim:Service, schema:Schema, and symbol:Symbol. The ItemClasses and the application profiles supported by the service are defined in the Capabilities.
JSON Schema
As the registry service can support different item classes and application profiles, the JSON schema supported by the service is not unique. However there is a set of core properties that will always be present for any items in the registry. The following table describes the core minimal properties for an item.
Path | Type | Description | Cardinality |
---|---|---|---|
|
|
Internal identifier for the item, used by the registry |
1 |
|
|
Linked Data URI for the item (equivalent to @id in JSON-LD) |
0..1 |
|
|
The Item class identifier as published in the capability. |
1 |
|
|
The title of the item |
1 |
|
|
The title map for each language of the title . Each key corresponds to the two letter language identifier name defined in the capabilities ( for example "en") |
0..1 |
|
|
The description of the item |
0..1 |
|
|
The description map for each language of the description. Each key corresponds to the two letter language identifier name defined in the capabilities ( for example "en") |
0..1 |
|
|
The date of creation (XSD datetime format) (generated by the service) |
1 |
|
|
The date of the last modification (XSD datetime format) (generated by the service) |
0..1 |
|
|
Array of register identifiers in which the item belongs to. |
0..1 |
Search Items
There are two ways to search for Items - globally or constrained to a given Register. The global search is done by performing a HTTP GET
Request on the Items Resource, while the register constrained search is done by performing a HTTP GET
Request on the Register Items Resource. The item search supports free text, spatial, temporal or semantic search and can return results with aggregations on specific facets. Additionally, if the search is performed from a given register, the parameter registerId is ignored, and if the search is performed globally, the search can be performed on multiple registries by providing a list of register aliases.
Query Parameters
The following parameters are supported in the query:
Parameter | Description |
---|---|
|
Text to search in textual fields |
|
One or more categories |
|
One or more languages (using 2-letter code defined in the capabilities) |
|
One or more URIs of items instances |
|
One or more id of item instances |
|
One or more item class identifiers defining the type of items to fetch. |
|
One or more id of register instances |
bbox |
Bounding box defined by minx,miny,maxx,maxy . This option may be deprecated in the future and replaced with a CQL constraint |
within |
Boolean defining if the search needs be strictly within the bbox or not. This option may be deprecated in the future and replaced with a CQL constraint |
|
Boolean or list of facet names to include for aggregation computation. If the value is true, include all facets supported by the server. If only a subset of the facets are needed, comma delimited field names can be set. |
|
Constraint values of a given facet field name |
|
A constraint expressed in CQL. This is used to express more advanced query filtering |
|
One or more fields to be included in the response. Use JSON path dot notation for referrence paths (ex: publisher.name) |
|
The number of the current page as defined in the Paging section |
|
The count of items on the current page as defined in the Paging section |
|
The sorting parameters as defined in the Sorting section. |
Example requests
The following request performs a search of instance of item Class dcat:Dataset
.
GET /registers/urn:example-register-27/items?type=dcat%3ADataset HTTP/1.1
Accept: application/hal+json
Host: localhost
The following request performs a search of items with type dcat:Dataset (item class id) containing the word arctic, includes aggregation in all facets, and returns results with a page size of 4 elements.
GET /items?q=Arctic&type=dcat:Dataset&size=4&includeFacet=true HTTP/1.1
Host: localhost
Response structure
The response is structured according to the Item JSON Schema.
Links
The following link relation types are provided in the response to allow the transition to others states from the register item embedded in the response.
Relation | Description |
---|---|
|
Refers to the items list itself |
|
Refers to the root of the registry |
|
Refers to the curies defined for the links |
|
The first page of results |
|
The last page of results |
|
The next page of results |
|
The previous page of results |
Example response
HAL+JSON Representation
The embedded objects in the response of the request conform to the Register Item JSON Schema. The rest of the response returns paging and aggregation information as well as links to other states.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 2352
{
"_embedded": {
"registry:items": [{
"id": "2fe9867e7a22473bc2ec25dac3d959c7",
"uri": "urn:x-envitia:TB12:NMF:nmf-G1470659423089",
"type": "dcat:Dataset",
"title": "Murres as indicators of a changing Arctic",
"description": "The two species of murres, thick-billed Uria lomvia and common U. aalge, both have circumpolar distributions, breeding in Arctic, sub-Arctic and temperate seas from alifornia and N Spain to N Greenland, high Arctic Canada, Svalbard, Franz Josef Land and Novaya Zemlya (Box 4.3 Fig. 1). Conservation of Arctic Flora and Fauna, CAFF 2013 - Akureyri . Arctic Biodiversity Assessment. Status and Trends in Arctic biodiversity. - Birds(Chapter 4) page 163",
"created": "2016-10-10T16:09:47.684Z",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/items/2fe9867e7a22473bc2ec25dac3d959c7"
}
}
}, {
"id": "2373c7d58a4d54f0093bfb9b9f9d6c21",
"uri": "urn:x-envitia:TB12:NMF:nmf-G1470659422925",
"type": "dcat:Dataset",
"title": "Avian biodiversity in different regions of the Arctic",
"description": "Figure 4.1. Avian biodiversity in different regions of the Arctic. Charts on the inner circle show species numbers of different bird groups in the high Arctic, on the outer circle in the low Arctic. The size of the charts is scaled to the number of species in each region, which ranges from 32 (Svalbard) to 117 (low Arctic Alaska). CAFF 2013. Arctic Biodiversity Assessment. Status and Trends in Arctic biodiversity. Conservation of Arctic Flora and Fauna, Akureyri - Birds (Chapter 4) page 145",
"created": "2016-10-10T16:09:45.791Z",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/items/2373c7d58a4d54f0093bfb9b9f9d6c21"
}
}
}, {
"id": "a267316b5c5171893b1771e71b7c5a19",
"uri": "urn:x-envitia:TB12:NMF:nmf-G1470659423365",
"type": "dcat:Dataset",
"title": "Cumulative numbers of marine fish.",
"description": "Cumulative numbers of marine fish diversity (n = 633, Appendix 6.2) in the Arctic Ocean and adjacent seas (AOAS) from 1758 to the present. Species are broadly grouped according to zoogeographic pattern (cf. Section 6.3.1): Arctic (A, blue symbols) and non-Arctic (Σ AB, B, WD, red symbols). Grey bars denote periods with many descriptions of new Arctic species. Note that 75% of the non-Arctic species known to science were described by 1912, whereas the same proportion for Arctic species was only reached in 1976. See text for further information. Conservation of Arctic Flora and Fauna, CAFF 2013 - Akureyri . Arctic Biodiversity Assessment. Status and Trends in Arctic biodiversity. - Fishes(Chapter 6) page 220",
"created": "2016-10-10T16:09:50.824Z",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/items/a267316b5c5171893b1771e71b7c5a19"
}
}
}, {
"id": "d52e1c753f61dc577dce3ea5c5b818c8",
"uri": "urn:x-envitia:TB12:NMF:nmf-G1470659423695",
"type": "dcat:Dataset",
"title": "Diversity of Arctic marine phytoplankton: based on surveys in the Russian Arctic",
"description": "The number of species depends partly on what has been studied. Proportions vary somewhat around the Arctic, but diatoms and dinoflagellates are the most diverse groups everywhere. The greatest sampling effort has been in the Laptev Sea, Hudson Bay, and the Norwegian sector of the Barents Sea. Species shown are among the most commonly recorded. Published in the Life Linked to Ice released in 2013, page 26. Life Linked to Ice: A guide to sea-ice-associated biodiversity in this time of rapid change. CAFF Assessment Series No. 10. Conservation of Arctic Flora and Fauna, Iceland. ISBN: 978-9935-431-25-7.",
"created": "2016-10-10T16:09:54.199Z",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/items/d52e1c753f61dc577dce3ea5c5b818c8"
}
}
}]
},
"_links": {
"first": {
"href": "http://54.208.90.94/registry/items?q=Arctic&type=dcat:Dataset&includeFacet=true&page=0&size=4"
},
"self": {
"href": "http://54.208.90.94/registry/items?q=Arctic&type=dcat:Dataset&size=4&includeFacet=true"
},
"next": {
"href": "http://54.208.90.94/registry/items?q=Arctic&type=dcat:Dataset&includeFacet=true&page=1&size=4"
},
"last": {
"href": "http://54.208.90.94/registry/items?q=Arctic&type=dcat:Dataset&includeFacet=true&page=33&size=4"
},
"registry:service": {
"href": "http://54.208.90.94/registry"
},
"curies": [{
"href": "http://www.opengis.net/rels/registry/{rel}",
"name": "registry",
"templated": true
}]
},
"aggregations": [{
"name": "subject",
"metrics": {
"count": 1
},
"buckets": [{
"label": "DATASET",
"count": 1
}]
}, {
"name": "language",
"metrics": {
"count": 1
},
"buckets": [{
"label": "iso3:eng",
"count": 1
}]
}, {
"name": "type",
"metrics": {
"count": 135
},
"buckets": [{
"label": "dcat:Dataset",
"count": 135
}]
}, {
"name": "keyword",
"metrics": {
"count": 1
},
"buckets": [{
"label": "dataset",
"count": 1
}]
}, {
"name": "register",
"metrics": {
"count": 135
},
"buckets": [{
"label": "datasets",
"count": 135
}]
}],
"page": {
"size": 4,
"totalElements": 135,
"totalPages": 34,
"number": 0
}
}
JSON Representation
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1920
{
"results": [{
"id": "2fe9867e7a22473bc2ec25dac3d959c7",
"uri": "urn:x-envitia:TB12:NMF:nmf-G1470659423089",
"type": "dcat:Dataset",
"title": "Murres as indicators of a changing Arctic",
"description": "The two species of murres, thick-billed Uria lomvia and common U. aalge, both have circumpolar distributions, breeding in Arctic, sub-Arctic and temperate seas from alifornia and N Spain to N Greenland, high Arctic Canada, Svalbard, Franz Josef Land and Novaya Zemlya (Box 4.3 Fig. 1). Conservation of Arctic Flora and Fauna, CAFF 2013 - Akureyri . Arctic Biodiversity Assessment. Status and Trends in Arctic biodiversity. - Birds(Chapter 4) page 163",
"created": "2016-10-10T16:09:47.684Z"
}, {
"id": "2373c7d58a4d54f0093bfb9b9f9d6c21",
"uri": "urn:x-envitia:TB12:NMF:nmf-G1470659422925",
"type": "dcat:Dataset",
"title": "Avian biodiversity in different regions of the Arctic",
"description": "Figure 4.1. Avian biodiversity in different regions of the Arctic. Charts on the inner circle show species numbers of different bird groups in the high Arctic, on the outer circle in the low Arctic. The size of the charts is scaled to the number of species in each region, which ranges from 32 (Svalbard) to 117 (low Arctic Alaska). CAFF 2013. Arctic Biodiversity Assessment. Status and Trends in Arctic biodiversity. Conservation of Arctic Flora and Fauna, Akureyri - Birds (Chapter 4) page 145",
"created": "2016-10-10T16:09:45.791Z"
}, {
"id": "a267316b5c5171893b1771e71b7c5a19",
"uri": "urn:x-envitia:TB12:NMF:nmf-G1470659423365",
"type": "dcat:Dataset",
"title": "Cumulative numbers of marine fish.",
"description": "Cumulative numbers of marine fish diversity (n = 633, Appendix 6.2) in the Arctic Ocean and adjacent seas (AOAS) from 1758 to the present. Species are broadly grouped according to zoogeographic pattern (cf. Section 6.3.1): Arctic (A, blue symbols) and non-Arctic (Σ AB, B, WD, red symbols). Grey bars denote periods with many descriptions of new Arctic species. Note that 75% of the non-Arctic species known to science were described by 1912, whereas the same proportion for Arctic species was only reached in 1976. See text for further information. Conservation of Arctic Flora and Fauna, CAFF 2013 - Akureyri . Arctic Biodiversity Assessment. Status and Trends in Arctic biodiversity. - Fishes(Chapter 6) page 220",
"created": "2016-10-10T16:09:50.824Z"
}, {
"id": "d52e1c753f61dc577dce3ea5c5b818c8",
"uri": "urn:x-envitia:TB12:NMF:nmf-G1470659423695",
"type": "dcat:Dataset",
"title": "Diversity of Arctic marine phytoplankton: based on surveys in the Russian Arctic",
"description": "The number of species depends partly on what has been studied. Proportions vary somewhat around the Arctic, but diatoms and dinoflagellates are the most diverse groups everywhere. The greatest sampling effort has been in the Laptev Sea, Hudson Bay, and the Norwegian sector of the Barents Sea. Species shown are among the most commonly recorded. Published in the Life Linked to Ice released in 2013, page 26. Life Linked to Ice: A guide to sea-ice-associated biodiversity in this time of rapid change. CAFF Assessment Series No. 10. Conservation of Arctic Flora and Fauna, Iceland. ISBN: 978-9935-431-25-7.",
"created": "2016-10-10T16:09:54.199Z"
}],
"aggregations": [{
"name": "subject",
"metrics": {
"count": 1
},
"buckets": [{
"label": "DATASET",
"count": 1
}]
}, {
"name": "language",
"metrics": {
"count": 1
},
"buckets": [{
"label": "iso3:eng",
"count": 1
}]
}, {
"name": "type",
"metrics": {
"count": 135
},
"buckets": [{
"label": "dcat:Dataset",
"count": 135
}]
}, {
"name": "keyword",
"metrics": {
"count": 1
},
"buckets": [{
"label": "dataset",
"count": 1
}]
}, {
"name": "register",
"metrics": {
"count": 135
},
"buckets": [{
"label": "datasets",
"count": 135
}]
}],
"page": {
"size": 4,
"number": 0,
"totalElements": 135
}
}
Creating an Item
A POST
request is used to create a register item.
The response from this request should have a status code of 201 Created
and contain a
Location
header whose value is the URI of the newly created register item. To access the item’s details, either perform a GET
Request on the URI in the Location
header of the response, or just access the details of the item in the body of the response. We decided to have the API return the created representation in the response to prevent an API consumer from having to hit the API again for the newly created representation.
Request structure
The JSON body of the POST request adheres to the Item JSON Schema.
Example request
The following POST request creates a new Item using a JSON representation of dcat:Dataset
:
POST /items HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost
Content-Length: 473
{
"id" : "urn:example-item-25",
"uri" : "urn:example-item-25",
"type" : "dcat:Dataset",
"title" : "Example Item",
"description" : "This is an example item",
"language" : [ "iso639-2:eng" ],
"characterSet" : "http://def.seegrid.csiro.au/isotc211/iso19115/2003/code/CharacterSet/utf8",
"distribution" : [ {
"title" : "Example Distribution",
"accessURL" : "http://example.com/example-distribution",
"type" : "dcat:Distribution"
} ]
}
Example response
The response returns the URI of the newly created Register Item in the Location
header with a '201 Created' status code, with the content body containing the newly created item.
HTTP/1.1 201 Created
Location: http://localhost:8080/items/6b28163ce062d31533b6f0af1ab3b9e3
Content-Type: application/json
Content-Length: 529
{
"id" : "6b28163ce062d31533b6f0af1ab3b9e3",
"uri" : "urn:example-item-25",
"type" : "dcat:Dataset",
"title" : "Example Item",
"description" : "This is an example item",
"created" : "2016-10-17T19:28:18.848Z",
"language" : [ "iso639-2:eng" ],
"characterSet" : "http://def.seegrid.csiro.au/isotc211/iso19115/2003/code/CharacterSet/utf8",
"distribution" : [ {
"title" : "Example Distribution",
"accessURL" : "http://example.com/example-distribution",
"type" : "dcat:Distribution"
} ]
}
Item
An Item is the top class of the SRIM hierarchy. It is a sub class of the class rdf:Resource
, and it represents any information entities or services that can be registered in a register. The Item resource is used to retrieve, update, and delete an individual item in the registry service.
Retrieve a Register Item
A HTTP GET
Request will retrieve a particular instance of a register item.
Query Parameters
None
Example request
The following performs a GET Request to retrieve an instance of an item:
GET /items/dc6e55caee358f48236facb7608d3945 HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response is structured according to the Item JSON Schema.
Links
The following table shows the link relation types accessible from a register item instance that provide transitions to other states related to this register item instance.
Relation | Description |
---|---|
|
Refers to this item itself |
|
Refers to item search endpoint |
|
Refers to the JSON context of the item |
|
Refers to the root of the registry |
|
Refers to the curies defined for the links |
Example response
======= HAL+JSON Representation
The following response returns the JSON representation of the requested register item instance conforming to the Register Item JSON Schema.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 895
{
"id" : "dc6e55caee358f48236facb7608d3945",
"uri" : "urn:example-item-22",
"type" : "dcat:Dataset",
"title" : "Example Item",
"description" : "This is an example item",
"created" : "2016-10-17T19:28:16.583Z",
"language" : [ "iso639-2:eng" ],
"characterSet" : "http://def.seegrid.csiro.au/isotc211/iso19115/2003/code/CharacterSet/utf8",
"distribution" : [ {
"title" : "Example Distribution",
"accessURL" : "http://example.com/example-distribution",
"type" : "dcat:Distribution"
} ],
"_links" : {
"self" : {
"href" : "http://localhost:8080/items/dc6e55caee358f48236facb7608d3945"
},
"registry:items" : {
"href" : "http://localhost:8080/items"
},
"ogc:jsonld-context" : {
"href" : "http://localhost:8080/context"
},
"registry:service" : {
"href" : "http://localhost:8080"
}
}
}
======= JSON Representation
The following response returns the JSON representation of the requested register item instance conforming to the Register Item JSON Schema.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 529
{
"id" : "b23ef7a5379831ccae0c061a5468a6bb",
"uri" : "urn:example-item-11",
"type" : "dcat:Dataset",
"title" : "Example Item",
"description" : "This is an example item",
"created" : "2016-10-17T19:28:12.404Z",
"language" : [ "iso639-2:eng" ],
"characterSet" : "http://def.seegrid.csiro.au/isotc211/iso19115/2003/code/CharacterSet/utf8",
"distribution" : [ {
"title" : "Example Distribution",
"accessURL" : "http://example.com/example-distribution",
"type" : "dcat:Distribution"
} ]
}
======= Turtle/N3 Representation
The following response returns the Turtle representation of the requested register item instance conforming to the ontology and application profile defining the ItemClass (dcat:Dataset, schema:SchemaMapping).
HTTP/1.1 200 OK
Content-Type: text/n3
Content-Length: 1617
@prefix schema: <http://www.opengis.net/ont/testbed12/srim/profile/schema#> .
@prefix extent: <http://www.opengis.net/ont/extent#> .
@prefix adms: <http://www.w3.org/TR/vocab-adms/#> .
@prefix pav: <http://purl.org/pav/> .
@prefix org: <http://www.socialml.org/ontologies/organization#> .
@prefix link: <http://www.opengis.net/ont/link#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix schema-org: <http://schema.org/> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix gr: <http://www.heppnetz.de/ontologies/goodrelations/v1#> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix srim: <http://www.opengis.net/ont/testbed12/srim#> .
@prefix locn: <http://www.w3.org/ns/locn#> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<urn:example-item-7> a dcat:Dataset ;
dct:created "2016-10-17T15:28:09.767-04:00"^^xsd:dateTime ;
dct:description "This is an example item" ;
dct:language <http://id.loc.gov/vocabulary/iso639-2/eng> ;
dct:title "Example Item" ;
srim:characterSet <http://def.seegrid.csiro.au/isotc211/iso19115/2003/code/CharacterSet/utf8> ;
dcat:distribution [ a dcat:Distribution ;
dct:title "Example Distribution" ;
dcat:accessURL <http://example.com/example-distribution>
] .
Update an Item
A PUT
request is used to update a Register Item.
A HTTP PUT
request, with a body containing a JSON representation of the Register Item instance that adheres to Item JSON Schema, is used to update an Item instance. The response of the request returns the HTTP Status Code 204 (no-content) if the update is accepted.
Request Structure
The JSON request body is structured according to the Item JSON Schema.
Example Request
The following HTTP request performs a register item update using a JSON representation of the register item:
PUT /items/a22e8128788dc41d7deec94a4d52fe7e HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost
Content-Length: 569
{
"id" : "a22e8128788dc41d7deec94a4d52fe7e",
"uri" : "urn:example-item-4",
"type" : "dcat:Dataset",
"title" : "New updated title",
"description" : "This is an example item",
"created" : "2016-10-17T19:28:05.628Z",
"language" : [ "iso639-2:eng" ],
"keyword" : [ "Added keyword" ],
"characterSet" : "http://def.seegrid.csiro.au/isotc211/iso19115/2003/code/CharacterSet/utf8",
"distribution" : [ {
"title" : "Example Distribution",
"accessURL" : "http://example.com/example-distribution",
"type" : "dcat:Distribution"
} ]
}
Example Response
The response of the request returns the HTTP Status Code 202 (accepted) if the update is accepted, as well as the updated item object so the client can avoid making a second call to get the Item.
HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: 613
{
"id" : "a22e8128788dc41d7deec94a4d52fe7e",
"uri" : "urn:example-item-4",
"type" : "dcat:Dataset",
"title" : "New updated title",
"description" : "This is an example item",
"created" : "2016-10-17T19:28:05.628Z",
"modified" : "2016-10-17T19:28:06.106Z",
"language" : [ "iso639-2:eng" ],
"keyword" : [ "Added keyword" ],
"characterSet" : "http://def.seegrid.csiro.au/isotc211/iso19115/2003/code/CharacterSet/utf8",
"distribution" : [ {
"title" : "Example Distribution",
"accessURL" : "http://example.com/example-distribution",
"type" : "dcat:Distribution"
} ]
}
Delete an Item
A DELETE
request is used to delete a register item. The deletion will remove the item from the associated register. If the
delete operation is successful, the response returns the HTTP code 200 and if the delete operation is unsuccessful, the response returns the HTTP code 404 (Not Found). This functionality should be available only for authorized users.
Example Request
The following performs a HTTP Delete request on a register item instance URL.
DELETE /items/e96a00ecc259d7d9215eb0143462b0e2 HTTP/1.1
Host: localhost
Example Response
If the register item is successfully deleted the response returns the code 200 shown below.
HTTP/1.1 200 OK
SPARQL Service
The Semantic Registry Service provides a SPARQL service endpoint, which implements the SPARQL Protocol, that can accept a SPARQL query on the whole registry or a given register. Both HTTP GET and HTTP POST are supported.
Query Parameters
HTTP Method | Query String Parameters | Request Content Type | Request Message Body | |
---|---|---|---|---|
query via GET |
GET |
query (exactly 1) |
None |
None |
query via URL-encoded POST |
POST |
None |
application/x-www-form-urlencoded |
|
query via POST directly |
POST |
None |
application/sparql-query |
Unencoded SPARQL query string |
Example Request
The following is an example of a SPARQL query to fetch instances of schema:SchemaMapping with information about source schema and target schema.
PREFIX dcat:<http://www.w3.org/ns/dcat#> PREFIX dct: <http://purl.org/dc/terms/> PREFIX schema:<http://www.opengis.net/ont/testbed12/srim/profile/schema#> SELECT DISTINCT ?schema ?title ?description ?srcSchema ?targetSchema WHERE { ?schema a schema:SchemaMapping; dct:title ?title; dct:description ?description; schema:sourceSchema ?srcSchema; schema:targetSchema ?targetSchema } LIMIT 4
Response Structure
The SPARQL response conforms to the SPARQL specification. The SPARQL Protocol uses the response status codes defined in HTTP to indicate the success or failure of an operation.
The response body of a successful query operation with a 2XX response is either:
-
A SPARQL Results Document in XML, JSON, or CSV/TSV format (for SPARQL Query forms SELECT and ASK); or,
-
A RDF graph serialized, in the RDF/XML syntax or an equivalent RDF graph serialization (for SPARQL Query forms DESCRIBE and CONSTRUCT). The content type of the response to a successful query operation must be the media type defined for the format of the response body.
Example response
The following example shows a SPARQL query response
HTTP/1.1 200 OK
Content-Type: application/sparql-results+json
Content-Length: 2352
{
"head": {
"vars": [ "schema" , "title" , "description" , "srcSchema" , "targetSchema" ]
} ,
"results": {
"bindings": [
{
"schema": { "type": "uri" , "value": "http://www.opengis.net/testbed12/schemas#MNIS2DDMS" } ,
"title": { "type": "literal" , "value": "NMIS 2.2 to DDMS SchemaMapping" } ,
"description": { "type": "literal" , "value": "Schema Mapping from NMIS 2.2 to DDMS" } ,
"srcSchema": { "type": "uri" , "value": "http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2" } ,
"targetSchema": { "type": "uri" , "value": "http://metadata.dod.mil/mdr/ns/DDMS/2.0" }
} ,
{
"schema": { "type": "uri" , "value": "http://www.opengis.net/testbed12/schemas#FGDC_TO_ISO_19139Mapping" } ,
"title": { "type": "literal" , "value": "FGDC to ISO 19139 SchemaMapping" } ,
"description": { "type": "literal" , "value": "Schema Mapping from FGDC_STD_001_1998 to ISO 19139" } ,
"srcSchema": { "type": "uri" , "value": "https://www.fgdc.gov/schemas/metadata/fgdc-std-001-1998" } ,
"targetSchema": { "type": "uri" , "value": "http://www.isotc211.org/2005/gmd" }
}
]
}
}
Harvester Service Resources
This section describes the list of resources made accessible by the Harvester Service. The RESTful API has an entry point (service root) which provides links that represent the current state transitions supported by the service.
Service Root
The root is the entry point of the RESTful Semantic Registry service. When the client consumes the API for the first time, it comes in contact with the root. If the HATEOAS constraint is to be considered and implemented throughout by clients, then this is the place to start. The root endpoint provides a set of links with well-defined relation types that correspond to the supported capabilities of the service. As the Harvester Service API evolves in the future, there may be additional links, each with it’s own semantics defined by the type of link relation.
The API is considered RESTful as it is fully discoverable from the root with no prior knowledge – meaning the client should be able to navigate the API by doing a GET on the root. Moving forward, all state changes are driven by the client using the available and discoverable transitions that the REST API provides in representations (hence Representational State Transfer).
Accessing the Root Endpoint
To access the root of the service and get the list of links, a GET
request is sent to the base url of the service.
Request Structure
This request sends a 'GET' request to the base url of the service. Here the HTTP request returns the list of links supported by the service:
GET /harvesters HTTP/1.1
Host: localhost
Query Parameters
None
Response Structure
The request returns a HAL response (application/hal+json) with the _links object that contains links associated with relation types (used as property names in JSON).
Path | Type | Description |
---|---|---|
|
|
The hypermedia links to other states |
Links
The following table describes the current link relation types supported by the service.
Relation | Description |
---|---|
|
Refers to the registers list itself |
|
Refers to the types of harvesters supported by the registry |
|
Refers to the harvester sources known to the registry |
|
Refers to the harvest objects stored in the registry |
|
Refers to the harvest results available from the registry |
|
Refers to the root of the registry |
|
Refers to the curies defined for the links |
Example Response
The following example response shows the current links supported by the service.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 555
{
"_links" : {
"self" : {
"href" : "http://localhost:8080/harvesters"
},
"harvester:types" : {
"href" : "http://localhost:8080/harvesters/types"
},
"harvester:sources" : {
"href" : "http://localhost:8080/harvesters/sources"
},
"harvester:objects" : {
"href" : "http://localhost:8080/harvesters/objects"
},
"harvester:results" : {
"href" : "http://localhost:8080/harvesters/results"
},
"registry:service" : {
"href" : "http://localhost:8080"
}
}
}
Harvester Types
A HarvesterType defines the specification (class) of harvester for a given source type that produces items.
This resource describes the collection of harvester types supported by the harvester service. They provide a description of the source types that can be harvested and the detailed description of the required and optional parameters used to configure harvester source instance of this type.
JSON Schema
The JSON representation of the Harvester Type instance has the following fields:
Path | Type | Description | Card. |
---|---|---|---|
|
|
Internal identifier for the harvester type. This identifier is referred by harvester source to associate the type of the source witht property type. |
1 |
|
|
URI of the Harvester Type Class (defined in an ontology) |
1 |
|
|
Always 'HarvesterType'. |
1 |
|
|
The title of the harvester |
1 |
|
|
The description of the register |
0..1 |
parameters |
Array of Object |
Array of Parameter definitions used to configure an instance of this type (called Harvester Source) |
0..1 |
parameters[].name |
String |
Name of the parameter used in harvester source config as a key. |
1 |
parameters[].title |
String |
Title of the parameter used for UI display |
1 |
parameters[].description |
String |
Description of parameter |
1 |
parameters[].datatype |
String |
Datatype of the parameter. Value can be URI, string, text (for text area), numeric |
1 |
parameters[].optional |
boolean |
Indicates if the parameter is optional |
1 |
parameters[].allowedValues |
Array of String |
List of allowed values for a given parameter |
0..1 |
parameters[].default |
string |
Default value of the parameter if any. |
0 |
Search Harvester Types
A search for harvester types is done by performing a HTTP GET
request on the Harvester Types Resource. The harvester type search supports free text search, search by id or uris, and facet values. In addition, it can return results with aggregations on specific facets and customized projection on fields.
Query Parameters
The following table describes the query parameters that are currently supported
Parameter | Description |
---|---|
|
Text to search for in textual field of the resource. |
|
One or more URIs of the resource to retrieve |
|
One or more IDs of the resource to retrieve |
|
Boolean or list of facet names to include for aggregation computation. If the value is true, include all facets supported by the server. If only a subset of the facets are needed, a comma delimited of field names can be set. |
|
Constraint values of a given facet field name |
|
List of fields to be returned using dot path notation in JSON. This method allows to return custom response controlled by the client with the given fields of interest |
|
The number of the current page (zero-indexed) |
|
The count of items on the current page. |
|
The sorting parameters. |
Example request
The following is an example of a GET Request performed on the Harvester Types resource.
GET /harvesters/types HTTP/1.1
Host: localhost
Response structure
The response of a Harvester Types request has the following structure:
Path | Type | Description |
---|---|---|
|
|
Embedded results |
|
|
The array of harvester types results |
|
|
Identifier for the harvester type |
|
|
Always 'HarvesterType' |
|
|
Title of the harvester |
|
|
Description of the harvester type |
|
|
Aggregation information |
|
|
Information about the current page |
|
|
The hypermedia links to other states |
Example response
The following example response shows the current links supported by the service.
{
"_embedded": {
"registry:harvesterTypes": [{
"id": "csw",
"type": "HarvesterType",
"title": "OGC CSW Harvester",
"description": "OGC Web Catalog Service Harvester",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/types/csw"
}
}
}, {
"id": "dcat",
"type": "HarvesterType",
"title": "DCAT Document Harvester",
"description": "DCAT Harvester type",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/types/dcat"
}
}
}, {
"id": "wfs",
"type": "HarvesterType",
"title": "OGC WFS Harvester",
"description": "Web Feature Service Harvester type",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/types/wfs"
}
}
}, {
"id": "wms",
"type": "HarvesterType",
"title": "OGC WMS Harvester",
"description": "OGC Web Map Service Harvester",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/types/wms"
}
}
}, {
"id": "pod",
"type": "HarvesterType",
"title": "Project Open Data Harvester",
"description": "Project Open Data file Harvester",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/types/pod"
}
}
}, {
"id": "ckan",
"type": "HarvesterType",
"title": "CKAN Harvester",
"description": "CKAN Harvester",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/types/ckan"
}
}
}, {
"id": "iso19139",
"type": "HarvesterType",
"title": "ISO19139 Document Harvester",
"description": "ISO 19139 Document Harvester",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/types/iso19139"
}
}
}]
},
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/types"
},
"registry:harvester": {
"href": "http://54.208.90.94/registry/harvesters"
},
"registry:service": {
"href": "http://54.208.90.94/registry"
},
"curies": [{
"href": "http://www.opengis.net/rels/registry/{rel}",
"name": "registry",
"templated": true
}]
},
"aggregations": [],
"page": {
"size": 20,
"totalElements": 7,
"totalPages": 1,
"number": 0
}
}
Harvester Type
A HarvesterType Resource provides the specification of a harvester type. This resource supports only GET operation.
Retrieve a Harvester Type
Perform a HTTP GET
Request to retrieve a particular instance of a Harvester Type.
Query Parameters
None
Example request
The following is an example of a GET Request to retrieve a Harvester Type resource.
GET /harvesters/types/csw HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response is structured according to the Harvester Type JSON Schema.
Links
The following table shows the link relation types accessible from a harvester type resource that provide transitions to other states related to the harvester type instance.
Relation | Description |
---|---|
|
Refers to this harvester type itself |
|
Refers to the root of the harvesters endpoint |
|
Refers to the harvester types collection supported by the service |
|
Refers to the root of the registry service |
|
Refers to the curies defined for the links |
Example response
The following example response shows the details of an OGC Web Catalog Harvester Type in HAL+JSON
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 827
{
"id": "csw",
"uri": "http://www.opengis.net/ont/service/harvesters/types/csw",
"type": "HarvesterType",
"title": "OGC CSW Harvester",
"description": "OGC Web Catalog Service Harvester",
"parameters": [{
"name": "requestXML",
"title": "GetRecords XML Request",
"description": "GetRecords Request body encoded in XML",
"datatype": "text",
"optional": true,
"default": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<csw:GetRecords\n service=\"CSW\"\n version=\"2.0.2\"\n\tstartPosition=\"1\"\n\tmaxRecords=\"50000\"\n resultType=\"results\"\n outputFormat=\"application/xml\"\n outputSchema=\"http://www.isotc211.org/2005/gmd\"\n xmlns:csw=\"http://www.opengis.net/cat/csw/2.0.2\"\n xmlns:ogc=\"http://www.opengis.net/ogc\"\n xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n xsi:schemaLocation=\"http://www.opengis.net/cat/csw/2.0.2/CSW-discovery.xsd\">\n <csw:Query typeNames=\"csw:Record\">\n <csw:ElementSetName>full</csw:ElementSetName>\n </csw:Query>\n</csw:GetRecords>"
}, {
"name": "resourceType",
"title": "Resource Type",
"description": "The type of resource harvested",
"datatype": "string",
"optional": true,
"allowedValues": [
"http://www.isotc211.org/2005/gmd",
"urn:ogc:def:ebRIM-AssociationType:OGC:SchemaMapping",
"urn:ogc:def:ebRIM-ObjectType:OGC:Schema",
"http://www.w3.org/ns/dcat#Dataset",
"urn:ogc:def:ebRIM-ObjectType:OGC-I15::DataMetadata"
],
"default": "http://www.isotc211.org/2005/gmd"
}],
"_links": {
"self": {
"href": "http://localhost:8080/registry/harvesters/csw"
},
"harvester:types": {
"href": "http://localhost:8080/registry/harvesters/types"
},
"harvester:service": {
"href": "http://localhost:8080/registry/harvesters"
},
"registry:service": {
"href": "http://localhost:8080/registry"
}
}
}
Harvester Sources
A HarvesterSource defines an instance of a harvester type that needs to be harvested. It provides a description of the source that can be harvested. Configuration information includes the values bound to the parameters defined by the harvester type associated with this source, harvesting frequency and register id where harvested item results are saved. The Harvester Sources Resource describes the collection of harvester sources currently managed by the harvester service. It is used to create and search harvester sources.
JSON Schema
The JSON representation of the Harvester Source instance has the following fields:
Path | Type | Description | Card. |
---|---|---|---|
|
|
Internal identifier for the harvester, used by the registry |
1 |
|
|
Type of harvester . Refer to the id of the harvester type (for example csw). |
1 |
|
|
The title of the harvester |
1 |
|
|
The description of the register |
0..1 |
|
|
The date of creation (XSD datetime format) |
1 |
|
|
The date of the last modification (XSD datetime format) |
0..1 |
|
|
URL of the Source harvest |
1 |
config |
Object |
Configuration Object defining value binding to the parameter name defined in the Harvester Type (for example 'requestXML' for CSW harvest) |
0..1 |
harvestInterval |
String |
Harvesting time interval. Use xsd:duration string or MANUAL value (for adhoc harvesting). Default is MANUAL |
0..1 |
registerId |
String |
Id of register instance that the harvester use to populate |
0..1 |
Search Harvester Sources
A search for harvester sources is done by performing a HTTP GET
request on the Harvester Sources Resource. The harvester source search supports free text search, search by id or uris, and facet values. In addition, it can return results with aggregations on specific facets.
Query Parameters
The following are the query parameters that are currently supported
Parameter | Description |
---|---|
|
Text to search for in textual field of the harvester source. |
|
One or more URIs of the harvester source to retrieve |
|
One or more IDs of the harvester source to retrieve |
|
Boolean or list of facet names to include for aggregation computation. If the value is true, include all facets supported by the server. If only a subset of the facets are needed, a comma delimited of field names can be set. |
|
Constraint values of a given facet field name |
|
List of fields to be returned using dot path notation in JSON. This method allows to return custom response controlled by the client with the given fields of interest |
|
The number of the current page (zero-indexed) |
|
The count of items on the current page. |
|
The sorting parameters. |
Example Request
The following is an example of a GET Request performed on the Harvester Sources resource.
GET /harvesters/sources HTTP/1.1
Host: localhost
Response structure
The response of a Harvester Sources request has the following structure in HAL+JSON:
Path | Type | Description |
---|---|---|
|
|
Embedded results |
|
|
The array of harvester sources results |
|
|
Identifier for the harvester source |
|
|
Title of the harvester source |
|
|
Description of the harvester source |
|
|
Link to the instance of this source |
|
|
Aggregation information |
|
|
Information about the current page |
|
|
The hypermedia links to other states |
Links
The following table shows the link relation types accessible from a harvester sources resource that provide transitions to other states related to the harvester source instance.
Relation | Description |
---|---|
|
Refers to the registers list itself |
|
Refers to the harvesters landing page |
|
Refers to the root of the registry |
|
Refers to the curies defined for the links |
|
The first page of results |
|
The last page of results |
|
The next page of results |
|
The previous page of results |
Example Response
The following example response shows the current links supported by the service.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1548
{
"_embedded": {
"harvester:sources": [{
"id": "galdosCSW2",
"title": "SchemaMapping and Script Harvester from Galdos ebRIM CSW ",
"description": "This source harvests schemaMapping stored in ebRIM Model",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/sources/galdosCSW2"
}
}
}, {
"id": "envitiaCSW",
"title": "Testbed12 Envitia ebRIM CSW",
"description": "Envitia CSW used harvest ebRIM datasets records",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/sources/envitiaCSW"
}
}
}, {
"id": "galdosCSW1",
"title": "Schema Harvester from Galdos ebRIM CSW ",
"description": "This source harvests schemas stored in ebRIM Model",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/sources/galdosCSW1"
}
}
}, {
"id": "compusultCSW",
"title": "Testbed12 Compusult CSW",
"description": "Compusult CSW used for OGC Testbed 12 to harvest ISO19139 documents",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/sources/compusultCSW"
}
}
}, {
"id": "esriCSW",
"title": "Testbed12 ESRI CSW",
"description": "ESRI CSW used for OGC Testbed 12",
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/sources/esriCSW"
}
}
}]
},
"_links": {
"self": {
"href": "http://54.208.90.94/registry/harvesters/sources"
},
"registry:harvester": {
"href": "http://54.208.90.94/registry/harvesters"
},
"registry:service": {
"href": "http://54.208.90.94/registry"
},
"curies": [{
"href": "http://www.opengis.net/rels/registry/{rel}",
"name": "registry",
"templated": true
}]
},
"aggregations": [],
"page": {
"size": 20,
"totalElements": 5,
"totalPages": 1,
"number": 0
}
}
Creating a Harvester Source
A POST
request is used to create a harvester source.
The response from this request should have a status code of 201 Created
and contain a
Location
header whose value is the URI of the newly created harvester source. To access the harvester source’s details, either perform a GET
Request on the URI in the Location
header of the response, or just access the details of the harvester source in the body of the response. We decided to have the API return the created representation in the response to prevent an API consumer from having to hit the API again for the newly created representation.
Request Structure
The following table describes the fields accepted in the JSON request:
Path | Type | Description | Cardinality |
---|---|---|---|
|
|
Internal identifier for the harvester, used by the registry. The id can be user defined. If null, the id will be generated by the system. |
0..1 |
|
|
Type of harvester |
1 |
|
|
The title of the harvester |
1 |
|
|
The description of the register |
1 |
|
|
Source url to harvest |
1 |
config |
Object |
Configuration Object defining value binding to the parameter name defined in the Harvester Type (for example 'requestXML' for CSW harvest) |
0..1 |
harvestInterval |
String |
Harvesting time interval. Use xsd:duration string or MANUAL value (for adhoc harvesting). Default is MANUAL |
0..1 |
registerId |
String |
Id of register instance that the harvester use to populate |
0..1 |
Example Request
The following POST request creates a new Harvester Source for a CSW Harvester Type.
POST /harvesters/sources HTTP/1.1
Content-Type: application/json
Host: localhost
Content-Length: 146
{
"id" : "example-33",
"type" : "CSWHarvester",
"title" : "Example Harvester",
"description" : "Harvest all Items from Example CSW"
}
Example Response
The response returns the URI of the newly created Harvester Source in the Location
header with a '201 Created' status code, with the content body containing the newly created harvester source.
HTTP/1.1 201 Created
Location: http://localhost:8080/harvesters/sources/example-33
Content-Type: application/hal+json
Content-Length: 827
{
"id" : "example-33",
"type" : "CSWHarvester",
"title" : "Example Harvester",
"description" : "Harvest all Items from Example CSW",
"created" : "2016-10-17T19:28:31.601Z",
"modified" : "2016-10-17T19:28:31.601Z",
"_links" : {
"self" : {
"href" : "http://localhost:8080/harvesters/sources/example-33"
},
"harvester:harvest" : {
"href" : "http://localhost:8080/harvesters/sources/example-33/harvest"
},
"harvester:sources" : {
"href" : "http://localhost:8080/harvesters/sources"
},
"harvester:type" : {
"href" : "http://localhost:8080/harvesters/types/CSWHarvester"
},
"harvester:service" : {
"href" : "http://localhost:8080/harvesters"
},
"registry:service" : {
"href" : "http://localhost:8080"
}
}
}
Harvester Source
A HarvesterSource defines an instance of a harvester type to access a given source of information.
Retrieve a Harvester Source
A HTTP GET
Request will retrieve a particular instance of Harvester Source.
Query Parameters
None
Example Request
The following is an example of a GET Request performed on the Harvester Source resource which accepts HAL+JSON format.
GET /harvesters/sources/compusultCSW HTTP/1.1
Accept: application/hal+json
Host: localhost
Response Structure
The response is structured according to the Harvester Source JSON Schema.
Links
The following table defines the link relation types accessible from a harvester source resource that provide transitions to other states related to the harvester instance.
Relation | Description |
---|---|
|
Refers to this harvester configuration itself |
|
Refers to the link used to harvest items using the harvester configuration |
|
Refers to the search endpoint for harvester sources |
|
Refers to the root of the harvesters endpoint |
|
Refers to the harvester type definition |
|
Refers to the root of the registry |
|
Refers to the curies defined for the links |
Example Response
The following example response is an instance of a CSW Harvester source managed by the service
{
"id": "compusultCSW",
"type": "csw",
"title": "Testbed12 Compusult CSW",
"description": "Compusult CSW used for OGC Testbed 12 to harvest ISO19139 documents",
"created": "2016-10-03T22:49:27.311Z",
"modified": "2016-10-03T22:49:27.311Z",
"source": "http://ogc-testbed12.compusult.net/wes/serviceManagerCSW/csw",
"config": {
"resourceType": "http://www.isotc211.org/2005/gmd"
},
"harvestInterval": "MANUAL",
"registerId": "datasets",
"_links": {
"self": {
"href": "http://localhost:8080/registry/harvesters/sources/compusultCSW"
},
"harvester:harvest": {
"href": "http://localhost:8080/registry/harvesters/sources/compusultCSW/harvest"
},
"harvester:sources": {
"href": "http://localhost:8080/registry/harvesters/sources"
},
"harvester:type": {
"href": "http://localhost:8080/registry/harvesters/types/csw"
},
"harvester:service": {
"href": "http://localhost:8080/registry/harvesters"
},
"registry:service": {
"href": "http://localhost:8080/registry"
}
}
}
Update a Harvester Source
A HTTP PUT
request, with a body containing a JSON representation of the Harvester Source instance, is used to update a Harvester Source instance. The response of the request returns the HTTP Status Code 202 (Accepted) if the update is accepted with the updated Harvester Source description. Both JSON and HAL+JSON formats are accepted as response mime types.
Request Structure
The following table describes the fields accepted in the JSON request:
Path | Type | Description | Cardinality |
---|---|---|---|
|
|
Internal identifier for the harvester, used by the harvester service. |
0..1 |
|
|
Type of harvester |
1 |
|
|
The title of the harvester |
1 |
|
|
The description of the register |
1 |
|
|
Source url to harvest |
1 |
config |
Object |
Configuration Object defining value binding to the parameter name defined in the Harvester Type (for example 'requestXML' for CSW harvest) |
0..1 |
harvestInterval |
String |
Harvesting time interval. Use xsd:duration string or MANUAL value (for adhoc harvesting). Default is MANUAL |
0..1 |
registerId |
String |
Id of register instance that the harvester use to populate |
0..1 |
Response Structure
The response is structured according to the Harvester Source JSON Schema.
Example Request
The following HTTP request performs an update using a JSON representation of the Harvester Source.
PUT /harvesters/sources/galdosCSW1 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost
Content-Length: 952
{
"id": "galdosCSW1",
"type": "csw",
"title": "Schema Harvester from Galdos ebRIM CSW ",
"description": "This source harvests schemas stored in ebRIM Model",
"source": "http://ows.galdosinc.com/indicio/query",
"config": {
"requestXML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<csw:GetRecords xmlns:env-ebrim=\"http://www.envitia.com/schemas/georegistry/ebrim-ext\"
xmlns:xmime=\"http://www.w3.org/2005/05/xmlmime\"
xmlns:dct=\"http://purl.org/dc/terms/\"
xmlns:csw=\"http://www.opengis.net/cat/csw/2.0.2\"
xmlns:gml=\"http://www.opengis.net/gml\"
xmlns:wrs=\"http://www.opengis.net/cat/wrs/1.0\"
xmlns:ows=\"http://www.opengis.net/ows\"
xmlns:ogc=\"http://www.opengis.net/ogc\"
xmlns:dc=\"http://purl.org/dc/elements/1.1/\"
xmlns:xlink=\"http://www.w3.org/1999/xlink\"
service=\"CSW\" version=\"2.0.2\"\r\n\tresultType=\"results\" outputSchema=\"urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0\"
startPosition=\"1\" maxRecords=\"50\">
<csw:Query typeNames=\"wrs:ExtrinsicObject\">
<csw:ElementSetName>full</csw:ElementSetName>
<csw:Constraint version=\"1.1.0\">
<ogc:Filter>
<ogc:PropertyIsEqualTo>
<ogc:PropertyName>@objectType</ogc:PropertyName>
<ogc:Literal>urn:ogc:def:ebRIM-ObjectType:OGC:Schema</ogc:Literal>
</ogc:PropertyIsEqualTo>
</ogc:Filter>
</csw:Constraint>
</csw:Query>
</csw:GetRecords>",
"resourceType": "urn:ogc:def:ebRIM-ObjectType:OGC:Schema"
},
"harvestInterval": "MANUAL",
"registerId": "schemas"
}
Example Response
The response returns the HTTP Status Code 202 (accepted) if the update is accepted, and the updated harvester source is returned so the client can avoid making a second call to get the harvester source. The response of the request conforms to the Harvester Source JSON Schema.
HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 980
{
"id": "galdosCSW1",
"type": "csw",
"title": "Schema Harvester from Galdos ebRIM CSW ",
"description": "This source harvests schemas stored in ebRIM Model",
"created": "2016-10-03T22:49:27.542Z",
"modified": "2016-10-03T22:49:27.542Z",
"source": "http://ows.galdosinc.com/indicio/query",
"config": {
"requestXML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<csw:GetRecords xmlns:env-ebrim=\"http://www.envitia.com/schemas/georegistry/ebrim-ext\"
xmlns:xmime=\"http://www.w3.org/2005/05/xmlmime\"
xmlns:dct=\"http://purl.org/dc/terms/\"
xmlns:csw=\"http://www.opengis.net/cat/csw/2.0.2\"
xmlns:gml=\"http://www.opengis.net/gml\"
xmlns:wrs=\"http://www.opengis.net/cat/wrs/1.0\"
xmlns:ows=\"http://www.opengis.net/ows\"
xmlns:ogc=\"http://www.opengis.net/ogc\"
xmlns:dc=\"http://purl.org/dc/elements/1.1/\"
xmlns:xlink=\"http://www.w3.org/1999/xlink\"
service=\"CSW\" version=\"2.0.2\"\r\n\tresultType=\"results\" outputSchema=\"urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0\"
startPosition=\"1\" maxRecords=\"50\">
<csw:Query typeNames=\"wrs:ExtrinsicObject\">
<csw:ElementSetName>full</csw:ElementSetName>
<csw:Constraint version=\"1.1.0\">
<ogc:Filter>
<ogc:PropertyIsEqualTo>
<ogc:PropertyName>@objectType</ogc:PropertyName>
<ogc:Literal>urn:ogc:def:ebRIM-ObjectType:OGC:Schema</ogc:Literal>
</ogc:PropertyIsEqualTo>
</ogc:Filter>
</csw:Constraint>
</csw:Query>
</csw:GetRecords>",
"resourceType": "urn:ogc:def:ebRIM-ObjectType:OGC:Schema"
},
"harvestInterval": "MANUAL",
"registerId": "schemas"
}
Delete a Harvester Source
A DELETE
request is used to delete a harvester source. If the
delete operation is successful, the response returns the HTTP code 200 and if the delete operation is unsuccessful, the response returns the HTTP code 404 (Not Found). This functionality should be available only for authorized users.
Example Request
The following example performs a HTTP Delete request on a harvester source URL.
DELETE /harvesters/sources/example-33 HTTP/1.1
Host: localhost
Example Response
If the harvester source is successfully deleted the response return the code 200 shown below.
HTTP/1.1 200 OK
Harvest Action Resource
A Harvest Action is an "Action" Resource that triggers the harvesting of a source defined by a Harvester Source instance. This operation is invoked by a HTTP Get Operation. The current implementation performs only synchronous operation, but future extension will support asynchronous operations.
Harvest a Source
Query Parameters
None
Example Request
The following is an example of a GET Request to perform a harvest action that accepts HAL+JSON format.
GET /harvesters/sources/galdosCSW1/harvest HTTP/1.1
Accept: application/hal+json
Host: localhost
Response Structure
The response of a Harvest action request in the synchronous model has the following structure in HAL+JSON:
Path | Type | Description | Card, |
---|---|---|---|
|
|
Harvester Source object used as defined in the Harvester Source JSON Schema |
1 |
|
|
The array of items collected |
1 |
|
|
The identifier of the harvested item |
1 |
|
|
The uri identifier of the harvested item |
0..1 |
|
|
The type (item class id) of the harvested item |
1 |
|
|
The title of the harvested item |
1 |
|
|
Start time of harvesting |
1 |
|
|
End time of harvesting |
1 |
|
|
Duration of harvesting in milliseconds |
1 |
|
|
Number of records matched |
1 |
|
|
Number of records harvested and successfully stored |
1 |
|
|
Number of records failed |
1 |
|
|
The hypermedia links to other states (if using HAL) |
0.. 1 |
Example response
The following is the response to the harvest action in HAL+JSON
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 2703
{
"harvesterSource": {
"id": "galdosCSW1",
"type": "csw",
"title": "Schema Harvester from Galdos ebRIM CSW ",
"description": "This source harvests schemas stored in ebRIM Model",
"created": "2016-11-08T02:51:43.747Z",
"modified": "2016-11-08T02:51:43.747Z",
"source": "http://ows.galdosinc.com/indicio/query",
"config": {
"requestXML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\r\n<csw:GetRecords xmlns:env-ebrim=\"http://www.envitia.com/schemas/georegistry/ebrim-ext\"\r\n\txmlns:xmime=\"http://www.w3.org/2005/05/xmlmime\" xmlns:dct=\"http://purl.org/dc/terms/\"\r\n\txmlns:csw=\"http://www.opengis.net/cat/csw/2.0.2\" xmlns:gml=\"http://www.opengis.net/gml\"\r\n\txmlns:wrs=\"http://www.opengis.net/cat/wrs/1.0\" xmlns:ows=\"http://www.opengis.net/ows\"\r\n\txmlns:ogc=\"http://www.opengis.net/ogc\" xmlns:dc=\"http://purl.org/dc/elements/1.1/\"\r\n\txmlns:xlink=\"http://www.w3.org/1999/xlink\" service=\"CSW\" version=\"2.0.2\"\r\n\tresultType=\"results\" outputSchema=\"urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0\"\r\n\tstartPosition=\"1\" maxRecords=\"50\">\r\n\t<csw:Query typeNames=\"wrs:ExtrinsicObject\">\r\n\t\t<csw:ElementSetName>full</csw:ElementSetName>\r\n\t\t<csw:Constraint version=\"1.1.0\">\r\n\t\t\t<ogc:Filter>\r\n\t\t\t\t<ogc:PropertyIsEqualTo>\r\n\t\t\t\t\t<ogc:PropertyName>@objectType</ogc:PropertyName>\r\n\t\t\t\t\t<ogc:Literal>urn:ogc:def:ebRIM-ObjectType:OGC:Schema</ogc:Literal>\r\n\t\t\t\t</ogc:PropertyIsEqualTo>\r\n\t\t\t</ogc:Filter>\r\n\t\t</csw:Constraint>\r\n\t</csw:Query>\r\n</csw:GetRecords>",
"resourceType": "urn:ogc:def:ebRIM-ObjectType:OGC:Schema"
},
"harvestInterval": "MANUAL",
"registerId": "schemas"
},
"items": [{
"id": "f981d111fdbbf8e7916f6dfe9dcc7c69",
"uri": "urn:uuid:566ff231-e768-41de-bb26-e0def91ceb9b",
"type": "schema:Schema",
"title": "National System for Geospatial Intelligence Metadata Implementation Specification (NMIS) - Part 2: XML Exchange Schema, Version 2.2.0"
}, {
"id": "315a1576cd09615683160f9f1e84ca97",
"uri": "urn:uuid:02200156-4271-4d52-a2e1-47d268680aa7",
"type": "schema:Schema",
"title": "Department of Defense Discovery Metadata Specification (DDMS), Version 2.0"
}],
"startTime": "2016-11-08T06:48:12.443Z",
"endTime": "2016-11-08T06:48:20.250Z",
"duration": 7807,
"recordsMatched": 2,
"recordsHarvested": 2,
"recordsFailed": 0,
"_links": {
"harvester:source": {
"href": "http://localhost:8080/harvesters/sources/galdosCSW1"
},
"harvester:service": {
"href": "http://localhost:8080/harvesters"
}
}
}
h
Appendix E: Semantic Mediation Service REST API
Overview
This document describes the initial version of RESTful Semantic Mediation Service API. We anticipate that a variety of clients may be using the Semantic Mediation Service, and as a consequence it is difficult to accommodate the needs of every type of client. It is almost certain that the REST API will evolve and be modified as more requirements and features are added to the service. The hypermedia-driven API provides a robust approach to evolve the API without breaking the client ecosystem, as long as the clients are using the semantics of the link relation types. For this reason, the service has adopted a hypermedia-driven RESTful API by default, which meets level 3 of the Richardson Maturity Model.
The default serialization of the information model in the service is JSON, as it is understood by most programming languages. However, to support machine-processable information, we enforce the JSON to be compatible Linked data by using JSON-LD Context. In this way, data can be converted to Linked Data Representation and be reasoned on and linked to other information expressed as Linked Data. The REST API does support content negotiation to return a response in Linked Data Format (RDF/XML, Turtle, NTriple) when applicable. The REST API in this document provides the core minimum functionalities that are based on the Schema SRIM Application Profile.
Creation/Retrieval/Deletion operations are optional for this service. We choose to delegate these operations to the Semantic Registry Service implementing the SRIM Schema Application Profile. For more information about these operations, refers to the documentation of the Semantic Registry API. The Semantic Mediation Service can delegate the operations of search of schemas and schema mappings (as demonstrated by the implementation in the testbed). However the response using hypermedia links is modified to provide links that are relevant for mediation operations. For example a schema mapping retrieval will provide hypermedia links to its source schema and target schema. A schema may provide a link to all the schema mappings using this schema as a source or target.
Note
|
The example URL used in this documentation used the hostname http://localhost:8080. This hostname should be replaced by the entry point (baseURL) of the service that you want to access in the format: http://{hostname}:{port}/{rootPath} |
HTTP verbs
The RESTful API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs. The following HTTP verbs are used by the Service.
Verb | Usage |
---|---|
|
Used to retrieve a resource |
|
Used to create a new resource |
|
Used to update an existing resource with a complete update |
|
Used to delete an existing resource |
HTTP status codes
The Service REST API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes. The following table summarizes the status codes and usage.
Status code | Usage |
---|---|
|
The request completed successfully |
|
A new resource has been created successfully. The resource’s URI is available from the response’s
|
|
An update to an existing resource has been applied successfully |
|
The request was malformed. The response body will include an error providing further information |
|
The requested resource did not exist |
|
The request was made of a resource using a request method not supported by that resource; for example, using GET on a form which requires data to be presented via POST, or using PUT on a read-only resource. |
|
The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. |
|
The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. |
|
The Web server encountered an unexpected condition that prevented it from fulfilling the request by the client |
Headers
Every response has the following header(s):
Name | Description |
---|---|
Content-Type |
The Content-Type of the payload, e.g. |
Future headers may be added for managing access control to the resources managed by the service.
Errors
Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:
Path | Type | Description |
---|---|---|
timestamp |
Number |
The time, in milliseconds, at which the error occurred |
status |
Number |
The HTTP status code, e.g. |
error |
String |
The HTTP error that occurred, e.g. |
message |
String |
A description of the cause of the error |
path |
String |
The path to which the request was made |
For example, a request that attempts to apply a non-existent resource to a register item will produce a
400 Bad Request
response:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 189
{
"timestamp" : 1461855421813,
"status" : 400,
"error" : "Bad Request",
"message" : "The resource item 'http://localhost:8080/schemas/123' does not exist",
"path" : "/schemas"
}
Paging and Sorting
Paging
Rather than return everything from a large result set, the REST API recognizes some URL parameters that will influence the page size (size
parameter) and starting page number (page
parameter) as well as sorting of the result set (sort
parameter).
See the following example, where we set the page size to 5 and request the third page (page 2) as page numbers are zero-indexed:
GET schemas?page=2&size=5 HTTP/1.1
Host: localhost
The paginated results in HAL format returns the following response:
{
"_embedded": {
...data...
},
"_links": {
"self": {
"href": "http://localhost:8080/schemas"
},
"first": {
"href": "http://localhost:8080/schemas?page=0&size=5"
},
"prev": {
"href": "http://localhost:8080/schemas?page=1&size=5"
},
"next": {
"href": "http://localhost:8080/schemas?page=3&size=5"
},
"last": {
"href": "http://localhost:8080/schemas?page=5&size=5"
},
},
"page": {
"size": 5,
"totalElements": 27,
"totalPages": 6,
"number": 2
}
}
Each paged response will return links to the first, previous, next, and last page of results based on the current page using the IANA defined link relations first
,
prev
,
next
,
last
. If you are currently at the first page of results, however, no prev
link will be rendered. The same is true for the last page of results: no next
link will be rendered.
The paginated results also have extra data about the page settings , including the size of a page, total elements, total pages, and the page number you are currently viewing. This extra information makes it very easy for the consumer to configure UI tools like sliders or indicators to reflect the overall position the user is in viewing the data. For example, the document above shows we are looking at the third page (with page numbers indexed to 0 being the first).
Sorting
The REST API recognizes sorting parameters. To have your results sorted on a particular property, add a sort
URL parameter with the name of the property you want to sort the results on. You can control the direction of the sort by appending a ,
to the the property name plus either asc
or desc
.
The following examples will sort results by title in ascending order:
GET /schemas?sort=title,asc HTTP/1.1
Host: www.mydomain.com
To sort the results by more than one property, keep adding as many sort=PROPERTY
parameters as you need. They will be added in the order they appear in the query string.
Search Results
A number of endpoints of the service return search results.They usually supports Level 2 (JSON) and Level 3 response (HAL+JSON). The search results contains the collection of matched items, paging information and optionally faceted aggregation results. The following describes the response structure for each format.
HAL+JSON Search Results
Path | Type | Description |
---|---|---|
|
|
The HAL _embedded field that contains a collection of instances |
embedded._collectionName[] |
|
The array of items instances defined a given JSON schema. The collectionName may varied depending of the types of items contained in the collection. |
|
|
The aggregation results as defined in the Aggregation JSON Schema. This field is optional is no faceted search is performed on the endpoint. |
|
|
The name of the aggregation (or facet) |
|
|
The metrics object containing global statistics of the object |
|
|
The total count of the aggregation |
|
|
The array of buckets of the aggregation |
|
|
The label of the bucket |
|
|
The count of the label for the bucket |
|
|
Links to other states |
|
|
The page state. See <<_paging,Paging section> |
|
|
The page size |
|
|
The total elements matched by the search request |
|
|
The total number of pages in the results |
|
|
The current page number (starts at 0) |
|
|
Array of hypermedia links to other reachable states. |
JSON Search results
When the JSON or JSON-LD response is retrieved, the matched items are placed in an array referred by the results field. Aggregations results are present only faceted search is performed and paging information are returned.
Path | Type | Description |
---|---|---|
|
|
The array of vocabulary instances that matches the search criteria |
|
|
The aggregation results as defined in the Aggregation JSON Schema. This field is optional is no faceted search is performed on the endpoint. |
|
|
The name of the aggregation (or facet) |
|
|
The metrics object containing global statistics of the object |
|
|
The total count of the aggregation |
|
|
The array of buckets of the aggregation |
|
|
The label of the bucket |
|
|
The count of the label for the bucket |
|
|
The page state. See <<_paging,Paging section> |
|
|
The page size |
|
|
The total elements matched by the search request |
|
|
The total number of pages in the results |
|
|
The current page number (starts at 0) |
Aggregation JSON Schema
In many use cases, it is useful to aggregate the search results according some facets values (number of items per topic, per publisher, etc). Each facet is composed of a name, global metrics (right now only total count is supported), a set of buckets containing a label (unique value of the facet) and the total count for each label within the context of the facet and search results. The JSON schema of the Aggregation results is defined in the following table.
Path | Type | Description |
---|---|---|
|
|
The aggregation results |
|
|
The name of the aggregation (or facet) |
|
|
The metrics object containing global statistics of the object |
|
|
The total count of the aggregation |
|
|
The array of buckets of the aggregation |
|
|
The label of the bucket |
|
|
The count of the label for the bucket |
Resources Summary
The following resources are the core resources supported by the Semantic Mediation Service.
Resources | Description | Operations |
---|---|---|
Capabilities |
This resource describes the capabilities of the service |
GET |
Schema Mapping Collection |
This resource represents a collection of schema mappings and supports creation of schema mappings and search on a collection of schema mappings based on search criteria |
GET, POST (optional) |
Schema Mapping |
This resource supports retrieval, update, and deletion of schema mapping instance |
GET, PUT (optional),DELETE (optional) |
Schema Collection |
represents a collection of schemas and supports creation of schema and search on a collection of schemas based on search criteria |
GET, POST (optional) |
Schema |
This resource supports retrieval update, and deletion of schema instance |
GET, PUT (optional), DELETE (optional) |
JSONLD Context |
This resource returns the JSON-LD context associated with the JSON representation returned by the service |
GET |
Validator |
This resource performs validation of a data against a given schema |
GET,POST |
Transformer |
This resource performs transformation of data from one schema to another |
GET,POST |
Link relation types
The following table describes the list of link relation types used by the Semantic Mediation Service. We use the OGC namespace to define the relationships in order to favor reusability accross all OGC service specifications.
Relation type | URI | Description |
---|---|---|
mediation:capabilities |
Reference to the capabilities of the service |
|
mediation:schemas |
Reference to the schema collection |
|
mediation:sourceSchema |
Reference to the source schema of a schema mapping |
|
mediation:targetSchema |
Reference to the target schema of a schema mapping |
|
mediation:schemaMappings |
Reference to the schema mapping collection |
|
mediation:sourceSchemaMappings |
Reference to the schema mapping collection |
|
mediation:targetSchemaMappings |
Reference to the schema mapping collection |
|
ogc:jsonldContext |
Reference to the JSON-LD context to apply to the JSON content to transform it to Linked Data |
|
mediation:validator |
Reference to the validator service |
|
mediation:transform |
Reference to the schema mapping transformer service |
|
ogc:documentation |
Reference to the REST documentation of the service |
Content negotiation
Most of the resource can serve multiple representations including:
Format | Mime type | Description |
---|---|---|
HAL+JSON |
application/hal+json |
It is the default format of the service. The JSON payload is compatible with JSON-LD and is aligned with the Schema SRIM Application Profile Ontology. |
JSON-LD |
application/ld+json |
Compliant with the Schema SRIM Application Profile Ontology using the JSON-LD context. |
RDF/XML |
application/rdf+xml |
Compliant with the Schema SRIM Application Profile Ontology |
Turtle |
text/turtle |
Compliant with the Schema SRIM Application Profile Ontology |
N-Triples |
text/ntriples |
Compliant with the Schema SRIM Application Profile Ontology |
Resources descriptions
Service Entry Point
The entry point (also called root) of the RESTful Semantic Mediation service is what the client comes into contact with when consuming the API for the first time. If the HATEOAS constraint is to be considered and implemented throughout by clients, then this is the place to start. The root endpoint provides a set of links with well-defined relation types that corresponds to the supported capabilities of the service. As the Semantic Mediation Service API evolves in the future, there would be many more links, each with it’s own semantics defined by the type of link relation.
The API is considered as RESTful as it is fully discoverable from the root and with no prior knowledge – meaning the client should be able to navigate the API by doing a GET on the root. Moving forward, all state changes are driven by the client using the available and discoverable transitions that the REST API provides in representations (hence Representational State Transfer).
Accessing the root endpoint
To get access to the root of the service and get the list of links, a GET
request is sent to the base url of the service.
Request structure
This request sends a 'GET' request to the base url of the service. Here the HTTP request associated to get the list of links supported by the service:
GET / HTTP/1.1
Host: localhost
The only representation is HAL+JSON.
Query Parameters
None
Response structure
The response is returning a HAL response (application/hal+json) with the _links object that contains links associated with relation types (used as property names in JSON).
Path | Type | Description |
---|---|---|
@context |
String |
JSON-LD Context applicable to JSON response of the service |
type |
String |
The type of the resource (always Service) |
title |
String |
Title of the service |
description |
String |
Description of the service |
categories |
Array |
Categories of the service |
_links |
Object |
Links to other resources |
Links
The following table describes the current link relation types supported by the service.
Relation | Description |
---|---|
ogc:capabilities |
Refers to the capabilities of this service. |
ogc:schemas |
Refers to the schemas supported by this service |
ogc:schemaMappings |
Refers to the schema mappings managed by this service |
ogc:validator |
Refers to the validator service |
ogc:transform |
Refers to transformer service |
ogc:jsonContext |
Refers to JSON Context of the service |
curies |
The curies to use to expand the link relation types to URI |
Example response
The following example response shows the current links supported by the service.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 921
{
"@context" : "http://localhost:8080/context",
"type" : "http://www.opengis.net/ont/srim#Service",
"title" : "Semantic Mediation Service",
"description" : "Semantic Mediation Service",
"categories" : [ "http://www.opengis.net/specs/testbed/sms" ],
"_links" : {
"ogc:capabilities" : {
"href" : "http://localhost:8080/capabilities"
},
"ogc:schemas" : {
"href" : "http://localhost:8080/schemas"
},
"ogc:schemaMappings" : {
"href" : "http://localhost:8080/mappings"
},
"ogc:jsonContext" : {
"href" : "http://localhost:8080/context"
},
"ogc:transform" : {
"href" : "http://localhost:8080/transform"
},
"ogc:validator" : {
"href" : "http://localhost:8080/validate"
},
"curies" : [ {
"href" : "http://www.opengis.net/rels/{rel}",
"name" : "ogc",
"templated" : true
} ]
}
}
Capabilities
This resource describes the capabilities of the service, including the supported schema and schema mapping languages, application profiles, transformers and formats.
Query Parameters
There is no query parameter to retrieve the capabilities.
Example request
The following is an example of GET Request performed on the Capability resource.
GET /capabilities HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response of Capability request has the following structure:
Path | Type | Description |
---|---|---|
|
|
schema Languages supported by the service |
|
|
The URI of the schema language |
|
|
The RDF type of the schema language (always skos:Concept) |
|
|
The human readable preflabel of this schema language |
|
|
The notation (abbreviation) of the schema language |
|
|
schema Languages supported by the service |
|
|
The URI of the schema language |
|
|
The RDF type of the schema mapping language (always skos:Concept) |
|
|
The human readable preflabel of this schema mapping language |
|
|
The notation (abbreviation) of the schema mapping language |
|
|
The hypermedia links to other states |
Links
The following table describes the current link relation types in the HAL capabilities response
Relation | Description |
---|---|
|
Link to the root of the service |
|
Refers to this endpoint. |
|
Refers to the curies defined for the links |
Example response
The following example response shows a capability of the service is represented.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 30456
{
"schemaLanguages": [{
"type": "skos:Concept",
"prefLabel": "XML Schema",
"uri": "http://www.w3.org/TR/xmlschema-1/",
"notation": "XMLSchema"
}, {
"type": "skos:Concept",
"prefLabel": "Web Ontology Language Full/DL/Lite",
"uri": "http://www.opengis.net/ont/testbed12/srim/profile/schema#OWL",
"notation": "OWL"
}, {
"type": "skos:Concept",
"prefLabel": "Resource Description Framework Schema",
"uri": "http://www.opengis.net/ont/testbed12/srim/profile/schema#RDFSchema",
"notation": "RDFSchema"
}, {
"type": "skos:Concept",
"prefLabel": "Relax NG",
"uri": "http://www.opengis.net/ont/testbed12/srim/profile/schema#RELAXNG",
"notation": "RelaxNG"
}, {
"type": "skos:Concept",
"prefLabel": "Simple Knowledge Organization System",
"uri": "http://www.opengis.net/ont/testbed12/srim/profile/schema#SKOS",
"notation": "SKOS"
}],
"schemaMappingLanguages": [{
"type": "skos:Concept",
"prefLabel": "eXtensible StyleSheet Transform",
"uri": "https://www.w3.org/TR/xslt20/",
"notation": "XSLT"
}],
"_links": {
"self": {
"href": "http://localhost:8083/capabilities"
},
"service": {
"href": "http://localhost:8083"
}
}
}
JSON-LD Context
The JSON produced by the Semantic Mediation Service is compatible with the Schema SRIM Application Profile, by using JSON-LD context. The context is made accessible through an endpoint, so it can referred and imported by JSON-LD processor to be converted into a Linked Data representation adhering to the Schema SRIM Profile.
Query Parameters
There is no query parameter to retrieve the JSON-LD context.
Example request
The following is an example of GET Request performed on the JSON-LD context resource.
GET /context HTTP/1.1
Host: localhost
Response structure
The response of JSON-LD Context is conforming to the standard JSON-LD.
Path | Type | Description |
---|---|---|
@context |
Object |
JSON-LD Context applicable to JSON response of the service |
Example response
The following example response shows a JSON-LD context of the service.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2222
{
"@context": {
"pav": "http://purl.org/pav/",
"dct": "http://purl.org/dc/terms/",
"owl": "http://www.w3.org/2002/07/owl#",
"xsd": "http://www.w3.org/2001/XMLSchema#",
"skos": "http://www.w3.org/2004/02/skos/core#",
"srim": "http://www.opengis.net/ont/testbed/12/srim#",
"rdfs": "http://www.w3.org/2000/01/rdf-schema#",
"dcat": "http://www.w3.org/ns/dcat#",
"iso639-2": "http://id.loc.gov/vocabulary/iso639-2/",
"lingvoj":"http://www.lingvoj.org/ontology#",
"foaf": "http://xmlns.com/foaf/0.1/",
"ldp":"http://www.w3.org/ns/ldp#",
"type": "@type",
"uri": "@id",
"value": "@value",
"lang": "@language",
"results": "ldp:contains",
"title": "dct:title",
"titleMap": {
"@id": "dct:title",
"@container": "@language"
},
"description": "dct:description",
"descriptionMap": {
"@id": "dct:description",
"@container": "@language"
},
"category": {
"@id": "dct:type",
"@type": "@id"
},
"hasVersion": "dct:hasVersion",
"currentVersion": {
"@id": "pav:currentVersion",
"@type": "@id"
},
"version": "pav:version",
"creator": "dct:creator",
"contributor": "dct:contributor",
"publisher": "dct:publisher",
"language": "dct:language",
"iso2Code":"lingvoj:iso1",
"iso3Code":"lingvoj:iso2",
"notation": "skos:notation",
"label": "rdfs:label",
"name": "foaf:name",
"sameAs": {
"@id": "owl:sameAs",
"@type": "@id"
},
"distributions": "dcat:distribution",
"license": "dct:license",
"issued": "dct:issued",
"modified": "dct:modified",
"prefix": "wov:prefix",
"namespace": "wov:namespace",
"releaseNote": {
"@id": "wov:releaseNote",
"@container": "@language"
},
"accessURL": "dcat:accessURL",
"mediaType": "dcat:mediaType"
}
}
Schema Collection
A Schema defines the vocabulary and structure of data. The Schema Collection resource represents a collection of Schema instances. It is used to create and search schemas.
JSON Schema
As the registry service can support different item classes and application profiles, the JSON schema supported by the service is not unique. However there is a set of core properties that will always be present for any items in the registry. The following table describes the core minimal properties for a item.
Path | Type | Description | Card. |
---|---|---|---|
|
|
Internal identifier for the item, used by the registry |
1 |
|
|
Linked Data URI for the item (equivalent to @id in JSON-LD) |
0..1 |
|
|
The Item class identifier as published in the capability. |
1 |
|
|
The title of the item |
1 |
|
|
The title map for each language of the title . Each key corresponds to the two letter language identifier name defined in the capabilities ( for example "en") |
0..1 |
|
|
The description of the item |
0..1 |
|
|
The description map for each language of the description. Each key corresponds to the two letter language identifier name defined in the capabilities ( for example "en") |
0..1 |
|
|
The date of creation (XSD datetime format) (generated by the service) |
1 |
|
|
The date of the last modification (XSD datetime format) (generated by the service) |
0..1 |
namespace |
URI |
This property store the namespace of the schema when available |
0..1 |
schemaLanguage |
URI |
This property holds the language used in the schema if applicable. |
1 |
Search schemas
A search for schemas is performed by performing a HTTP GET
request. The schema search supports free text, by ids, by uris, CQL constraint and can return results with aggregations on specific facets.
Query Parameters
The current parameters supported by the GET request are for paging and sorting.
The following query parameters are supported in the query:
Parameter | Description |
---|---|
|
Text to search in textual fields |
|
One or more URIs of schema instances |
|
One or more id of schema instances |
|
Boolean or list of facet names to include for aggregation computation. If the value is true, include all facets supported by the server. If only a subset of the facets are needed, a comma delimited of field names can be set. |
|
Constraint values of a given facet field name |
|
A constraint expressed in CQL. This is used to express more advanced query filtering |
|
One or more fields to be included in the response. Use JSON path dot notation for referring paths (ex: publisher.name) |
|
The number of the current page as defined in Paging section |
|
The count of items on the current page as defined in Paging section |
|
The sorting parameters as defined in Sorting section. |
Example request
The following is an example of GET Request performed on the Schemas resource to the first page composed of 3 schemas and sorted by title in ascending order.
GET /schemas HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The following fields are present in the response and adhere to the JSON Schema definition.
Links
The following link relation types are provided in the response to allow the transition to others states from the schemas collection embedded in the response.
Relation | Description |
---|---|
|
Refers to this search request itself |
|
Refers to the mediation service |
|
Refers to the curies defined for the links |
Example response
The embedded objects in the response of the request conforms to the Schema JSON Schema. Tne rest of the response return paging information and links to other states.
{
"_embedded": {
"mediation:schemas": [{
"id": "643d2431ff31955de485f84cbbc598d1",
"uri": "https://www.fgdc.gov/schemas/metadata/fgdc-std-001-1998",
"type": "schema:Schema",
"title": "Content Standards for Digital Geospatial Metadata Version 2.0",
"description": "The objectives of the standard are to provide a common set of terminology and definitions for the documentation of digital geospatial data. The standard establishes the names of data elements and compound elements (groups of data elements) to be used for these purposes, the definitions of these compound elements and data elements, and information about the values that are to be provided for the data elements.",
"created": "2016-10-10T16:10:01.213Z",
"_links": {
"self": {
"href": "http://54.208.90.94/mediation/schemas/643d2431ff31955de485f84cbbc598d1"
}
}
}, {
"id": "66dcd67e36e93540bc77e4710fd749ad",
"uri": "http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2",
"type": "schema:Schema",
"title": "National System for Geospatial Intelligence Metadata Implementation Specification (NMIS) - Part 2: XML Exchange Schema, Version 2.2.",
"description": "An XML encoding of the NMIS logical model (Part 1) that is conformant to ISO 19139 and the XML Data Encoding Specification for Information Security Marking Metadata (DES.ISM.XML.V9)",
"created": "2016-10-10T16:09:58.704Z",
"namespace": "http://metadata.ces.mil/dse/ns/GSIP/5.0/nas",
"_links": {
"self": {
"href": "http://54.208.90.94/mediation/schemas/66dcd67e36e93540bc77e4710fd749ad"
}
}
}, {
"id": "3712ab70e045d43a416ce468d295e0ea",
"uri": "http://www.isotc211.org/2005/gmd",
"type": "schema:Schema",
"title": "ISO 19139 Schema (version 2012-07-13)",
"description": "Geographic MetaData (GMD) extensible markup language is a component of the XML Schema Implementation of Geographic Information Metadata documented in ISO/TS 19139:2007. GMD includes all the definitions of http://www.isotc211.org/2005/gmd namespace. The root document of this namespace is the file gmd.xsd.",
"created": "2016-10-10T16:09:56.115Z",
"namespace": "http://www.isotc211.org/2005/gmd",
"_links": {
"self": {
"href": "http://54.208.90.94/mediation/schemas/3712ab70e045d43a416ce468d295e0ea"
}
}
}, {
"id": "32ed1ba2e79e51ed951b250ea1bd50d9",
"uri": "http://metadata.dod.mil/mdr/ns/DDMS/2.0",
"type": "schema:Schema",
"title": "Department of Defense Discovery Metadata Specification (DDMS), Version 2.0",
"description": "Defines discovery metadata elements for resources posted to community and organizational shared spaces",
"created": "2016-10-10T16:10:04.174Z",
"namespace": "http://metadata.dod.mil/mdr/ns/DDMS/2.0/",
"_links": {
"self": {
"href": "http://54.208.90.94/mediation/schemas/32ed1ba2e79e51ed951b250ea1bd50d9"
}
}
}, {
"id": "f981d111fdbbf8e7916f6dfe9dcc7c69",
"uri": "urn:uuid:566ff231-e768-41de-bb26-e0def91ceb9b",
"type": "schema:Schema",
"title": "National System for Geospatial Intelligence Metadata Implementation Specification (NMIS) - Part 2: XML Exchange Schema, Version 2.2.0",
"description": "An XML encoding of the NMIS logical model (Part 1) that is conformant to ISO 19139 and the XML Data Encoding Specification for Information Security Marking Metadata (DES.ISM.XML.V9).",
"created": "2016-11-04T14:17:04.903Z",
"namespace": "http://metadata.ces.mil/dse/ns/GSIP/5.0/nas",
"_links": {
"self": {
"href": "http://54.208.90.94/mediation/schemas/f981d111fdbbf8e7916f6dfe9dcc7c69"
}
}
}, {
"id": "315a1576cd09615683160f9f1e84ca97",
"uri": "urn:uuid:02200156-4271-4d52-a2e1-47d268680aa7",
"type": "schema:Schema",
"title": "Department of Defense Discovery Metadata Specification (DDMS), Version 2.0",
"description": "Defines discovery metadata elements for resources posted to community and organizational shared spaces",
"created": "2016-11-04T14:17:05.619Z",
"namespace": "http://metadata.dod.mil/mdr/ns/DDMS/2.0/",
"_links": {
"self": {
"href": "http://54.208.90.94/mediation/schemas/315a1576cd09615683160f9f1e84ca97"
}
}
}]
},
"_links": {
"self": {
"href": "http://54.208.90.94/mediation/schemas"
},
"service": {
"href": "http://54.208.90.94/mediation"
},
"curies": [{
"href": "http://www.opengis.net/rels/mediation/{rel}",
"name": "mediation",
"templated": true
}]
},
"aggregations": [],
"page": {
"size": 20,
"totalElements": 6,
"totalPages": 1,
"number": 0
}
}
Schema
The Schema resource is used to retrieve, update, and delete schema instance.
Retrieve a schema
To retrieve a particular instance of schema, a HTTP GET
request will get the details of a schema. They are two ways to retrieve a instance of a schema, using an internal id in the path or by using its Linked Data URL (using uri as query parameter).
Query Parameters
None
Response structure
The response of the schema instance request is conform to the JSON Schema Model.
Links
The following table describes the link relation types accessible from a schema instance that provide transitions to other states related to the schema instance, in particular the relevant schema mappings that use this schema instance.
Relation | Description |
---|---|
|
Refers to this schema itself |
|
Refers to schemas search endpoint |
|
Refers to schema mappings that accepts this schema as a source schema |
|
Refers to schema mappings that accepts this schema as a target schema |
|
Refers to schema mappings having this schema either as a source or as target schema |
|
Refers to validator service for this schema |
|
Refers to the mediation service |
|
Refers to the curies defined for the links |
Examples
======= HAL+JSON Format Response (Level 3 REST API)
The following HTTP request performs a GET Request to get an instance of a schema in HAL+JSON format.
GET /schemas/66dcd67e36e93540bc77e4710fd749ad HTTP/1.1
Accept: application/hal+json
Host: localhost
The HAL+JSON response contains the description of the schema in JSON-LD (which can be converted to Linked Data by applying the JSON-LD context of the service). In addition, it provides links to other states than be followed by clients following the semantic of the link relation types described in the previous section.
{
"id": "66dcd67e36e93540bc77e4710fd749ad",
"uri": "http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2",
"type": "schema:Schema",
"register": [
"schemas"
],
"title": "National System for Geospatial Intelligence Metadata Implementation Specification (NMIS) - Part 2: XML Exchange Schema, Version 2.2.",
"description": "An XML encoding of the NMIS logical model (Part 1) that is conformant to ISO 19139 and the XML Data Encoding Specification for Information Security Marking Metadata (DES.ISM.XML.V9)",
"created": "2016-10-10T16:09:58.704Z",
"publisher": [{
"name": "National Geospatial Intelligence Agency (NGA)",
"uri": "http://wwww.nga.mil",
"type": "org:Organization"
}],
"keyword": [
"ISO 19139 Profile",
"XML Schema",
"Metadata",
"NGA",
"Geospatial",
"NMIS"
],
"namespace": "http://metadata.ces.mil/dse/ns/GSIP/5.0/nas",
"schemaLanguage": "http://www.w3.org/TR/xmlschema-1/",
"distribution": [{
"title": "NGA.STND.0018_2.2 XML Schema",
"description": "NGA.STND.0018_2.2 XML schema encoding",
"accessURL": "http://schemas.opengis.net/iso/19139/20070417/gmd/gmd.xsd",
"type": "dcat:Distribution",
"representationTechnique": "http://www.w3.org/TR/xmlschema-1/"
}],
"alternative": "NGA.STND.0018_2.2",
"_links": {
"self": {
"href": "http://54.208.90.94/mediation/schemas/66dcd67e36e93540bc77e4710fd749ad"
},
"service": {
"href": "http://54.208.90.94/mediation"
},
"mediation:validator": {
"href": "http://54.208.90.94/mediation/schemas/66dcd67e36e93540bc77e4710fd749ad/validator"
},
"mediation:schemas": {
"href": "http://54.208.90.94/mediation/schemas"
},
"mediation:sourceSchemaMappings": {
"href": "http://54.208.90.94/mediation/schemaMappings?constraint=sourceSchema='http%3A%2F%2Fwww.opengis.net%2Ftestbed12%2Fschemas%23NGA.STND.0018_2.2'"
},
"mediation:targetSchemaMappings": {
"href": "http://54.208.90.94/mediation/schemaMappings?constraint=targetSchema='http%3A%2F%2Fwww.opengis.net%2Ftestbed12%2Fschemas%23NGA.STND.0018_2.2'"
},
"mediation:schemaMappings": {
"href": "http://54.208.90.94/mediation/schemaMappings?constraint=sourceSchema='http%3A%2F%2Fwww.opengis.net%2Ftestbed12%2Fschemas%23NGA.STND.0018_2.2' OR targetSchema='http%3A%2F%2Fwww.opengis.net%2Ftestbed12%2Fschemas%23NGA.STND.0018_2.2'"
},
"curies": [{
"href": "http://www.opengis.net/rels/mediation/{rel}",
"name": "mediation",
"templated": true
}]
}
}
======= JSON(-LD) Format Response (Level 2 REST API)
The following HTTP request performs a GET Request to get an instance of a schema in HAL+JSON format.
GET /schemas/66dcd67e36e93540bc77e4710fd749ad HTTP/1.1
Accept: application/json
Host: localhost
The JSON-(LD) response is identical to the HAL+JSON except it does not have the hyperlinks to other states. The client will need to build the URL to reach other states (by reading documentation of API).
{
"id": "66dcd67e36e93540bc77e4710fd749ad",
"uri": "http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2",
"type": "schema:Schema",
"register": [
"schemas"
],
"title": "National System for Geospatial Intelligence Metadata Implementation Specification (NMIS) - Part 2: XML Exchange Schema, Version 2.2.",
"description": "An XML encoding of the NMIS logical model (Part 1) that is conformant to ISO 19139 and the XML Data Encoding Specification for Information Security Marking Metadata (DES.ISM.XML.V9)",
"created": "2016-10-10T16:09:58.704Z",
"publisher": [{
"name": "National Geospatial Intelligence Agency (NGA)",
"uri": "http://wwww.nga.mil",
"type": "org:Organization"
}],
"keyword": [
"ISO 19139 Profile",
"XML Schema",
"Metadata",
"NGA",
"Geospatial",
"NMIS"
],
"namespace": "http://metadata.ces.mil/dse/ns/GSIP/5.0/nas",
"schemaLanguage": "http://www.w3.org/TR/xmlschema-1/",
"distribution": [{
"title": "NGA.STND.0018_2.2 XML Schema",
"description": "NGA.STND.0018_2.2 XML schema encoding",
"accessURL": "http://schemas.opengis.net/iso/19139/20070417/gmd/gmd.xsd",
"type": "dcat:Distribution",
"representationTechnique": "http://www.w3.org/TR/xmlschema-1/"
}],
"alternative": "NGA.STND.0018_2.2",
}
======= Turtle Format Response (Linked Data API)
The following HTTP request performs a GET Request to get an instance of a schema in Turtle format.
GET /schemas/66dcd67e36e93540bc77e4710fd749ad HTTP/1.1
Accept: text/turtle
Host: localhost
@prefix schema: <http://www.opengis.net/ont/testbed12/srim/profile/schema#> .
@prefix adms: <http://www.w3.org/TR/vocab-adms/#> .
@prefix org: <http://www.socialml.org/ontologies/organization#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix schema-org: <http://schema.org/> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2>
a schema:Schema ;
dct:alternative "NGA.STND.0018_2.2" ;
dct:created "2016-10-10T16:09:58.704Z"^^xsd:dateTime ;
dct:description "An XML encoding of the NMIS logical model (Part 1) that is conformant to ISO 19139 and the XML Data Encoding Specification for Information Security Marking Metadata (DES.ISM.XML.V9)" ;
dct:publisher <http://wwww.nga.mil> ;
dct:title "National System for Geospatial Intelligence Metadata Implementation Specification (NMIS) - Part 2: XML Exchange Schema, Version 2.2." ;
schema:namespace <http://metadata.ces.mil/dse/ns/GSIP/5.0/nas> ;
schema:schemaLanguage <http://www.w3.org/TR/xmlschema-1/> ;
dcat:distribution [ a dcat:Distribution ;
dct:description "NGA.STND.0018_2.2 XML schema encoding" ;
dct:title "NGA.STND.0018_2.2 XML Schema" ;
adms:representationTechnique <http://www.w3.org/TR/xmlschema-1/> ;
dcat:accessURL <http://schemas.opengis.net/iso/19139/20070417/gmd/gmd.xsd>
] ;
dcat:keyword "ISO 19139 Profile" , "XML Schema" , "Metadata" , "NGA" , "Geospatial" , "NMIS" .
<http://wwww.nga.mil>
a org:Organization ;
foaf:name "National Geospatial Intelligence Agency (NGA)" .
Schema Mapping Collection
A Schema Mapping is defining a mapping between a source and target schema. The Schema Mappings resource is used to create and search schema mappings.
JSON Schema
As the registry service can support different item classes and application profiles, the JSON schema supported by the service is not unique. However there is a set of core properties that will always be present for any items in the registry. The following table describes the core minimal properties for a item.
Path | Type | Description | Card. |
---|---|---|---|
|
|
Internal identifier for the schema mapping |
1 |
|
|
Linked Data URI for the schema mapping (equivalent to @id in JSON-LD) |
0..1 |
|
|
The type (class) of the mapping (schema:SchemaMapping or subclass). |
1 |
|
|
The title of the item |
1 |
|
|
The title map for each language of the title . Each key corresponds to the two letter language identifier name defined in the capabilities ( for example "en") |
0..1 |
|
|
The description of the item |
0..1 |
|
|
The description map for each language of the description. Each key corresponds to the two letter language identifier name defined in the capabilities ( for example "en") |
0..1 |
|
|
The date of creation (XSD datetime format) (generated by the service) |
1 |
|
|
The date of the last modification (XSD datetime format) (generated by the service) |
0..1 |
sourceSchema |
URI |
This property stores the schema being mapped from. |
1 |
targetSchema |
URI |
This property holds the schema being mapped to. |
1 |
mappingLanguage |
URI |
This property stores the language used to create a schema mapping. |
1 |
distribution[] |
Array |
Distribution |
0..1 |
distribution[].type |
String |
type of the distribution set to dcat:Distribution |
0..1 |
distribution[].accessURL |
URL |
access url of the distribution |
1 |
distribution[].format |
String |
format distribution |
0..1 |
distribution[].representationTechnique |
URL |
representation technique of the distribution content (XSL, XML Schema) |
0..1 |
Search Schema Mappings
The search of the schema mappings is performed by performing a HTTP GET
request on the Schema Mappings resource. The schema mapping search supports free text, by ids, by uris, CQL constraint and can return results with aggregations on specific facets.
Query Parameters
The following query parameters are supported in the query:
The current parameters supported by the GET request are for paging and sorting.
The following query parameters are supported in the query:
Parameter | Description |
---|---|
|
Text to search in textual fields |
|
One or more URIs of schema mapping instances |
|
One or more id of schema mapping instances |
|
Boolean or list of facet names to include for aggregation computation. If the value is true, include all facets supported by the server. If only a subset of the facets are needed, a comma delimited of field names can be set. |
|
Constraint values of a given facet field name |
|
A constraint expressed in CQL. This is used to express more advanced query filtering |
|
One or more fields to be included in the response. Use JSON path dot notation for referring paths (ex: publisher.name) |
|
The number of the current page as defined in Paging section |
|
The count of items on the current page as defined in Paging section |
|
The sorting parameters as defined in Sorting section. |
Example request
The following performs a schema mapping search between a source schema and target
TODO: include::includes/snippets/mediation/list-schema-mapping-example/http-request.adoc[]
schemaMappings?constraint=sourceSchema=%27https%3A%2F%2Fwww.fgdc.gov%2Fschemas%2Fmetadata%2Ffgdc-std-001-1998%27%20OR%20targetSchema=%27https%3A%2F%2Fwww.fgdc.gov%2Fschemas%2Fmetadata%2Ffgdc-std-001-1998%27
Response structure
The response is structured according the Schema Mapping JSON Schema.
Links
The following link relation types are provided in the response to allow the transition to others states from the schema mappings embedded in the response.
TODO: include::includes/snippets/mediation/list-schema-mappings-example/links.adoc[]
Example response
The embedded objects in the response of the request conforms to the SchemaMapping definition in the SRIM Schema Application Profile. Tne rest of the response return paging information and links to other states.
TODO: include::includes/snippets/mediation/list-schema-mappings-example/http-response.adoc[]
Schema Mapping
The Schema Mapping resource is used to retrieve, update, and delete schema mapping instance. A Schema Mapping
is defined as a transformation from source schema to another. This resource enable search and discovery of schema mappings.
Retrieve a schema mapping
To retrieve a particular instance of schema mapping, a HTTP GET
request will get the details of a schema mapping. They are two ways to retrieve a instance of a schema, using an internal id in the path or by using its Linked Data URL (using uri as query parameter).
Query Parameters
None
Example request
The following HTTP request performs a GET Request to get an instance of a schema mapping:
GET /schemaMappings/2ddf2633f660b1d6f281a989faeec3e6 HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response of the schema mapping instance request is defined by the SchemMapping definition defined in the SRIM Schema Application Profile.
Links
The following table defines the link relation types accessible from a schema mapping instance that provide transitions to other states related to the schema mapping instance.
Relation | Description |
---|---|
|
Refers to this schema itself |
|
Refers to schemas search endpoint |
|
Refers to source schema accepted by this schema mapping |
|
Refers to target schema accepted by this schema mapping |
|
Refers to schema mappings search endpoint |
|
Refers to transformation service for this schema mapping that converts a document compliant to the source schema to a document in the target schema of this mapping. |
|
Refers to the mediation service |
|
Refers to the curies defined for the links |
Example response
======= HAL+JSON Format Response (Level 3 REST API)
The following HTTP request performs a GET Request to get an instance of a schema mapping converting NMIS to DDMS format in HAL+JSON format. The HAL+JSON response contains the description of the schema mapping in JSON-LD (which can be converted to Linked Data by applying the JSON-LD context of the service). In addition, it provides links to other states than be followed by clients following the semantic of the link relation types described in the previous section.
{
"id": "2ddf2633f660b1d6f281a989faeec3e6",
"uri": "http://www.opengis.net/testbed12/schemas#MNIS2DDMS",
"type": "schema:SchemaMapping",
"register": [
"schemas"
],
"title": "NMIS 2.2 to DDMS SchemaMapping",
"description": "Schema Mapping from NMIS 2.2 to DDMS",
"created": "2016-10-10T16:10:06.490Z",
"publisher": [{
"name": "National Geospatial Intelligence Agency (NGA)",
"uri": "http://wwww.nga.mil",
"type": "org:Organization"
}],
"keyword": [
"NAS",
"DDMS",
"XSLT",
"Geospatial",
"NMIS"
],
"sourceSchema": "http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2",
"targetSchema": "http://metadata.dod.mil/mdr/ns/DDMS/2.0",
"mappingLanguage": "https://www.w3.org/TR/xslt20/",
"distribution": [{
"title": "NMIS to DDMS SchemaMapping XSLT Distribution",
"description": "NGA.STND.0018_2.2 to DDMS SchemaMapping XSLT Distribution",
"accessURL": "http://ows.galdosinc.com:80/indicio/query?request=GetRepositoryItem&service=CSW-ebRIM&id=urn:uuid:38ffef44-e1ee-4856-8812-d8b82da497a4",
"type": "dcat:Distribution",
"representationTechnique": "https://www.w3.org/TR/xslt20/"
}],
"_links": {
"self": {
"href": "http://54.208.90.94/mediation/schemaMappings/2ddf2633f660b1d6f281a989faeec3e6"
},
"service": {
"href": "http://54.208.90.94/mediation"
},
"mediation:schemaMappings": {
"href": "http://54.208.90.94/mediation/schemaMappings"
},
"mediation:transform": {
"href": "http://54.208.90.94/mediation/schemaMappings/2ddf2633f660b1d6f281a989faeec3e6/transform"
},
"mediation:sourceSchema": {
"href": "http://54.208.90.94/mediation/schemas/instance?uri=http%3A%2F%2Fwww.opengis.net%2Ftestbed12%2Fschemas%23NGA.STND.0018_2.2"
},
"mediation:targetSchema": {
"href": "http://54.208.90.94/mediation/schemas/instance?uri=http%3A%2F%2Fmetadata.dod.mil%2Fmdr%2Fns%2FDDMS%2F2.0"
},
"curies": [{
"href": "http://www.opengis.net/rels/mediation/{rel}",
"name": "mediation",
"templated": true
}]
}
}
======= JSON(-LD) Format Response (Level 2 REST API)
The following HTTP request performs a GET Request to get an instance of a schema in HAL+JSON format.
GET /schemaMappings/2ddf2633f660b1d6f281a989faeec3e6 HTTP/1.1
Accept: application/json
Host: localhost
The JSON-(LD) response is identical to the HAL+JSON except it does not have the hyperlinks to other states. The client will need to build the URL to reach other states (by reading documentation of API).
{
"id": "2ddf2633f660b1d6f281a989faeec3e6",
"uri": "http://www.opengis.net/testbed12/schemas#MNIS2DDMS",
"type": "schema:SchemaMapping",
"register": [
"schemas"
],
"title": "NMIS 2.2 to DDMS SchemaMapping",
"description": "Schema Mapping from NMIS 2.2 to DDMS",
"created": "2016-10-10T16:10:06.490Z",
"publisher": [{
"name": "National Geospatial Intelligence Agency (NGA)",
"uri": "http://wwww.nga.mil",
"type": "org:Organization"
}],
"keyword": [
"NAS",
"DDMS",
"XSLT",
"Geospatial",
"NMIS"
],
"sourceSchema": "http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2",
"targetSchema": "http://metadata.dod.mil/mdr/ns/DDMS/2.0",
"mappingLanguage": "https://www.w3.org/TR/xslt20/",
"distribution": [{
"title": "NMIS to DDMS SchemaMapping XSLT Distribution",
"description": "NGA.STND.0018_2.2 to DDMS SchemaMapping XSLT Distribution",
"accessURL": "http://ows.galdosinc.com:80/indicio/query?request=GetRepositoryItem&service=CSW-ebRIM&id=urn:uuid:38ffef44-e1ee-4856-8812-d8b82da497a4",
"type": "dcat:Distribution",
"representationTechnique": "https://www.w3.org/TR/xslt20/"
}]
}
======= Turtle Format Response (Linked Data API)
The following HTTP request performs a GET Request to get an instance of a schema in Turtle format.
GET /schemaMappings/2ddf2633f660b1d6f281a989faeec3e6 HTTP/1.1
Accept: text/turtle
Host: localhost
The response in the following:
HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Length: 1617
@prefix schema: <http://www.opengis.net/ont/testbed12/srim/profile/schema#> .
@prefix adms: <http://www.w3.org/TR/vocab-adms/#> .
@prefix pav: <http://purl.org/pav/> .
@prefix org: <http://www.socialml.org/ontologies/organization#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<http://www.opengis.net/testbed12/schemas#MNIS2DDMS>
a schema:SchemaMapping ;
dct:created "2016-11-16T15:06:18.246-05:00"^^xsd:dateTime ;
dct:description "Schema Mapping from NMIS 2.2 to DDMS" ;
dct:modified "2016-11-16T15:06:22.269-05:00"^^xsd:dateTime ;
dct:publisher <http://wwww.nga.mil> ;
dct:title "NMIS 2.2 to DDMS SchemaMapping" ;
schema:mappingLanguage schema:XSLT ;
schema:sourceSchema <http://www.opengis.net/testbed12/schemas#NGA.STND.0018_2.2> ;
schema:targetSchema <http://metadata.dod.mil/mdr/ns/DDMS/2.0> ;
dcat:distribution [ a dcat:Distribution ;
dct:description "NGA.STND.0018_2.2 to DDMS SchemaMapping XSLT Distribution" ;
dct:title "NMIS to DDMS SchemaMapping XSLT Distribution" ;
adms:representationTechnique schema:XSLT ;
dcat:accessURL <http://ows.galdosinc.com:80/indicio/query?request=GetRepositoryItem&service=CSW-ebRIM&id=urn:uuid:38ffef44-e1ee-4856-8812-d8b82da497a4>
] ;
dcat:keyword "NAS" , "DDMS" , "XSLT" , "Geospatial" , "NMIS" .
<http://wwww.nga.mil>
a org:Organization ;
foaf:name "National Geospatial Intelligence Agency (NGA)" .
Validator
A Validator Resource performs validation of data according the schema the validator is associated with.
Validate data
To validate a particular instance of data against a schema, a HTTP GET
request can be used to perform validation against a remote resource accessible from a URL or using a POST with the dataset attached.
Query Parameters
The following query parameters are supported in the query by the GET request.
Parameter | Description | Card. |
---|---|---|
|
URL of the document to validate against a given schema |
1 |
|
URL or the id of the schema to use for validation |
1 |
Links
The following table describes the current link relation types in the HAL validator response
Relation | Description |
---|---|
|
Refers to the schema used for validation |
|
Refers to the document that was used for validation |
|
Refers to validator service |
|
Refers to the mediation service |
|
Refers to the curies defined for the links |
Example request
The following performs a GET Request to get the validation of a ISO 19139 document against the schema ISO 19139 XML Schema identified by the id "3712ab70e045d43a416ce468d295e0ea". The response is request in HAL+JSON.
GET /validate?url=https%3A%2F%2Fcatalog.data.gov%2Fharvest%2Fobject%2F7a7fcccf-b4ba-469d-a3e8-5489105f0ef0&schema=3712ab70e045d43a416ce468d295e0ea
Accept: application/hal+json
Host: localhost
The following performs a POST Request with the dataset to validate with the schema associated with the validator.
TODO: include::includes/snippets/mediation/validator-get-example/http-request.adoc[]
Response structure
If the validation is performed successfully,the service will return a HTTP Code 200 OK with a validation report, adhering the schema described in the table below. If the URL or schema is invalid it will return a error code 400 (bad request).
Path | Type | Description | Cardinality |
---|---|---|---|
status |
|
Status of the validation ( 'valid' or 'invalid') |
1 |
|
|
Unique identifier the schema used for validation |
1 |
|
|
The url of the document that is validated |
1 |
|
|
Array list of validation messages |
0.1 |
|
|
The level of the messsage ('error', 'warning') |
1 |
|
|
The description of the message |
1 |
|
|
The line in which the error occurs |
0..1 |
|
|
The column in which the error occurs |
0..1 |
Example responses
======= HAL Response
The following snippet shows an example of report for a valid document in HAL+JSON format. The response contains links to the document URL (whether external or stored by service) and the schema description URL.
{
"status": "valid",
"schemaId": "3712ab70e045d43a416ce468d295e0ea",
"sourceURL": "https://catalog.data.gov/harvest/object/7a7fcccf-b4ba-469d-a3e8-5489105f0ef0",
"_links": {
"mediation:schema": {
"href": "http://localhost:8083/schemas/3712ab70e045d43a416ce468d295e0ea"
},
"mediation:validator": {
"href": "http://localhost:8083"
},
"service": {
"href": "http://localhost:8083"
},
"mediation:source": {
"href": "https://catalog.data.gov/harvest/object/7a7fcccf-b4ba-469d-a3e8-5489105f0ef0"
},
"curies": [{
"href": "http://www.opengis.net/rels/mediation/{rel}",
"name": "mediation",
"templated": true
}]
}
}
The following snippet shows an example of report for an invalid document in HAL+JSON format.
{
"status": "invalid",
"schemaId": "66dcd67e36e93540bc77e4710fd749ad",
"sourceURL": "http://54.208.90.94/documents/xml/nmisExampleInstanceFull_ISM6.xml",
"messages": [{
"level": "error",
"description": "cvc-elt.1: Cannot find the declaration of element 'nas:MD_Metadata'."
}],
"_links": {
"mediation:schema": {
"href": "http://localhost:8083/schemas/66dcd67e36e93540bc77e4710fd749ad"
},
"mediation:validator": {
"href": "http://localhost:8083"
},
"service": {
"href": "http://localhost:8083"
},
"mediation:source": {
"href": "http://54.208.90.94/documents/xml/nmisExampleInstanceFull_ISM6.xml"
},
"curies": [{
"href": "http://www.opengis.net/rels/mediation/{rel}",
"name": "mediation",
"templated": true
}]
}
}
======= JSON Response
The following snippet shows an example of report for a valid document in JSON format.
{
"status": "valid",
"schemaId": "3712ab70e045d43a416ce468d295e0ea",
"sourceURL": "https://catalog.data.gov/harvest/object/7a7fcccf-b4ba-469d-a3e8-5489105f0ef0"
}
The following snippet shows an example of report for an invalid document in JSON format.
{
"status": "invalid",
"schemaId": "66dcd67e36e93540bc77e4710fd749ad",
"sourceURL": "http://54.208.90.94/documents/xml/nmisExampleInstanceFull_ISM6.xml",
"messages": [{
"level": "error",
"description": "cvc-elt.1: Cannot find the declaration of element 'nas:MD_Metadata'."
}]
}
Transformer Resource
A Transformer Resource performs the transformation data accessible from a URL or from the body of a POST message from a source schema to a target schema.
Transform data from one schema to another
Query Parameters
The following query parameters are supported in the query by the GET request.
Parameter | Description | Card. |
---|---|---|
|
URL of the document compliant to the source schema parameter that needs to be transformed to the target schema indicated in the targetSchema parameter. |
1 |
|
URL or Id of the schema of the source document |
1 |
|
Url of id of the target schema of the transformation. |
1 |
Response structure
If the transformation is performed successfully, we service will return a HTTP Code 200 OK, along with the result dataset compliant with the target schema. If not, a error message will be returned with the code 400 (Bad Request) if the source document is not compliant to the schema, or source and target schema or a path between them cannot be found.
Appendix F: Semantic Portrayal Service REST API
Overview
This document describes the initial version of RESTful Semantic Portrayal Service API. We anticipate that a variety of clients may be using the Semantic Portrayal Service, and as a consequence it is difficult to accommodate the needs of every type of client. It is almost certain that the REST API will evolve and be modified as more requirements and features are added to the service. The hypermedia-driven API provides a robust approach to evolve the API without breaking the client ecosystem, as long as the clients are using the semantics of the link relation types. For this reason, the service has adopted a hypermedia-driven RESTful API by default, which meets level 3 of the Richardson Maturity Model.
The default serialization of the information model in the service is JSON, as it is understood by most programming languages. However, to support machine-processable information, we enforce the JSON to be compatible Linked data by using JSON-LD Context. In this way, data can be converted to Linked Data Representation and be reasoned on and linked to other information expressed as Linked Data. The REST API does support content negotiation to return a response in Linked Data Format (RDF/XML, Turtle, NTriple) when applicable. The REST API in this document provides the core minimum functionalities that are based on the Portrayal Ontologies described in Appendix C.
Note
|
The example URL used in this documentation used the hostname http://localhost:port. This hostname should be replaced by the entry point (baseURL) of the service that you want to access in the format: http://{hostname}:{port}/{rootPath} |
HTTP verbs
The RESTful API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs. The following HTTP verbs are used by the Service.
Verb | Usage |
---|---|
|
Used to retrieve a resource |
|
Used to create a new resource |
|
Used to update an existing resource with a complete update |
|
Used to delete an existing resource |
HTTP status codes
The Service REST API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes. The following table summarizes the status codes and usage.
Status code | Usage |
---|---|
|
The request completed successfully |
|
A new resource has been created successfully. The resource’s URI is available from the response’s
|
|
An update to an existing resource has been applied successfully |
|
The request was malformed. The response body will include an error providing further information |
|
The requested resource did not exist |
|
The request was made of a resource using a request method not supported by that resource; for example, using GET on a form which requires data to be presented via POST, or using PUT on a read-only resource. |
|
The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. |
|
The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. |
|
The Web server encountered an unexpected condition that prevented it from fulfilling the request by the client |
Headers
Every response has the following header(s):
Name | Description |
---|---|
Content-Type |
The Content-Type of the payload, e.g. |
Future headers may be added for managing access control to the resources managed by the service.
Errors
Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:
Path | Type | Description |
---|---|---|
timestamp |
Number |
The time, in milliseconds, at which the error occurred |
status |
Number |
The HTTP status code, e.g. |
error |
String |
The HTTP error that occurred, e.g. |
message |
String |
A description of the cause of the error |
path |
String |
The path to which the request was made |
For example, a request that attempts to apply a non-existent resource to a symbolset item will produce a
400 Bad Request
response:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 189
{
"timestamp" : 1461855421813,
"status" : 400,
"error" : "Bad Request",
"message" : "The resource item 'http://localhost:8080/styles/123' does not exist",
"path" : "/schemas"
}
Paging and Sorting
Paging
Rather than return everything from a large result set, the REST API recognizes some URL parameters that will influence the page size (size
parameter) and starting page number (page
parameter) as well as sorting of the result set (sort
parameter).
See the following example, where we set the page size to 5 and request the third page (page 2) as page numbers are zero-indexed:
GET /symbolsets?page=2&size=5 HTTP/1.1
Host: localhost
The paginated results in HAL format returns the following response:
{
"_embedded": {
...data...
},
"_links": {
"self": {
"href": "http://localhost:8080/symbolsets"
},
"first": {
"href": "http://localhost:8080/symbolsets?page=0&size=5"
},
"prev": {
"href": "http://localhost:8080/symbolsets?page=1&size=5"
},
"next": {
"href": "http://localhost:8080/symbolsets?page=3&size=5"
},
"last": {
"href": "http://localhost:8080/symbolsets?page=5&size=5"
},
},
"page": {
"size": 5,
"totalElements": 27,
"totalPages": 6,
"number": 2
}
}
Each paged response will return links to the first, previous, next, and last page of results based on the current page using the IANA defined link relations first,
prev,
next,
last. If you are currently at the first page of results, however, no prev
link will be rendered. The same is true for the last page of results: no next
link will be rendered.
The paginated results also have extra data about the page settings , including the size of a page, total elements, total pages, and the page number you are currently viewing. This extra information makes it very easy for the consumer to configure UI tools like sliders or indicators to reflect the overall position the user is in viewing the data. For example, the document above shows we are looking at the third page (with page numbers indexed to 0 being the first).
Sorting
The REST API recognizes sorting parameters. To have your results sorted on a particular property, add a sort
URL parameter with the name of the property you want to sort the results on. You can control the direction of the sort by appending a ,
to the the property name plus either asc
or desc
.
The following examples will sort results by title in ascending order:
GET /symbolsets?sort=title,asc HTTP/1.1
Host: www.mydomain.com
To sort the results by more than one property, keep adding as many sort=PROPERTY
parameters as you need. They will be added in the order they appear in the query string.
Search Results
A number of endpoints of the service return search results.They usually supports Level 2 (JSON) and Level 3 response (HAL+JSON). The search results contains the collection of matched items, paging information and optionally faceted aggregation results. The following describes the response structure for each format.
HAL+JSON Search Results
Path | Type | Description |
---|---|---|
|
|
The HAL _embedded field that contains a collection of instances |
embedded._collectionName[] |
|
The array of items instances defined a given JSON schema. The collectionName may varied depending of the types of items contained in the collection. |
|
|
The aggregation results as defined in the Aggregation JSON Schema. This field is optional is no faceted search is performed on the endpoint. |
|
|
The name of the aggregation (or facet) |
|
|
The metrics object containing global statistics of the object |
|
|
The total count of the aggregation |
|
|
The array of buckets of the aggregation |
|
|
The label of the bucket |
|
|
The count of the label for the bucket |
|
|
Links to other states |
|
|
The page state. See <<_paging,Paging section> |
|
|
The page size |
|
|
The total elements matched by the search request |
|
|
The total number of pages in the results |
|
|
The current page number (starts at 0) |
|
|
Array of hypermedia links to other reachable states. |
JSON Search results
When the JSON or JSON-LD response is retrieved, the matched items are placed in an array referred by the results field. Aggregations results are present only when faceted search is performed and paging information are returned.
Path | Type | Description |
---|---|---|
|
|
The array of vocabulary instances that matches the search criteria |
|
|
The aggregation results as defined in the Aggregation JSON Schema. This field is optional is no faceted search is performed on the endpoint. |
|
|
The name of the aggregation (or facet) |
|
|
The metrics object containing global statistics of the object |
|
|
The total count of the aggregation |
|
|
The array of buckets of the aggregation |
|
|
The label of the bucket |
|
|
The count of the label for the bucket |
|
|
The page state. See <<_paging,Paging section> |
|
|
The page size |
|
|
The total elements matched by the search request |
|
|
The total number of pages in the results |
|
|
The current page number (starts at 0) |
Aggregation JSON Schema
In many use cases, it is useful to aggregate the search results according some facets values (number of items per topic, per publisher, etc). Each facet is composed of a name, global metrics (right now only total count is supported), a set of buckets containing a label (unique value of the facet) and the total count for each label within the context of the facet and search results. The JSON schema of the Aggregation results is defined in the following table.
Path | Type | Description |
---|---|---|
|
|
The aggregation results |
|
|
The name of the aggregation (or facet) |
|
|
The metrics object containing global statistics of the object |
|
|
The total count of the aggregation |
|
|
The array of buckets of the aggregation |
|
|
The label of the bucket |
|
|
The count of the label for the bucket |
Resources Summary
The following resources are the core resources supported by the Semantic Portrayal Service.
Resources | Description | Operations |
---|---|---|
Capabilities |
This resource describes the capabilities of the service |
GET |
StyleSet |
represents a collection of Styles and supports search on a collection of StyleSet instances based on search criteria |
GET |
StyleSet |
represents an instance of a StyleSet |
GET |
Styles |
represents a collection of Styles and supports search on a collection of Style instances based on search criteria |
GET |
Style |
represents an instance of a Style |
GET |
SymbolSets |
represents a collection of Symbol Sets and supports search on a collection of symbol sets based on search criteria |
GET |
SymbolSet |
represents a collection of Symbol Sets and supports search on a collection of symbol sets based on search criteria |
GET |
SymbolRenderer |
This resource supports rendering of a symbol to support legend rendering |
GET |
LayerRenderer |
This resource supports rendering of data for a given style |
GET, POST |
JSONLD Context |
This resource returns the JSON-LD context associated with the JSON representation returned by the service |
GET |
SPARQL |
This resource provides a SPARQL service query endpoint that can accomodate more advanced query capabilities on the portrayal information |
GET |
Level 2 REST Endpoints
The following table describes the endpoint URL paths for each resource for a Level 2 REST API. These paths are considered NON-NORMATIVE but rather INFORMATIVE, as changes of path templates may occur in the future, requiring updates of clients and version control of APIs. The use of hypermedia REST API is advised to be isolated from these changes. However we provide this information to support frameworks that work with Level 2 REST API (such as AngularJS)
Path | HTTP Methods | Consume | Produce |
---|---|---|---|
/ |
GET,HEAD |
application/hal+json |
|
/capabilities |
GET,HEAD |
|
|
/stylesets |
GET,HEAD |
|
|
/stylesets/instance |
GET,HEAD |
|
|
/stylesets/{id} |
GET,HEAD |
|
|
/styles |
GET,HEAD |
|
|
/styles/instance |
GET,HEAD |
|
|
/styles/{id} |
GET,HEAD |
|
|
/symbolsets |
GET,HEAD |
|
|
/symbolsets/instance |
GET,HEAD |
|
|
/symbolsets/{id} |
GET,HEAD |
|
|
/symbols |
GET,HEAD |
|
|
/symbols/instance |
GET,HEAD |
|
|
/symbols/{id} |
GET,HEAD |
|
|
/symbols/{id}/render |
GET,HEAD |
|
|
/styles/{id}/render |
GET,HEAD |
|
|
/styles/{id}/render |
POST |
|
|
/sparql |
GET,HEAD |
|
|
/sparql |
POST |
|
|
Link relation types
The following table describes the list of link relation types used by the Semantic Portrayal Service. We use the OGC namespace to define for the relationships that can be reused by other services such as capabilites, apiDocumentation. The links specific to the portrayal service have the following relation type URI template: http://www.opengis.net/rels/portrayal/{rel}.
Relation type | URI | Description |
---|---|---|
ogc:capabilities |
Reference to the capabilities of the service |
|
portrayal:styles |
Reference to a collection of Style instances in the portrayal service |
|
portrayal:style |
Reference to an instance of Style in the portrayal service |
|
portrayal:symbolSets |
Reference to a collection of SymbolSet instances in the portrayal service |
|
portrayal:symbolSet |
Reference to an instance of SymbolSet in the portrayal service |
|
portrayal:symbols |
Reference to a collection of Symbol instances in the portrayal service |
|
portrayal:symbol |
Reference to an instance of Symbol in the portrayal service |
|
portrayal:renderer |
Reference to the portrayal renderer of a symbol or a map layer |
|
ogc:jsonldContext |
Reference to the JSON-LD context to apply to the JSON content to transform it to Linked Data |
|
ogc:documentation |
Reference to the REST documentation of the service |
Content negotiation
Most of the resource can serve multiple representations including:
Format | Mime type | Description |
---|---|---|
HAL+JSON |
application/hal+json |
It is the default format of the service. The JSON payload is compatible with JSON-LD and is aligned with the Portrayal Ontology Ontology. |
JSON-LD |
application/ld+json |
Compliant with the Portrayal Ontology using the JSON-LD context. |
JSON |
application/ljson |
Compliant with the Portrayal Ontology Ontology using the JSON-LD context. |
RDF/XML |
application/rdf+xml |
Compliant with the Portrayal Ontology |
Turtle |
text/turtle |
Compliant with the Portrayal Ontology |
N-Triples |
text/ntriples |
Compliant with thePortrayal Ontology |
Renderers produces different formats depending of their type such as SVG, KML, PNG etc.
Semantic Portrayal Resources
This section describes the list of resources made accessible by the Semantic Portrayal Service. The RESTful API has an entry point (service root) which provides links which represents the current state transitions supported by the service.
Service Root
The root is the entry point of the RESTful Semantic Portrayal service – it is what the client comes into contact with when consuming the API for the first time. If the HATEOAS constraint is to be considered and implemented throughout by clients, then this is the place to start. The root endpoint provides a set of links with well-defined relation types that corresponds to the supported capabilities of the service. As the Semantic Portrayal Service API evolves in the future, there would be many more links, each with it’s own semantics defined by the type of link relation.
The API is considered as RESTful as it is fully discoverable from the root and with no prior knowledge – meaning the client should be able to navigate the API by doing a GET on the root. Moving forward, all state changes are driven by the client using the available and discoverable transitions that the REST API provides in representations (hence Representational State Transfer).
Accessing the root endpoint
To get access to the root of the service and get the list of links, a GET
request is sent to the base url of the service.
Request structure
This request sends a 'GET' request to the base url of the service. Here the HTTP request associated to get the list of links supported by the service:
GET / HTTP/1.1
Host: localhost
Query Parameters
None
Response structure
The response is returning a HAL response (application/hal+json) with the _links object that contains links associated with relation types (used as property names in JSON).
Path | Type | Description |
---|---|---|
@context |
String |
JSON-LD Context applicable to JSON response of the service |
type |
String |
The type of the resource (always Service) |
title |
String |
Title of the service |
description |
String |
Description of the service |
categories |
Array |
Categories of the service |
_links |
Object |
Links to other resources |
Links
The following table describes the current link relation types supported by the service.
Relation | Description |
---|---|
portrayal:capabilities |
Refers to the capabilities of this service. |
portrayal:styles |
Refers to the style search endpoint supported by this service |
portrayal:symbols |
Refers to the symbol search endpoint supported by this service |
portrayal:symbolSets |
Refers to the symbolSet search endpoint supported by this service |
portrayal:renderer |
Refers to the renderer endpoint supported by this service |
portrayal:sparql |
Refers to the SPARQL endpoint supported by this service |
ogc:jsonLdContext |
Refers to JSON Context |
curies |
The curies to use to expand the link relation types to URI |
Example response
The following example response shows the current links supported by the service.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 921
{
"type": "srim:Service",
"title": "Semantic Portrayal Service",
"description": "Semantic Portrayal Service prototype for OGC Testbed12",
"category": [
"http://www.opengis.net/specs/testbed12/semanticPortrayalService"
],
"publisher": [{
"name": "Image Matters LLC",
"uri": "http://www.imagemattersllc.com",
"type": "org:Organization"
}],
"version": "0.1",
"_links": {
"self": {
"href": "http://localhost:8082"
},
"portrayal:capabilities": {
"href": "http://localhost:8082/capabilities"
},
"portrayal:symbols": {
"href": "http://localhost:8082/symbols"
},
"portrayal:symbolsets": {
"href": "http://localhost:8082/symbolsets"
},
"portrayal:styles": {
"href": "http://localhost:8082/styles"
},
"portrayal:renderer": {
"href": "http://localhost:8082/renderer"
},
"ogc:jsonldContext": {
"href": "http://localhost:8082/context"
},
"portrayal:sparql": {
"href": "http://localhost:8082/sparql"
},
"curies": [{
"href": "http://www.opengis.net/rels/portrayal/{rel}",
"name": "portrayal",
"templated": true
}]
}
}
Capabilities
This resource describes the capabilities of the service, including the supported portrayal items, application profiles, formats.
Query Parameters
There is no query parameter to retrieve the capabilities.
Example request
The following is an example of GET Request performed on the Capability resource.
GET /capabilities HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response of Capability request has the following structure:
Path | Type | Description |
---|---|---|
|
|
ItemClasses supported by the registry |
|
|
The ID of the ItemClass |
|
|
The URI of the ItemClass |
|
|
The RDF type of the ItemClass (always srim:ItemClass) |
|
|
The human readable title of the ItemClass |
|
|
The human readable description of the ItemClass |
|
|
The supported graphic format mime types |
|
|
The hypermedia links to other states |
Links
The following table describes the current link relation types in the HAL capabilities response
Relation | Description |
---|---|
|
Reference to the entry point of the service |
|
Refers to this endpoint. |
|
Refers to the curies defined for the links |
Example response
The following example response shows a capability of the service is represented.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 30456
{
"formats": [
"image/svg+xml",
"image/png",
"image/jpeg",
"image/gif",
"image/geotiff"
],
"itemClasses": [{
"id": "style:Style",
"uri": "http://www.opengis.net/ont/portrayal/style#Style",
"type": "srim:ItemClass",
"title": "Style",
"description": "Style class"
}, {
"id": "style:StyleSet",
"uri": "http://www.opengis.net/ont/portrayal/style#StyleSet",
"type": "srim:ItemClass",
"title": "StyleSet",
"description": "StyleSet class"
}, {
"id": "style:SymbolSet",
"uri": "http://www.opengis.net/ont/portrayal/symbol#SymbolSet",
"type": "srim:ItemClass",
"title": "SymbolSet",
"description": "SymbolSet class"
}, {
"id": "style:PortrayalRuleSet",
"uri": "http://www.opengis.net/ont/portrayal/style#PortrayalRuleSet",
"type": "srim:ItemClass",
"title": "Portrayal RuleSet",
"description": "PortrayalRuleSet class"
}, {
"id": "style:FeatureTypeStyle",
"uri": "http://www.opengis.net/ont/portrayal/style#FeatureTypeStyle",
"type": "srim:ItemClass",
"title": "FeatureType Style",
"description": "FeatureType class"
}, {
"id": "symbol:Symbol",
"uri": "http://www.opengis.net/ont/portrayal/symbol#Symbol",
"type": "srim:ItemClass",
"title": "Portrayal Symbol",
"description": "Symbol class"
}, {
"id": "symbol:SymbolSet",
"uri": "http://www.opengis.net/ont/portrayal/symbol#SymbolSet",
"type": "srim:ItemClass",
"title": "Symbol Set",
"description": "SymbolSet Class"
}, {
"id": "style:PortrayalRule",
"uri": "http://www.opengis.net/ont/portrayal/style#PortrayalRule",
"type": "srim:ItemClass",
"title": "Portrayal Rule",
"description": "Portrayal Rule"
}, {
"id": "style:PortrayalRuleList",
"uri": "http://www.opengis.net/ont/portrayal/style#PortrayalRuleList",
"type": "srim:ItemClass",
"title": "Portrayal RuleList",
"description": "Portrayal RuleList "
}, {
"id": "style:PortrayalRuleList",
"uri": "http://www.opengis.net/ont/portrayal/style#PortrayalRuleList",
"type": "srim:ItemClass",
"title": "Portrayal RuleList",
"description": "Portrayal RuleList "
}],
"_links": {
"self": {
"href": "http://localhost:8082/capabilities"
},
"service": {
"href": "http://localhost:8082"
}
}
}
JSON-LD Context
The JSON produced by the Semantic Portrayal Service is compatible with the Portrayal SRIM Application Profile using the Portrayal ontologies described in Appendix C, by using JSON-LD context. The context is made accessible through an endpoint, so it can referred and imported by JSON-LD processor to be converted into a Linked Data representation adhering to the Portrayal SRIM Profile.
Retrieve JSON Context
Query Parameters
There is no query parameter to retrieve the JSON-LD context.
Example request
The following is an example of GET Request performed on the JSON-LD context resource.
GET /context HTTP/1.1
Host: localhost
Response structure
The response of JSON-LD Context is conforming to the standard JSON-LD.
Path | Type | Description |
---|---|---|
@context |
Object |
JSON-LD Context applicable to JSON response of the service |
Example response
The following example response shows a JSON-LD context of the service.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2222
{
"@context": {
"style": "http://www.opengis.net/ont/portrayal/style#",
"symbol": "http://www.opengis.net/ont/portrayal/symbol#",
"symbolizer": "http://www.opengis.net/ont/portrayal/symbolizer#",
"graphic": "http://www.opengis.net/ont/portrayal/graphic#",
"pav": "http://purl.org/pav/",
"dct": "http://purl.org/dc/terms/",
"owl": "http://www.w3.org/2002/07/owl#",
"xsd": "http://www.w3.org/2001/XMLSchema#",
"skos": "http://www.w3.org/2004/02/skos/core#",
"srim": "http://www.opengis.net/ont/testbed/12/srim#",
"rdfs": "http://www.w3.org/2000/01/rdf-schema#",
"dcat": "http://www.w3.org/ns/dcat#",
"iso639-2": "http://id.loc.gov/vocabulary/iso639-2/",
"lingvoj": "http://www.lingvoj.org/ontology#",
"foaf": "http://xmlns.com/foaf/0.1/",
"ldp": "http://www.w3.org/ns/ldp#",
"locn": "http://www.w3.org/ns/locn#",
"adms": "http://www.w3.org/TR/vocab-adms/#",
"extent": "http://www.opengis.net/ont/extent#",
"idvoc": "http://www.opengis.net/ont/identifier#",
"link": "http://www.opengis.net/ont/link#",
"gr": "http://www.heppnetz.de/ontologies/goodrelations/v1#",
"org": "http://www.socialml.org/ontologies/organization#",
"schema": "http://www.opengis.net/ont/testbed12/srim/profile/schema#",
"vcard": "http://www.w3.org/2006/vcard/ns#",
"type": "@type",
"uri": {
"@id": "rdf:id",
"@container": "@language"
},
"value": "@value",
"lang": "@language",
"results": "ldp:contains",
"title": "dct:title",
"titleMap": {
"@id": "dct:title",
"@container": "@language"
},
"description": "dct:description",
"descriptionMap": {
"@id": "dct:description",
"@container": "@language"
},
"prefLabel": "skos:prefLabel",
"prefLabelMap": {
"@id": "skos:prefLabel",
"@container": "@language"
},
"category": {
"@id": "dct:type",
"@type": "@id"
},
"version": "pav:version",
"creator": {
"@id": "dct:creator",
"@type": "@id"
},
"versionNotes": "adms:versionNotes",
"versionNotesMap": {
"@id": "adms:versionNotes",
"@container": "@language"
},
"contributor": {
"@id": "dct:contributor",
"@type": "@id"
},
"publisher": {
"@id": "dct:publisher",
"@type": "@id"
},
"language": {
"@id": "dct:language",
"@type": "@id"
},
"iso2Code": "lingvoj:iso1",
"iso3Code": "lingvoj:iso2",
"label": "rdfs:label",
"name": "foaf:name",
"nameMap": {
"@id": "foaf:name",
"@container": "@language"
},
"sameAs": {
"@id": "owl:sameAs",
"@type": "@id"
},
"distribution": {
"@id": "dcat:distribution",
"@type": "@id"
},
"license": {
"@id": "dct:license",
"@type": "@id"
},
"created": "dct:created",
"issued": "dct:issued",
"modified": "dct:modified",
"mediaType": "dcat:mediaType",
"country-name": "vcard:country-name",
"region": "vcard:region",
"locality": "vcard:locality",
"postal-code": "vcard:postal-code",
"street-address": "vcard:street-address",
"inScheme": {
"@id": "skos:inScheme",
"@type": "@id"
},
"conformsTo": {
"@id": "dct:conformsTo",
"@type": "@id"
},
"page": {
"@id": "foaf:page",
"@type": "@id"
},
"rights": {
"@id": "dct:rights",
"@type": "@id"
},
"hasValue": {
"@id": "vcard:hasValue",
"@type": "@id"
},
"landingPage": {
"@id": "dcat:landingPage",
"@type": "@id"
},
"accrualPeriodicity": {
"@id": "dct:accrualPeriodicity",
"@type": "@id"
},
"purpose": "srim:purpose",
"itemClass": {
"@id": "srim:itemClass",
"@type": "@id"
},
"keyword": "dcat:keyword",
"identifier": "dct:identifier",
"theme": {
"@id": "dcat:theme",
"@type": "@id"
},
"audience": {
"@id": "dct:audience",
"@type": "@id"
},
"function": {
"@id": "srim:function",
"@type": "@id"
},
"subject": {
"@id": "dct:subject",
"@type": "@id"
},
"project": {
"@id": "foaf:project",
"@type": "@id"
},
"hasIdentifier": {
"@id": "id:hasIdentifier",
"@type": "@id"
},
"depiction": {
"@id": "foaf:depiction",
"@type": "@id"
},
"provenance": {
"@id": "dct:provenance",
"@type": "@id"
},
"contactPoint": {
"@id": "dcat:contactPoint",
"@type": "@id"
},
"hasGeographicExtent": {
"@id": "extent:hasGeographicExtent",
"@type": "@id"
},
"temporal": {
"@id": "dct:temporal",
"@type": "@id"
},
"spatial": {
"@id": "dct:spatial",
"@type": "@id"
},
"accessRights": {
"@id": "dct:accessrights",
"@type": "@id"
},
"rightsHolder": {
"@id": "dct:rightsHolder",
"@type": "@id"
},
"subOrganizationOf": {
"@id": "org:subOrganizationOf",
"@type": "@id"
},
"item": {
"@id": "srim:item",
"@type": "@id"
},
"status": "srim:status",
"itemType": {
"@id": "srim:itemType",
"@type": "@id"
},
"organization-name": "vcard:organization-name",
"address": {
"@id": "vcard:address",
"@type": "@id"
},
"fn": "vcard:fn",
"hasEmail": {
"@id": "vcard:hasEmail",
"@type": "@id"
},
"vcardTitle": "vcard:title",
"hasTelephone": {
"@id": "vcard:hasTelephone",
"@type": "@id"
},
"featureType": "style:featureType",
"rules": "style:hasRule",
"symbolSet": "symbol:symbolSet",
"hasRuleSet": "style:hasRuleSet",
"styles": "style:hasStyle",
"ruleset": "style:hasRuleSet",
"minScaleDenominator": "style:minScaleDenominator",
"maxScaleDenominator": "style:maxScaleDenominator",
"constraint": "style:hasConstraint",
"constraintLanguage": "style:constraintLanguage",
"constraintLanguageVersion": "style:constraintLanguageVersion",
"ruleCondition": "style:has",
"body": "style:body",
"browseGraphic": "symbol:browseGraphic",
"specification": "symbol:specification",
"denotes": "symbol:denotes",
"uom": "symbolizer:uom",
"comp-op": "symbolizer:comp-op",
"symbolizer": "symbolizer:symbolizer",
"geometryProperty": "symbolizer:geometryProperty",
"propertyName": "symbolizer:propertyName",
"hasGraphicContent": "graphic:hasGraphicContent",
"graphicObject": "graphic:graphicObject",
"graphicSymbol": "graphic:graphicSymbol",
"mark": "graphic:shape",
"shape": "graphic:graphicObject",
"hasGraphicProperty": "graphic:hasGraphicProperty",
"fontFamily": "graphic:fontFamily",
"fontStyle": "graphic:fontStyle",
"hasColor": "graphic:hasColor",
"fill": "graphic:fill",
"font": "graphic:font",
"graphicStroke": "graphic:graphicStroke",
"graphicFill": "graphic:graphicFill",
"onlineResource": "graphic:onlineResource",
"stroke": "graphic:stroke",
"wellKnownShape": "graphic:wellKnownShape",
"labelPlacement": "graphic:labelPlacement",
"pointPlacement": "graphic:pointPlacement",
"linePlacement": "graphic:linePlacement",
"graphicContent": "graphic:graphicContent",
"externalGraphic": "graphic:externalGraphic",
"graphicProperty": "graphic:graphicProperty",
"colorName": "graphic:colorName",
"cssColor": "graphic:cssColor",
"fill-property": "graphic:fill-property",
"fill-color": "graphic:fill-color",
"fill-opacity": "graphic:fill-opacity",
"font-property": "graphic:font-property",
"font-code": "graphic:font-code",
"font-size": "graphic:font-size",
"font-weight": "graphic:font-weight",
"format": "graphic:format",
"gap": "graphic:gap",
"halo": "graphic:halo",
"radius": "graphic:radius",
"asWKT": "graphic:asWKT",
"initialGap": "graphic:initialGap",
"perpendicularOffset": "graphic:perpendicularOffset",
"stroke-property": "graphic:stroke-property",
"stroke-color": "graphic:stroke-color",
"stroke-dasharray": "graphic:stroke-dasharray",
"stroke-dashoffset": "graphic:stroke-dashoffset",
"stroke-linecap": "graphic:stroke-linecap",
"stroke-linejoin": "graphic:stroke-linejoin",
"stroke-opacity": "graphic:stroke-opacity",
"stroke-linejoin": "graphic:stroke-linejoin",
"stroke-width": "graphic:stroke-width",
"svgPath": "graphic:svgPath",
"anchorPointX": "graphic:anchorPointX",
"anchorPointY": "graphic:anchorPointY",
"opacity": "graphic:opacity",
"inlineContent": "graphic:inlineContent",
"markIndex": "graphic:markIndex",
"textLabel": "graphic:textLabel",
"isRepeated": "graphic:isRepeated",
"isAligned": "graphic:isAligned",
"generalizeLine": "graphic:generalizeLine";
}
}
Styles
A Style defines the set of portrayal rules to apply to some geospatial data. Style has subclasses suchas style:FeatureTypeStyle and style:CoverageStyle. The Styles resource is used to search style instances based on some search criteria.
JSON Schema
The following defines the JSON schema for the Style derived from the Style Ontology defined in Appendix C. It can also be derived from the JSON-LD Context.
Path | Type | Description | Card. |
---|---|---|---|
|
|
Internal identifier for the symbol (which can be used in Level 2 API) |
1 |
|
|
Linked Data URI for the Style (equivalent to @id in JSON-LD) |
0..1 |
|
|
The type (class) of the Style (symbol:Style subclasses such as style:FeatureTypeStyle). |
1 |
|
|
The title of the Style |
1 |
|
|
The title map for each language of the title . Each key corresponds to the two letter language identifier name ( for example "en") |
0..1 |
|
|
The description of the Style |
0..1 |
|
|
The description map for each language of the description. Each key corresponds to the two letter language identifier name ( for example "en") |
0..1 |
|
|
The date of creation (XSD datetime format) (generated by the service) |
1 |
|
|
The date of the last modification (XSD datetime format) (generated by the service) |
0..1 |
featureType |
uri |
URI of FeatureType associated with a FeatureTypeStyle instance |
0..1 |
rules[] |
Object |
Array of PortrayalRule URIs. See ontology for Symbolizer in Appendix C |
1 |
Search Styles
The search of the Styles is performed by performing a HTTP GET
request on the Styles resource. The style search supports free text, by types, ids, or uris, CQL constraint and can return results with aggregations on specific facets.
Query Parameters
The following query parameters are supported in the query:
Parameter | Description | Cardinality |
---|---|---|
|
Text to search in textual fields |
0..1 |
|
One or more Style types (style:FeatureTypeStyle or other subclasses) |
0..n |
|
One or more URIs of Style instances |
0..n |
|
One or more id of Style instances |
0..n |
|
Boolean or list of facet names to include for aggregation computation. If the value is true, include all facets supported by the server. If only a subset of the facets are needed, a comma delimited of field names can be set. |
0..1 |
|
Constraint values of a given facet field name |
0..n |
|
A constraint expressed in CQL. This is used to express more advanced query filtering |
0..1 |
|
One or more fields to be included in the response. Use JSON path dot notation for referring paths |
0..n |
|
The number of the current page as defined in Paging section |
0..1 |
|
The count of items on the current page as defined in Paging section |
0..1 |
|
The sorting parameters as defined in Sorting section. |
0..n |
Example request
The following request performs a style search of all types
GET /styles HTTP/1.1
Accept: application/hal+json
Host: localhost
The following request search styles for the featureType 'http://www.opengis.net/testbed11/ont/incident/ems#EMSIncident using a CQL constraint
(featureType='http://www.opengis.net/testbed11/ont/incident/ems#EMSIncident')
GET /styles?constraint=(featureType=%27http%3A%2F%2Fwww.opengis.net%2Ftestbed11%2Font%2Fincident%2Fems%23EMSIncident%27) HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response search is structured according the Search Results Schema. The items of the results conforms to the Style JSON Schema. The collection name used in the _ embedded section of the HAL response is called portrayal:items.
Links
The following link relation types are provided in the response to allow the transition to others states from the Style search results embedded in the response.
Relation | Description |
---|---|
|
Refers to this resource itself |
|
Refers to the root of the portrayal service |
|
Refers to the curies defined for the links |
|
The first page of results |
|
The last page of results |
|
The next page of results |
|
The previous page of results |
Example response
======= HAL+JSON Response
The embedded objects in the response of the request conforms to the Style JSON Schema. The collection name used in the _ embedded section of the HAL response is called portrayal:items. . Tne rest of the response return paging information and links to other states.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 2707
{
"_embedded": {
"portrayal:items": [{
"id": "345a19896b477721787a82742cc04770",
"uri": "http://www.opengis.net/testbed/12/portrayal/ems/style#EMSIncidentStyle",
"type": "style:FeatureTypeStyle",
"title": "EMS Incident Type Style",
"description": "EMS Incident Type Style",
"created": "2016-11-18T03:18:12.661Z",
"modified": "2016-11-18T03:18:15.024Z",
"_links": {
"self": {
"href": "http://localhost:8082/styles/345a19896b477721787a82742cc04770"
}
}
}, {
"id": "c7a30cb460ad27d98fc4ddd303a7c4ab",
"uri": "http://www.opengis.net/testbed/12/portrayal/hswg/style#HSWGIncidentStyle",
"type": "style:FeatureTypeStyle",
"title": "HSWG Incident Type Style",
"description": "HSWG Incident Type Style",
"created": "2016-11-18T03:18:15.457Z",
"modified": "2016-11-18T03:18:15.842Z",
"_links": {
"self": {
"href": "http://localhost:8082/styles/c7a30cb460ad27d98fc4ddd303a7c4ab"
}
}
}]
},
"_links": {
"self": {
"href": "http://localhost:8082/styles"
},
"service": {
"href": "http://localhost:8082"
},
"curies": [{
"href": "http://www.opengis.net/rels/portrayal/{rel}",
"name": "portrayal",
"templated": true
}]
},
"aggregations": [],
"page": {
"size": 20,
"totalElements": 2,
"totalPages": 1,
"number": 0
}
}
======= JSON Response
The result objects in the response of the request conforms to the Style JSON Schema. The rest of the response return paging information.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 850
{
"results": [{
"id": "345a19896b477721787a82742cc04770",
"uri": "http://www.opengis.net/testbed/12/portrayal/ems/style#EMSIncidentStyle",
"type": "style:FeatureTypeStyle",
"title": "EMS Incident Type Style",
"description": "EMS Incident Type Style",
"created": "2016-11-18T03:18:12.661Z",
"modified": "2016-11-18T03:18:15.024Z"
}, {
"id": "c7a30cb460ad27d98fc4ddd303a7c4ab",
"uri": "http://www.opengis.net/testbed/12/portrayal/hswg/style#HSWGIncidentStyle",
"type": "style:FeatureTypeStyle",
"title": "HSWG Incident Type Style",
"description": "HSWG Incident Type Style",
"created": "2016-11-18T03:18:15.457Z",
"modified": "2016-11-18T03:18:15.842Z"
}],
"page": {
"size": 20,
"number": 0,
"totalElements": 2
}
}
Style
The Style resource is used to retrieve a Style instance.
Retrieve a Style
To retrieve a particular instance of Style, a HTTP GET
request will get the details of a Style. They are two ways to retrieve a instance of a style, using an internal id in the path or by using its Linked Data URL (using uri as query parameter).
Query Parameters
Parameter | Description | Cardinality |
---|---|---|
uri |
URI of the style if the instance needs to be retrieved by URI. URI should be encoded to escape special characters. |
0..1 |
Example request
The following HTTP request performs a GET Request to get an instance of a style identified by its internal id 345a19896b477721787a82742cc04770
GET /styles/345a19896b477721787a82742cc04770 HTTP/1.1
Accept: application/hal+json
Host: localhost
The following query get the instance identified by the URI http://www.opengis.net/testbed/12/portrayal/ems/style#EMSIncidentStyle
GET /styles/instance?uri=http%3A%2F%2Fwww.opengis.net%2Ftestbed%2F12%2Fportrayal%2Fems%2Fstyle%23EMSIncidentStyle HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response of the instance request can be retrieved in HAL+JSON, JSON-LD and Linked Data formats. The JSON Structure of the reponse conforms to the Style JSON Schema. The Linked Data formats conforms to the Style Ontology.
Links
The following table defines the link relation types accessible from a style instance that provide transitions to other states related to the style instance.
Relation | Description |
---|---|
|
Refers to this resource itself |
|
Refers to the root of the portrayal service |
|
Refers to the style search endpoint |
|
Refers to the curies defined for the links |
Example response
======= HAL+JSON Format Response (Level 3 REST API)
The HAL+JSON response contains the description of the Style in JSON-LD (which can be converted to Linked Data by applying the JSON-LD context of the service). In addition, it provides links to other states that can be followed by clients following the semantic of the link relation types described in the Style Link section.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1895
{
"id": "345a19896b477721787a82742cc04770",
"uri": "http://www.opengis.net/testbed/12/portrayal/ems/style#EMSIncidentStyle",
"type": "style:FeatureTypeStyle",
"title": "EMS Incident Type Style",
"description": "EMS Incident Type Style",
"created": "2016-11-18T03:18:12.661Z",
"modified": "2016-11-18T03:18:15.024Z",
"featureType": "http://www.opengis.net/testbed11/ont/incident/ems#EMSIncident",
"rules": [
"http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.wind.strongWind-portrayal-rule",
"http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.geophysical.magneticStorm-portrayal-rule",
"http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.crime.bombThreat-portrayal-rule",
"http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.hazardousMaterial.biologicalHazard-portrayal-rule",
.... truncated ....
"http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.geophysical.earthquake-portrayal-rule",
"http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.crime.bombExplosion-portrayal-rule"
],
"_links": {
"self": {
"href": "http://localhost:8082/styles/345a19896b477721787a82742cc04770"
},
"portrayal:styles": {
"href": "http://localhost:8082/styles"
},
"service": {
"href": "http://localhost:8082"
},
"curies": [{
"href": "http://www.opengis.net/rels/portrayal/{rel}",
"name": "portrayal",
"templated": true
}]
}
}
======= JSON(-LD) Format Response (Level 2 REST API)
The following HTTP request performs a GET Request to get an instance of a Style in JSON format.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1495
{
"id": "345a19896b477721787a82742cc04770",
"uri": "http://www.opengis.net/testbed/12/portrayal/ems/style#EMSIncidentStyle",
"type": "style:FeatureTypeStyle",
"title": "EMS Incident Type Style",
"description": "EMS Incident Type Style",
"created": "2016-11-18T03:18:12.661Z",
"modified": "2016-11-18T03:18:15.024Z",
"featureType": "http://www.opengis.net/testbed11/ont/incident/ems#EMSIncident",
"rules": [
"http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.wind.strongWind-portrayal-rule",
"http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.geophysical.magneticStorm-portrayal-rule",
"http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.crime.bombThreat-portrayal-rule",
"http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.hazardousMaterial.biologicalHazard-portrayal-rule",
.... truncated ....
"http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.geophysical.earthquake-portrayal-rule",
"http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.crime.bombExplosion-portrayal-rule"
]
}
The JSON-(LD) response is identical to the HAL+JSON except it does not have the hyperlinks to other states. The client will need to build the URL to reach other states (by reading documentation of API).
======= Turtle Format Response (Linked Data API)
The following HTTP request performs a GET Request to get an instance of a Style in Turtle format.
GET /styles/345a19896b477721787a82742cc04770 HTTP/1.1
Accept: text/turtle
Host: localhost
The response returns a TTL document that can processed and interpreted by machine using the Style ontology.
HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Length: 10395
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix style: <http://www.opengis.net/ont/portrayal/style#> .
<http://www.opengis.net/testbed/12/portrayal/ems/style#EMSIncidentStyle>
a style:FeatureTypeStyle ;
dcterms:created "2016-11-18T03:18:12.661Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ;
dcterms:description "EMS Incident Type Style" ;
dcterms:modified "2016-11-18T03:18:15.024Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> ;
dcterms:title "EMS Incident Type Style" ;
style:featureType <http://www.opengis.net/testbed11/ont/incident/ems#EMSIncident> ;
style:hasRule
<http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.wind.strongWind-portrayal-rule> ,
<http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.geophysical.magneticStorm-portrayal-rule> ,
<http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.crime.bombThreat-portrayal-rule> ,
.... truncated.....
<http://www.opengis.net/testbed/12/portrayal/ems/style#ems.incident.crime.bombExplosion-portrayal-rule> .
Render Geospatial Data (Proposed)
To render a particular dataset, a HTTP GET
request will be performed on the style renderer endpoint is performed. The request should accept one of the supported graphic formats advertised in the capabilities by the service. The endpoint provides tha ability to customize the size of the graphic returned in the response.
Query Parameters
Parameter | Type | Description | Cardinality |
---|---|---|---|
url |
String |
URL to access geospatial data |
|
style |
String |
Identifier of a style (id or URI) |
1 |
bbox |
String |
Bounding box geospatial data to render in the given CRS |
1 |
crs |
String |
Coordinate Reference System (default is EPSG:4326) |
0..1 |
width |
integer |
Width in pixel of the rendered map layer |
0..1 |
height |
integer |
Height in pixel of the rendered map layer |
0..1 |
Response Structure
The Response of the render action is according the mime format accepted by the renderer, which is defined in the capabilities resource.
Symbols
A Symbol defines a graphic representation of a feature. The Symbols resource is used to search symbol instances based on some search criteria.
JSON Schema
The following defines the JSON schema for the Symbol derived from the Symbol Ontology defined in Appendix C. The JSON-LD Context of the service can be used to convert the JSON document compliant to this schema to the Linked Data Representation.
Path | Type | Description | Card. |
---|---|---|---|
|
|
Internal identifier for the symbol (which can be used in Level 2 API) |
1 |
|
|
Linked Data URI for the Symbol (equivalent to @id in JSON-LD) |
0..1 |
|
|
The type (class) of the Symbol (symbol:Symbol or (future) subclasses). |
1 |
|
|
The title of the symbol |
1 |
|
|
The title map for each language of the title . Each key corresponds to the two letter language identifier name ( for example "en") |
0..1 |
|
|
The description of the item |
0..1 |
|
|
The description map for each language of the description. Each key corresponds to the two letter language identifier name ( for example "en") |
0..1 |
|
|
The date of creation (XSD datetime format) (generated by the service) |
1 |
|
|
The date of the last modification (XSD datetime format) (generated by the service) |
0..1 |
symbolizers[] |
Array |
Array of symbolizers used to render the symbol. See ontology for Symbolizer in Appendix C |
1 |
Search Symbols
The search of the Symbols is performed by performing a HTTP GET
request on the Symbols resource. The symbol search supports free text, by ids, by uris, CQL constraint and can return results with aggregations on specific facets.
Query Parameters
The following query parameters are supported in the query:
Parameter | Description | Cardinality |
---|---|---|
|
Text to search in textual fields |
0..1 |
|
One or more URIs of Symbol instances |
0..n |
|
One or more id of Symbol instances |
0..n |
|
Boolean or list of facet names to include for aggregation computation. If the value is true, include all facets supported by the server. If only a subset of the facets are needed, a comma delimited of field names can be set. |
0..1 |
|
Constraint values of a given facet field name |
0..n |
|
A constraint expressed in CQL. This is used to express more advanced query filtering |
0..1 |
|
One or more fields to be included in the response. Use JSON path dot notation for referring paths |
0..n |
|
The number of the current page as defined in Paging section |
0..1 |
|
The count of items on the current page as defined in Paging section |
0..1 |
|
The sorting parameters as defined in Sorting section. |
0..n |
Example request
The following performs a symbol search containing the keyword 'Rail'.
GET /symbols?q=Rail HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response search is structured according the Search Results Schema. The items of the results conforms to the Symbol JSON Schema. The collection name used in the _ embedded section of the HAL response is called portrayal:items.
Links
The following link relation types are provided in the response to allow the transition to others states from the symbol search results embedded in the response.
Relation | Description |
---|---|
|
Refers to this resource itself |
|
Refers to the root of the portrayal service |
|
Refers to the curies defined for the links |
|
The first page of results |
|
The last page of results |
|
The next page of results |
|
The previous page of results |
Example response
======= HAL+JSON Response
The embedded objects in the response of the request conforms to the Symbol JSON Schema. The collection name used in the _ embedded section of the HAL response is called portrayal:items. . Tne rest of the response return paging information and links to other states.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 2707
{
"_embedded": {
"portrayal:items": [{
"id": "41f4b3ed5976016d071cf30498bf6358",
"uri": "http://www.opengis.net/testbed/12/hswg/symbols#RailHijackingSymbol",
"type": "symbol:Symbol",
"title": "Rail Hijacking",
"created": "2016-11-17T15:41:35.436Z",
"modified": "2016-11-17T15:41:35.951Z",
"_links": {
"self": {
"href": "http://localhost:8082/symbols/41f4b3ed5976016d071cf30498bf6358"
}
}
}, {
"id": "d6c8d924a629514d322bb25f563f8948",
"uri": "http://www.opengis.net/testbed/12/hswg/symbols#RailAccidentSymbol",
"type": "symbol:Symbol",
"title": "Rail Accident",
"created": "2016-11-17T15:42:18.602Z",
"modified": "2016-11-17T15:42:18.717Z",
"_links": {
"self": {
"href": "http://localhost:8082/symbols/d6c8d924a629514d322bb25f563f8948"
}
}
}, {
"id": "d6792c5cb00daa3b9e2c161846cc7ef4",
"uri": "http://www.opengis.net/testbed/12/hswg/symbols#RailIncidentSymbol",
"type": "symbol:Symbol",
"title": "Rail Incident",
"created": "2016-11-17T15:42:11.281Z",
"modified": "2016-11-17T15:42:11.712Z",
"_links": {
"self": {
"href": "http://localhost:8082/symbols/d6792c5cb00daa3b9e2c161846cc7ef4"
}
}
}]
},
"_links": {
"self": {
"href": "http://localhost:8082/symbols?q=Rail"
},
"service": {
"href": "http://localhost:8082"
},
"curies": [{
"href": "http://www.opengis.net/rels/portrayal/{rel}",
"name": "portrayal",
"templated": true
}]
},
"aggregations": [],
"page": {
"size": 20,
"totalElements": 3,
"totalPages": 1,
"number": 0
}
}
======= JSON Response
The result objects in the response of the request conforms to the Symbol JSON Schema. The rest of the response return paging information.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1007
{
"results": [{
"id": "41f4b3ed5976016d071cf30498bf6358",
"uri": "http://www.opengis.net/testbed/12/hswg/symbols#RailHijackingSymbol",
"type": "symbol:Symbol",
"title": "Rail Hijacking",
"created": "2016-11-17T15:41:35.436Z",
"modified": "2016-11-17T15:41:35.951Z"
}, {
"id": "d6c8d924a629514d322bb25f563f8948",
"uri": "http://www.opengis.net/testbed/12/hswg/symbols#RailAccidentSymbol",
"type": "symbol:Symbol",
"title": "Rail Accident",
"created": "2016-11-17T15:42:18.602Z",
"modified": "2016-11-17T15:42:18.717Z"
}, {
"id": "d6792c5cb00daa3b9e2c161846cc7ef4",
"uri": "http://www.opengis.net/testbed/12/hswg/symbols#RailIncidentSymbol",
"type": "symbol:Symbol",
"title": "Rail Incident",
"created": "2016-11-17T15:42:11.281Z",
"modified": "2016-11-17T15:42:11.712Z"
}],
"page": {
"size": 20,
"number": 0,
"totalElements": 3
}
}
Symbol
The Symbol resource is used to retrieve a Symbol instance.
Retrieve a Symbol
To retrieve a particular instance of Symbol, a HTTP GET
request will get the details of a Symbol. They are two ways to retrieve a instance of a schema, using an internal id in the path or by using its Linked Data URL (using uri as query parameter).
Query Parameters
Parameter | Description | Cardinality |
---|---|---|
uri |
URI of the symbol if the instance needs to be retrieved by URI. URI should be encoded to escape special characters. |
0..1 |
Example request
The following HTTP request performs a GET Request to get an instance of a symbol identified by its internal id 06aab0337e96ea6e2535a2620b8e9a90
GET /symbols/06aab0337e96ea6e2535a2620b8e9a90 HTTP/1.1
Accept: application/hal+json
Host: localhost
The following query get the instance identified by the URI http://www.opengis.net/testbed/12/ems/symbols#ems.incident.wind-symbol
GET /symbols/instance?uri=http%3A%2F%2Fwww.opengis.net%2Ftestbed%2F12%2Fems%2Fsymbols%23ems.incident.wind-symbol HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response of the instance request can be retrieved in HAL+JSON, JSON-LD and Linked Data formats. The JSON Structure of the reponse conforms to the Symbol JSON Schema. The Linked Data formats conform to the Symbol Ontology.
Links
The following table defines the link relation types accessible from a symbol instance that provide transitions to other states related to the symbol instance.
Relation | Description |
---|---|
|
Refers to this resource itself |
|
Refers to the root of the portrayal service |
|
Refers to the symbols search endpoint |
|
Refers to the renderer of the symbol. |
|
Refers to the curies defined for the links |
Example response
======= HAL+JSON Format Response (Level 3 REST API)
The HAL+JSON response contains the description of the Symbol in JSON-LD (which can be converted to Linked Data by applying the JSON-LD context of the service). In addition, it provides links to other states that can be followed by clients following the semantic of the link relation types described in the Symbol Link section.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1895
{
"id": "06aab0337e96ea6e2535a2620b8e9a90",
"uri": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.wind-symbol",
"type": "symbol:Symbol",
"register": [
"portrayal"
],
"title": "wind",
"created": "2016-11-17T15:39:40.261Z",
"modified": "2016-11-17T15:39:40.711Z",
"symbolName": "ems.incident.wind",
"specification": "https://cms.masas-x.ca.s3.amazonaws.com/EMS_Symbology_v1.0.pdf",
"symbolSet": "http://www.opengis.net/testbed/12/ems/symbols#EMSSymbolSet",
"browseGraphic": {
"type": "graphic:ExternalGraphic",
"uri": "http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.wind.png",
"title": "ems.incident.wind icon",
"description": "icon for ems.incident.wind",
"onlineResource": "http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.wind.png",
"format": "image/png"
},
"symbolizers": [{
"uri": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.wind-pointSymbolizer",
"type": "symbolizer:PointSymbolizer",
"title": "PointSymbolizer for wind symbol",
"graphicSymbol": {
"type": "graphic:GraphicSymbol",
"externalGraphic": {
"type": "graphic:ExternalGraphic",
"uri": "http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.wind.png",
"title": "ems.incident.wind icon",
"description": "icon for ems.incident.wind",
"onlineResource": "http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.wind.png",
"format": "image/png"
}
}
}],
"denotes": [
"http://www.opengis.net/taxonomy/ems#ems.incident.wind"
],
"_links": {
"self": {
"href": "http://localhost:8082/symbols/06aab0337e96ea6e2535a2620b8e9a90"
},
"portrayal:render": {
"href": "http://localhost:8082/symbols/06aab0337e96ea6e2535a2620b8e9a90/render"
},
"portrayal:symbols": {
"href": "http://localhost:8082/symbols"
},
"service": {
"href": "http://localhost:8082"
},
"curies": [{
"href": "http://www.opengis.net/rels/portrayal/{rel}",
"name": "portrayal",
"templated": true
}]
}
}
======= JSON(-LD) Format Response (Level 2 REST API)
The following HTTP request performs a GET Request to get an instance of a Symbol in JSON format.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1495
{
"id": "06aab0337e96ea6e2535a2620b8e9a90",
"uri": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.wind-symbol",
"type": "symbol:Symbol",
"register": [
"portrayal"
],
"title": "wind",
"created": "2016-11-17T15:39:40.261Z",
"modified": "2016-11-17T15:39:40.711Z",
"symbolName": "ems.incident.wind",
"specification": "https://cms.masas-x.ca.s3.amazonaws.com/EMS_Symbology_v1.0.pdf",
"symbolSet": "http://www.opengis.net/testbed/12/ems/symbols#EMSSymbolSet",
"browseGraphic": {
"type": "graphic:ExternalGraphic",
"uri": "http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.wind.png",
"title": "ems.incident.wind icon",
"description": "icon for ems.incident.wind",
"onlineResource": "http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.wind.png",
"format": "image/png"
},
"symbolizers": [{
"uri": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.wind-pointSymbolizer",
"type": "symbolizer:PointSymbolizer",
"title": "PointSymbolizer for wind symbol",
"graphicSymbol": {
"type": "graphic:GraphicSymbol",
"externalGraphic": {
"type": "graphic:ExternalGraphic",
"uri": "http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.wind.png",
"title": "ems.incident.wind icon",
"description": "icon for ems.incident.wind",
"onlineResource": "http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.wind.png",
"format": "image/png"
}
}
}],
"denotes": [
"http://www.opengis.net/taxonomy/ems#ems.incident.wind"
]
}
The JSON-(LD) response is identical to the HAL+JSON except it does not have the hyperlinks to other states. The client will need to build the URL to reach other states (by reading documentation of API).
======= Turtle Format Response (Linked Data API)
The following HTTP request performs a GET Request to get an instance of a Symbol in Turtle format.
GET /symbols/06aab0337e96ea6e2535a2620b8e9a90 HTTP/1.1
Accept: text/turtle
Host: localhost
The response returns a TTL document that can processed and interpreted by machine using the Portrayal ontology.
HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Length: 1395
@prefix symbol: <http://www.opengis.net/ont/portrayal/symbol#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
<http://www.opengis.net/testbed/12/ems/symbols#ems.incident.wind-symbol>
a symbol:Symbol ;
dcterms:title "wind" ;
symbol:browseGraphic <http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.wind.png> ;
symbol:specification <https://cms.masas-x.ca.s3.amazonaws.com/EMS_Symbology_v1.0.pdf> ;
symbol:symbolName "ems.incident.wind" ;
symbol:symbolSet <http://www.opengis.net/testbed/12/ems/symbols#EMSSymbolSet> ;
<http://www.opengis.net/ont/portrayal/symbolizer#symbolizer>
<http://www.opengis.net/testbed/12/ems/symbols#ems.incident.wind-pointSymbolizer> .
<http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.wind.png>
a <http://www.opengis.net/ont/portrayal/graphic#ExternalGraphic> ;
dcterms:description "icon for ems.incident.wind" ;
dcterms:title "ems.incident.wind icon" ;
<http://www.opengis.net/ont/portrayal/graphic#format>
"image/png" ;
<http://www.opengis.net/ont/portrayal/graphic#onlineResource>
"http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.wind.png" .
<http://www.opengis.net/testbed/12/ems/symbols#ems.incident.wind-pointSymbolizer>
a <http://www.opengis.net/ont/portrayal/symbolizer#PointSymbolizer> ;
dcterms:title "PointSymbolizer for wind symbol" ;
<http://www.opengis.net/ont/portrayal/graphic#graphicSymbol>
[ a <http://www.opengis.net/ont/portrayal/graphic#GraphicSymbol> ;
<http://www.opengis.net/ont/portrayal/graphic#externalGraphic>
<http://ows.usersmarts.com/ems/icons/tier1/Base/ems.incident.wind.png>
] .
Symbol Renderer
The Symbol Renderer resource is used to render a symbol into a graphic representation such as SVG, PNG, TIFF, JPEG using its symbolizer definitions. This endpoint provides the ability to render the symbol into different formats and size.
Render a Symbol
To render a particular instance of Symbol, a HTTP GET
request will get on the symbol renderer endpoint is performed. The request should accept one of the supported graphic formats advertised in the capabilities by the service. The endpoint provides the ability to customize the size of the graphic returned in the response.
Query Parameters
Parameter | Type | Description | Cardinality |
---|---|---|---|
width |
integer |
Width in pixel of the rendered symbol |
0..1 |
height |
integer |
Height in pixel of the rendered symbol |
0..1 |
Response Structure
The Response of the render action is according the mime format accepted by the renderer, which is defined in the capabilities resource.
Examples
The following example requests the renderer to render the symbol Wind Incident to a PNG image of size 512x 512.
GET /symbols/06aab0337e96ea6e2535a2620b8e9a90/render?width=512&height=512 HTTP/1.1
Accept: image/png
Host: localhost
The image produces is the following:
SymbolSets
A SymbolSet defines a set of Symbols. The SymbolSets resource is used to search SymbolSet instances based on some search criteria.
JSON Schema
The following defines the JSON schema for the SymbolSet derived from the Symbol Ontology defined in Appendix C. It can also be derived from the JSON-LD Context
Path | Type | Description | Card. |
---|---|---|---|
|
|
Internal identifier for the SymbolSet (which can be used in Level 2 API) |
1 |
|
|
Linked Data URI for the SymbolSet (equivalent to @id in JSON-LD) |
0..1 |
|
|
The type (class) of the SymbolSet (symbol:SymbolSet). |
1 |
|
|
The title of the symbol |
1 |
|
|
The title map for each language of the title . Each key corresponds to the two letter language identifier name ( for example "en") |
0..1 |
|
|
The description of the item |
0..1 |
|
|
The description map for each language of the description. Each key corresponds to the two letter language identifier name ( for example "en") |
0..1 |
|
|
The date of creation (XSD datetime format) (generated by the service) |
1 |
|
|
The date of the last modification (XSD datetime format) (generated by the service) |
0..1 |
|
|
The reference to a specification document |
0..1 |
symbols[] |
Array |
Array of symbols URIs. |
0..1 |
Search SymbolSets
The search of the SymbolSets is performed by performing a HTTP GET
request on the SymbolSets resource. The symbolSet search supports free text, by ids, by uris, CQL constraint and can return results with aggregations on specific facets.
Query Parameters
The following query parameters are supported in the query:
Parameter | Description | Cardinality |
---|---|---|
|
Text to search in textual fields |
0..1 |
|
One or more URIs of Symbol instances |
0..n |
|
One or more id of Symbol instances |
0..n |
|
Boolean or list of facet names to include for aggregation computation. If the value is true, include all facets supported by the server. If only a subset of the facets are needed, a comma delimited of field names can be set. |
0..1 |
|
Constraint values of a given facet field name |
0..n |
|
A constraint expressed in CQL. This is used to express more advanced query filtering |
0..1 |
|
One or more fields to be included in the response. Use JSON path dot notation for referring paths |
0..n |
|
The number of the current page as defined in Paging section |
0..1 |
|
The count of items on the current page as defined in Paging section |
0..1 |
|
The sorting parameters as defined in Sorting section. |
0..n |
Example request
The following performs a symbolSet search containing the keyword 'Rail'.
GET /symbolsets HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response search is structured according the Search Results Schema. The items of the results conform to the SymbolSet JSON Schema. The collection name used in the _ embedded section of the HAL response is called portrayal:items.
Links
The following link relation types are provided in the response to allow the transition to others states from the symbolSet search results embedded in the response.
Relation | Description |
---|---|
|
Refers to this resource itself |
|
Refers to the root of the portrayal service |
|
Refers to the curies defined for the links |
|
The first page of results |
|
The last page of results |
|
The next page of results |
|
The previous page of results |
Example response
======= HAL+JSON Response
The embedded objects in the response of the request conforms to the SymbolSet JSON Schema. The collection name used in the _ embedded section of the HAL response is called portrayal:items. . Tne rest of the response return paging information and links to other states.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 2707
{
"_embedded": {
"portrayal:items": [{
"id": "4cabf46007df9b652151927033e265c6",
"uri": "http://www.opengis.net/testbed/12/ems/symbols#EMSSymbolSet",
"type": "symbol:SymbolSet",
"description": "Standard Canadian Emergency Mapping Symbology (EMS) SymbolSet version 1.0",
"created": "2016-11-17T15:38:35.856Z",
"modified": "2016-11-17T15:38:36.457Z",
"_links": {
"self": {
"href": "http://localhost:8082/symbolsets/4cabf46007df9b652151927033e265c6"
}
}
}, {
"id": "bf83c8b6f4033ffd4c93a2be14ebe476",
"uri": "http://www.opengis.net/testbed/12/hswg/symbols#HSWGSymbolSet",
"type": "symbol:SymbolSet",
"description": "Home Security Working Group (HSWG) SymbolSet version 1.0",
"created": "2016-11-17T15:38:37.357Z",
"modified": "2016-11-17T15:38:37.786Z",
"_links": {
"self": {
"href": "http://localhost:8082/symbolsets/bf83c8b6f4033ffd4c93a2be14ebe476"
}
}
}]
},
"_links": {
"self": {
"href": "http://localhost:8082/symbolsets"
},
"service": {
"href": "http://localhost:8082"
},
"curies": [{
"href": "http://www.opengis.net/rels/portrayal/{rel}",
"name": "portrayal",
"templated": true
}]
},
"aggregations": [],
"page": {
"size": 20,
"totalElements": 2,
"totalPages": 1,
"number": 0
}
}
======= JSON Response
The result objects in the response of the request conforms to the SymbolSet JSON Schema. The rest of the response return paging information.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 850
{
"results": [{
"id": "4cabf46007df9b652151927033e265c6",
"uri": "http://www.opengis.net/testbed/12/ems/symbols#EMSSymbolSet",
"type": "symbol:SymbolSet",
"description": "Standard Canadian Emergency Mapping Symbology (EMS) SymbolSet version 1.0",
"created": "2016-11-17T23:13:47.142Z",
"modified": "2016-11-17T23:13:48.534Z"
}, {
"id": "bf83c8b6f4033ffd4c93a2be14ebe476",
"uri": "http://www.opengis.net/testbed/12/hswg/symbols#HSWGSymbolSet",
"type": "symbol:SymbolSet",
"description": "Home Security Working Group (HSWG) SymbolSet version 1.0",
"created": "2016-11-17T23:13:50.354Z",
"modified": "2016-11-17T23:13:50.922Z"
}],
"page": {
"size": 20,
"number": 0,
"totalElements": 2
}
}
SymbolSet
The SymbolSet resource is used to retrieve a SymbolSet instance.
Retrieve a SymbolSet
To retrieve a particular instance of SymbolSet, a HTTP GET
request will get the details of a SymbolSet. They are two ways to retrieve an instance of a SymbolSet, using an internal id in the path or by using its Linked Data URL (using uri as query parameter).
Query Parameters
Parameter | Description | Cardinality |
---|---|---|
uri |
URI of the symbol if the instance needs to be retrieved by URI. URI should be encoded to escape special characters. |
0..1 |
Example request
The following HTTP request performs a GET Request to get an instance of a symbol identified by its internal id 4cabf46007df9b652151927033e265c6
GET /symbolsets/4cabf46007df9b652151927033e265c6 HTTP/1.1
Accept: application/hal+json
Host: localhost
The following query get the instance identified by the URI http://www.opengis.net/testbed/12/ems/symbols#EMSSymbolSet
GET /symbolsets/instance?uri=http%3A%2F%2Fwww.opengis.net%2Ftestbed%2F12%2Fems%2Fsymbols%23EMSSymbolSet HTTP/1.1
Accept: application/hal+json
Host: localhost
Response structure
The response of the instance request can be retrieved in HAL+JSON, JSON-LD and Linked Data formats. The JSON Structure of the response conforms to the SymbolSet JSON Schema. The Linked Data formats conforms to the Symbol Ontology.
Links
The following table defines the link relation types accessible from a symbolSet instance that provide transitions to other states related to the symbolSet instance.
Relation | Description |
---|---|
|
Refers to this resource itself |
|
Refers to the root of the portrayal service |
|
Refers to the symbols search endpoint |
|
Refers to the curies defined for the links |
Example response
======= HAL+JSON Format Response (Level 3 REST API)
The HAL+JSON response contains the description of the SymbolSet in JSON-LD (which can be converted to Linked Data by applying the JSON-LD context of the service). In addition, it provides links to other states that can be followed by clients following the semantic of the link relation types described in the SymbolSet Link section.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1895
{
"id": "4cabf46007df9b652151927033e265c6",
"uri": "http://www.opengis.net/testbed/12/ems/symbols#EMSSymbolSet",
"type": "symbol:SymbolSet",
"register": [
"portrayal"
],
"description": "Standard Canadian Emergency Mapping Symbology (EMS) SymbolSet version 1.0",
"created": "2016-11-17T15:38:35.856Z",
"modified": "2016-11-17T15:38:36.457Z",
"specification": "https://cms.masas-x.ca.s3.amazonaws.com/EMS_Symbology_v1.0.pdf",
"symbols": [
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.temperature-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.railway.railwayAccident-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.crime.industrialCrime-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.hazardousMaterial.infectiousDisease-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.wind.hurricaneForceWind-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.missingPerson.silver-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.hazardousMaterial.poisonousGas-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.meteorological.hurricane-symbol",
.... (truncated) ....
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.crime.retailCrime-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.animalHealth.animalDieOff-symbol"
],
"_links": {
"self": {
"href": "http://localhost:8082/symbolsets/4cabf46007df9b652151927033e265c6"
},
"portrayal:symbolSets": {
"href": "http://localhost:8082/symbolsets"
},
"service": {
"href": "http://localhost:8082"
},
"curies": [{
"href": "http://www.opengis.net/rels/portrayal/{rel}",
"name": "portrayal",
"templated": true
}]
}
}
======= JSON(-LD) Format Response (Level 2 REST API)
The following HTTP request performs a GET Request to get an instance of a Symbol in JSON format.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1495
{
"id": "4cabf46007df9b652151927033e265c6",
"uri": "http://www.opengis.net/testbed/12/ems/symbols#EMSSymbolSet",
"type": "symbol:SymbolSet",
"register": [
"portrayal"
],
"description": "Standard Canadian Emergency Mapping Symbology (EMS) SymbolSet version 1.0",
"created": "2016-11-17T15:38:35.856Z",
"modified": "2016-11-17T15:38:36.457Z",
"specification": "https://cms.masas-x.ca.s3.amazonaws.com/EMS_Symbology_v1.0.pdf",
"symbols": [
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.temperature-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.railway.railwayAccident-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.crime.industrialCrime-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.hazardousMaterial.infectiousDisease-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.wind.hurricaneForceWind-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.missingPerson.silver-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.hazardousMaterial.poisonousGas-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.meteorological.hurricane-symbol",
.... (truncated) ....
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.crime.retailCrime-symbol",
"http://www.opengis.net/testbed/12/ems/symbols#ems.incident.animalHealth.animalDieOff-symbol"
]
}
The JSON-(LD) response is identical to the HAL+JSON except it does not have the hyperlinks to other states. The client will need to build the URL to reach other states (by reading documentation of API).
======= Turtle Format Response (Linked Data API)
The following HTTP request performs a GET Request to get an instance of a SymbolSet in Turtle format.
GET /symbolsets/4cabf46007df9b652151927033e265c6 HTTP/1.1
Accept: text/turtle
Host: localhost
The response returns a TTL document that can processed and interpreted by machine using the Portrayal ontology.
HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Length: 1395
<http://www.opengis.net/testbed/12/ems/symbols#EMSSymbolSet>
a <http://www.opengis.net/ont/portrayal/symbol#SymbolSet> ;
<http://purl.org/dc/terms/description>
"Standard Canadian Emergency Mapping Symbology (EMS) SymbolSet version 1.0" ;
<http://www.opengis.net/ont/portrayal/symbol#specification>
"https://cms.masas-x.ca.s3.amazonaws.com/EMS_Symbology_v1.0.pdf" ;
<http://www.opengis.net/ont/portrayal/symbol#symbol>
<http://www.opengis.net/testbed/12/ems/symbols#ems.incident.temperature-symbol> , <http://www.opengis.net/testbed/12/ems/symbols#ems.incident.railway.railwayAccident-symbol> , <http://www.opengis.net/testbed/12/ems/symbols#ems.incident.crime.industrialCrime-symbol>,
.... truncated ...
<http://www.opengis.net/testbed/12/ems/symbols#ems.incident.crime.retailCrime-symbol> , <http://www.opengis.net/testbed/12/ems/symbols#ems.incident.animalHealth.animalDieOff-symbol> .
SPARQL Service
The Semantic Portrayal Service provides a SPARQL service endpoint, which implements the SPARQL Protocol, that can accept a SPARQL query on portrayal managed by the service. Both HTTP GET and HTTP POST are supported.
Query Parameters
HTTP Method | Query String Parameters | Request Content Type | Request Message Body | |
---|---|---|---|---|
query via GET |
GET |
query (exactly 1) |
None |
None |
query via URL-encoded POST |
POST |
None |
application/x-www-form-urlencoded |
|
query via POST directly |
POST |
None |
application/sparql-query |
Unencoded SPARQL query string |
Example Request
The following is an example of a SPARQL query to fetch symbol instances URI and symbol names that belongs to the SymbolSet identified with the URI http://www.opengis.net/testbed/12/ems/symbols#EMSSymbolSet
PREFIX symbol:<http://www.opengis.net/ont/portrayal/symbol#>
SELECT ?symbol ?symbolName WHERE {
?symbol a symbol:Symbol;
symbol:symbolName ?symbolName;
symbol:symbolSet <http://www.opengis.net/testbed/12/ems/symbols#EMSSymbolSet>.
}
LIMIT 10
The request can be done using a HTTP Get request
GET /sparql?query=PREFIX%20symbol%3A%3Chttp%3A%2F%2Fwww.opengis.net%2Font%2Fportrayal%2Fsymbol%23%3E%0ASELECT%20%3Fsymbol%20%20%3FsymbolName%20WHERE%20%7B%0A%20%20%3Fsymbol%20a%20symbol%3ASymbol%3B%0A%20%20%20%20%20%20%20%20%20%20symbol%3AsymbolName%20%3FsymbolName%3B%0A%20%20%20%20%20%20%20%20%20%20symbol%3AsymbolSet%20%3Chttp%3A%2F%2Fwww.opengis.net%2Ftestbed%2F12%2Fems%2Fsymbols%23EMSSymbolSet%3E.%0A%7D%20%0ALIMIT%2010 HTTP/1.1
Accept: application/sparql-results+json
Host: localhost
Response Structure
The SPARQL response conforms to the SPARQL specification. The SPARQL Protocol uses the response status codes defined in HTTP to indicate the success or failure of an operation.
The response body of a successful query operation with a 2XX response is either:
-
A SPARQL Results Document in XML, JSON, or CSV/TSV format (for SPARQL Query forms SELECT and ASK); or,
-
A RDF graph serialized, in the RDF/XML syntax or an equivalent RDF graph serialization (for SPARQL Query forms DESCRIBE and CONSTRUCT). The content type of the response to a successful query operation must be the media type defined for the format of the response body.
Example response
The following example shows a SPARQL query response
HTTP/1.1 200 OK
Content-Type: application/sparql-results+json
Content-Length: 2352
{
"head": {
"vars": [ "symbol" , "symbolName" ]
} ,
"results": {
"bindings": [
{
"symbol": { "type": "uri" , "value": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.airQuality-symbol" } ,
"symbolName": { "type": "literal" , "value": "ems.incident.airQuality" }
} ,
{
"symbol": { "type": "uri" , "value": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.animalHealth-symbol" } ,
"symbolName": { "type": "literal" , "value": "ems.incident.animalHealth" }
} ,
{
"symbol": { "type": "uri" , "value": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.animalHealth.animalDieOff-symbol" } ,
"symbolName": { "type": "literal" , "value": "ems.incident.animalHealth.animalDieOff" }
} ,
{
"symbol": { "type": "uri" , "value": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.animalHealth.animalFeed-symbol" } ,
"symbolName": { "type": "literal" , "value": "ems.incident.animalHealth.animalFeed" }
} ,
{
"symbol": { "type": "uri" , "value": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.aviation-symbol" } ,
"symbolName": { "type": "literal" , "value": "ems.incident.aviation" }
} ,
{
"symbol": { "type": "uri" , "value": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.aviation.aircraftCrash-symbol" } ,
"symbolName": { "type": "literal" , "value": "ems.incident.aviation.aircraftCrash" }
} ,
{
"symbol": { "type": "uri" , "value": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.aviation.aircraftHijacking-symbol" } ,
"symbolName": { "type": "literal" , "value": "ems.incident.aviation.aircraftHijacking" }
} ,
{
"symbol": { "type": "uri" , "value": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.aviation.airportClosure-symbol" } ,
"symbolName": { "type": "literal" , "value": "ems.incident.aviation.airportClosure" }
} ,
{
"symbol": { "type": "uri" , "value": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.aviation.airspaceClosure-symbol" } ,
"symbolName": { "type": "literal" , "value": "ems.incident.aviation.airspaceClosure" }
} ,
{
"symbol": { "type": "uri" , "value": "http://www.opengis.net/testbed/12/ems/symbols#ems.incident.aviation.noticeToAirmen-symbol" } ,
"symbolName": { "type": "literal" , "value": "ems.incident.aviation.noticeToAirmen" }
}
]
}
}
Appendix G: Revision History
Date | Editor | Release | Primary clauses modified | Descriptions |
---|---|---|---|---|
March 10, 2016 |
S. Fellah |
0.1 |
abstract |
initial version |
April 10, 2016 |
S. Fellah |
0.2 |
all |
initial version |
April 14, 2016 |
S. Fellah |
0.3 |
Registry Model |
Registry Model |
May 31, 2016 |
S. Fellah |
0.4 |
Future work section |
|
June 27, 2016 |
S. Fellah |
0.4 |
All sections |
|
June 27, 2016 |
S. Fellah |
0.5 |
All sections |
|
June 27, 2016 |
S. Fellah |
0.56 |
All sections |
|
October 4, 2016 |
S. Fellah |
0.7 |
Registry REST API |
|
October 10, 2016 |
S. Fellah |
0.8 |
All Sections |
|
October 25, 2016 |
S. Fellah |
0.9 |
All Sections |
|
October 30, 2016 |
S. Fellah |
0.10 |
All Sections |
|
November 3, 2016 |
S. Fellah |
0.11 |
Appendix C |
|
November 7, 2016 |
S. Fellah |
0.12 |
Mediation REST API |
|
November 14, 2016 |
S. Fellah |
0.13 |
Portrayal REST API |
|
November 20, 2016 |
S. Fellah |
0.14 |
Registry REST API |
|
November 20, 2016 |
S. Fellah |
0.15 |
All Sections (formatting) |
|
March 14, 2017 |
L. Bermudez |
0.16 |
Preface, Future Work and intro |
Appendix H: Bibliography
[1] OGC,: OGC Testbed 11 Demonstration. (2015).
[2] Testbed-11 Symbology Mediation Engineering Report, OGC document 15-058
[3] Implementing Linked Data and Semantically Enabling OGC Services Engineering Report, OGC document 15-054
[4] CCI Ontology Engineering Report,OGC document 14-049
[5] Guidelines for Successful OGC Interface Standards, OGC document 00-014r1
[6] SKOS Reference, W3C Recommendation, 18 August 2009. Latest version available at http://www.w3.org/TR/skos-reference .
[7] RDF 1.1 Turtle: Terse RDF Triple Language. W3C Recommendation, 25 February 2014. The latest edition is available at http://www.w3.org/TR/turtle/
[8] Gruber, Thomas R. "Toward principles for the design of ontologies used for knowledge sharing?" International journal of human-computer studies 43, no. 5 (1995): 907-928.
[9] Stuckenschmidt, Heiner, and Michel Klein. "Structure-based partitioning of large concept hierarchies." In The Semantic Web–ISWC 2004, pp. 289-303. Springer Berlin Heidelberg, 2004.
[10] Stuckenschmidt, Heiner, Christine Parent, and Stefano Spaccapietra, eds.Modular ontologies: concepts, theories and techniques for knowledge modularization. Vol. 5445. Springer, 2009.