Skip to content

Commit

Permalink
Implement new resource structure
Browse files Browse the repository at this point in the history 
* change path structure, resolves #64
* change remaining uses of "collectionId" to "name"
  • Loading branch information
@cportele
cportele committed Mar 7, 2018
1 parent a87d485 commit af8ffd5
Show file tree
Hide file tree
Showing 5 changed files with 455 additions and 258 deletions.
4 changes: 2 additions & 2 deletions core/UML/ISO 191xx-1 Edition 1.xmi
View file
Original file line number Diff line number Diff line change
Expand Up @@ -776,7 +776,7 @@
<UML:TaggedValue tag="style" value="BackColor=-1;BorderColor=-1;BorderWidth=-1;FontColor=-1;VSwimLanes=1;HSwimLanes=1;BorderStyle=0;"/>
</UML:ModelElement.taggedValue>
<UML:Classifier.feature>
<UML:Attribute name="collectionId" changeable="none" visibility="public" ownerScope="instance" targetScope="instance">
<UML:Attribute name="name" changeable="none" visibility="public" ownerScope="instance" targetScope="instance">
<UML:Attribute.initialValue>
<UML:Expression/>
</UML:Attribute.initialValue>
Expand Down Expand Up @@ -973,7 +973,7 @@
<UML:TaggedValue tag="style" value="BackColor=-1;BorderColor=-1;BorderWidth=-1;FontColor=-1;VSwimLanes=1;HSwimLanes=1;BorderStyle=0;"/>
</UML:ModelElement.taggedValue>
<UML:Classifier.feature>
<UML:Attribute name="collectionId" changeable="none" visibility="public" ownerScope="instance" targetScope="instance">
<UML:Attribute name="name" changeable="none" visibility="public" ownerScope="instance" targetScope="instance">
<UML:Attribute.initialValue>
<UML:Expression/>
</UML:Attribute.initialValue>
Expand Down
3 changes: 3 additions & 0 deletions core/standard/clause_0_front_material.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,11 @@ Query operations allow features or values of feature properties to be retrieved

This part of this International Standard defines the following resources:

* Landing page [1]
* Service definition [1]
* Conformance classes [1]
* Feature collections metadata [1]
* Feature collection metadata [0..n]
* Feature collection [0..n]
* Feature [0..n]
Expand Down
217 changes: 136 additions & 81 deletions core/standard/clause_7_core.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,24 +60,87 @@ which describes the capabilities of the server and which can be used by
clients to connect to the server or
by development tools to support the implementation of servers and clients.

!!! Update diagram and description

[#img_core,reftext='{figure-caption} {counter:figure-num}']
.Resources in the Core requirements class
image::figures/PT1_FIG01.png[align="center"]

CAUTION: link:https://github.com/opengeospatial/WFS_FES/issues/30[ISSUE 30] +
Allow also features that do not belong to any collection?

=== API definition
=== API landing page

==== Operation

[width="90%",cols="2,6a"]
|===
|*Requirement {counter:req-id}* |/req/core/root-op +

The server SHALL support the HTTP GET operation at the path `/`.
|===

==== Response

[width="90%",cols="2,6a"]
|===
|*Requirement {counter:req-id}* |/req/core/root-success +

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

The content of that response SHALL be based upon the OpenAPI 3.0 schema link:https://raw.githubusercontent.com/opengeospatial/WFS_FES/master/core/openapi/schemas/root.yaml[root.yaml]
and include at least links to the following resources:

* `/api` (relation type 'service')
* `/conformance` (relation type 'conformance')
* `/collections` (relation type 'data')
|===

NOTE: TODO +
Check, if we can reuse existing relation types instead of 'conformance' and 'data'?

.link:https://raw.githubusercontent.com/opengeospatial/WFS_FES/master/core/openapi/schemas/root.yaml[Schema for the landing page]
[source,JSON]
----
type: object
required:
- links
properties:
links:
type: array
items:
$ref: https://raw.githubusercontent.com/opengeospatial/WFS_FES/master/core/openapi/schemas/link.yaml
----

.Landing page response document
=================
[source,JSON]
----
{
"links": [
{ "href": "http://data.example.org/",
"rel": "self", "type": "application/json", "title": "this document" },
{ "href": "http://data.example.org/api",
"rel": "service", "type": "application/openapi+json;version=3.0", "title": "the API definition" },
{ "href": "http://data.example.org/conformance",
"rel": "conformance", "type": "application/json", "title": "WFS 3.0 conformance classes implemented by this server" },
{ "href": "http://data.example.org/collections",
"rel": "data", "type": "application/json", "title": "Metadata about the feature collections" }
]
}
----
=================

==== General requirements
=== API definition

Every WFS is defined by an API definition that describes the capabilities
of the server and which can be used by clients to connect to the server or
by development tools to support the implementation of servers and clients.

include::requirements/requirement_api-definition.adoc[]

The API definition document is the "landing page" for the API. I.e.,
The API definition document describes the API. I.e.,
there is no need to include the `/api` operation in the API definition itself.

The idea is that any WFS can be used by developers that are familiar with
Expand All @@ -87,20 +150,17 @@ client using the OpenAPI definition. The developer may need to learn a little
bit about geometry, etc., but it should not be required to read this standard
to access the data via the API.

==== Requirements specific to Web Feature Services

===== Support for generic clients
=== Declaration of conformance classes

In addition, it should be possible to write a "generic" client that can
access Web Feature Services in general, i.e. that are not written for a
specific server or API. To support such clients, the server has to declare the
requirements classes it implements and conforms to.
To support "generic" clients for accessing Web Feature Services in general - and
not "just" a specific API / server, the server has to declare the
requirements classes it implements and conforms to, too.

[width="90%",cols="2,6a"]
|===
|*Requirement {counter:req-id}* |/req/core/conformance-op +

The server SHALL support the HTTP GET operation at the path `/api/conformance`.
The server SHALL support the HTTP GET operation at the path `/conformance`.
|===

[width="90%",cols="2,6a"]
Expand Down Expand Up @@ -319,7 +379,7 @@ included in a response or a link is not known when the HTTP headers of the
response are created.
|===

=== Feature collection metadata
=== Feature collections metadata

==== Operation

Expand All @@ -338,43 +398,20 @@ The content of that response SHALL be based upon the OpenAPI 3.0 schema link:htt
|===

.link:https://raw.githubusercontent.com/opengeospatial/WFS_FES/master/core/openapi/schemas/content.yaml[Schema for the metadata about feature collections]
[source,JSON]
[source,YAML]
----
type: object
required:
- links
- collections
properties:
links:
type: array
items:
$ref: link.yaml
$ref: https://raw.githubusercontent.com/opengeospatial/WFS_FES/master/core/openapi/schemas/link.yaml
collections:
type: array
items:
type: object
required:
- name
- links
properties:
name:
type: string
title:
type: string
description:
type: string
links:
type: array
items:
$ref: link.yaml
extent:
$ref: bbox.yaml
crs:
description: the list of coordinate reference systems supported by the service; the first item is the default coordinate reference system
type: array
items:
type: string
default:
- http://www.opengis.net/def/crs/OGC/1.3/CRS84
$ref: https://raw.githubusercontent.com/opengeospatial/WFS_FES/master/core/openapi/schemas/collectionInfo.yaml
----

Expand All @@ -389,9 +426,7 @@ of the response:
* a link to the response document in every other media type supported by
the server (relation: `alternate`),
* links to each feature collection resource in this distribution of the
dataset for each supported encoding (relation: `item`), and
* links to the API definition document in each supported encoding
(relation: `service`).
dataset for each supported encoding (relation: `item`).

All links SHALL include the `rel` and `type` link parameters.
|===
Expand Down Expand Up @@ -467,10 +502,10 @@ For each feature collection, the `extent` property, if provided, SHALL be a boun
----
type: object
required:
- collectionId
- name
- links
properties:
collectionId:
name:
description: identifier of the collection used, for example, in URIs
type: string
title:
Expand Down Expand Up @@ -514,42 +549,61 @@ geometries only in the default system (WGS84 longitude/latitude).
----
{
"links": [
{ "href": "http://data.example.org/index.json",
{ "href": "http://data.example.org/collections.json",
"rel": "self", "type": "application/json", "title": "this document" },
{ "href": "http://data.example.org/index.html",
{ "href": "http://data.example.org/collections.html",
"rel": "alternate", "type": "text/html", "title": "this document as HTML" },
{ "href": "http://data.example.org/api.json",
"rel": "service", "type": "application/openapi+json;version=3.0", "title": "the OpenAPI definition as JSON" },
{ "href": "http://data.example.org/api.html",
"rel": "service", "type": "text/html", "title": "the OpenAPI definition as HTML" },
{ "href": "http://catalog.example.org/datasets/buildings#wfs",
"rel": "???", "type": "application/json+ld" }
{ "href": "http://schemas.example.org/1.0/foobar.xsd",
"rel": "describedBy", "type": "application/xml", "title": "XML schema for ACME Inc. data" }
],
"collections": [
{
"collectionId": "buildings",
"name": "buildings",
"title": "Buildings",
"description": "Buildings in the city of Bonn.",
"extent": {
"bbox": [ 7.01, 50.63, 7.22, 50.78 ]
},
"links": [
{ "href": "http://data.example.org/buildings.json",
"rel": "about", "type": "application/geo+json",
"title": "Buildings as GeoJSON" },
{ "href": "http://data.example.org/buildings.html",
"rel": "about", "type": "text/html",
"title": "Buildings as HTML" },
{ "href": "http://data.example.org/collections/buildings/items",
"rel": "item", "type": "application/geo+json",
"title": "Buildings" }
{ "href": "http://example.org/concepts/building.html",
"rel": "describedBy", "type": "text/html",
"title": "Feature catalogue for the buildings" }
"title": "Feature catalogue for buildings" }
]
}
]
}
----
=================

=== Feature collection metadata

==== Operation

[width="90%",cols="2,6a"]
|===
|*Requirement {counter:req-id}* |/req/core/sfc-md-op +

The server SHALL support the HTTP GET operation at the path `/collections/{name}`.

`name` is the property of the same name in the feature collections metadata.
|===

==== Response

[width="90%",cols="2,6a"]
|===
|*Requirement {counter:req-id}* |/req/core/sfc-md-success +

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

The content of that response SHALL be the same to the content for this feature
collection in the `/collections` response.
|===

=== Feature collections

==== Operation
Expand All @@ -560,9 +614,9 @@ geometries only in the default system (WGS84 longitude/latitude).
+

For every feature collection identified in the metadata about the feature collection (path "/"),
the server SHALL support the HTTP GET operation at the path `/{collectionId}`.
the server SHALL support the HTTP GET operation at the path `/collections/{name}/items`.

`collectionId` is the property of the same name in the feature collection metadata.
`name` is the property of the same name in the feature collections metadata.
|===

CAUTION: link:https://github.com/opengeospatial/WFS_FES/issues/17[ISSUE 17] +
Expand Down Expand Up @@ -842,38 +896,38 @@ the optional `prev` links):
[source]
----
Link: <http://data.example.org/buildings.json>; rel="self"; type="application/geo+json"
Link: <http://data.example.org/buildings.html>; rel="alternate"; type="text/html"
Link: <http://data.example.org/buildings.json?startIndex=10>; rel="next"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items.json>; rel="self"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items.html>; rel="alternate"; type="text/html"
Link: <http://data.example.org/collections/buildings/items.json?startIndex=10>; rel="next"; type="application/geo+json"
----
Following the `next` link could return:
[source]
----
Link: <http://data.example.org/buildings.json?startIndex=10>; rel="self"; type="application/geo+json"
Link: <http://data.example.org/buildings.html?startIndex=10>; rel="alternate"; type="text/html"
Link: <http://data.example.org/buildings.json?startIndex=0>; rel="prev"; type="application/geo+json"
Link: <http://data.example.org/buildings.json?startIndex=20>; rel="next"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items.json?startIndex=10>; rel="self"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items.html?startIndex=10>; rel="alternate"; type="text/html"
Link: <http://data.example.org/collections/buildings/items.json?startIndex=0>; rel="prev"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items.json?startIndex=20>; rel="next"; type="application/geo+json"
----
If an explicit `count` of "50" is used, the links in the response could be:
[source]
----
Link: <http://data.example.org/buildings.json?count=50>; rel="self"; type="application/geo+json"
Link: <http://data.example.org/buildings.html?count=50>; rel="alternate"; type="text/html"
Link: <http://data.example.org/buildings.json?count=50&startIndex=50>; rel="next"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items.json?count=50>; rel="self"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items.html?count=50>; rel="alternate"; type="text/html"
Link: <http://data.example.org/collections/buildings/items.json?count=50&startIndex=50>; rel="next"; type="application/geo+json"
----
Following the `next` link could return:
[source]
----
Link: <http://data.example.org/buildings.json?count=50&startIndex=50>; rel="self"; type="application/geo+json"
Link: <http://data.example.org/buildings.html?count=50&startIndex=50>; rel="alternate"; type="text/html"
Link: <http://data.example.org/buildings.json?count=50&startIndex=0>; rel="prev"; type="application/geo+json"
Link: <http://data.example.org/buildings.json?count=50&startIndex=100>; rel="next"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items.json?count=50&startIndex=50>; rel="self"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items.html?count=50&startIndex=50>; rel="alternate"; type="text/html"
Link: <http://data.example.org/collections/buildings/items.json?count=50&startIndex=0>; rel="prev"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items.json?count=50&startIndex=100>; rel="next"; type="application/geo+json"
----
=================

Expand Down Expand Up @@ -926,10 +980,11 @@ not seem to be needed given the 'Date' HTTP header. For `numberMatched` and
|===
|*Requirement {counter:req-id}* |/req/core/f-op +

For every feature in a feature collection (path "/{collectionId}"),
the service SHALL support the HTTP GET operation at the path `/{collectionId}/{id}`.
For every feature in a feature collection (path `/collections/{name}/items`),
the service SHALL support the HTTP GET operation at the path
`/collections/{name}/items/{id}`.

`collectionId` is the property of the same name in the feature collection metadata.
`name` is the property of the same name in the feature collection metadata.

`id` is the unique identifier of the feature within the dataset.
|===
Expand Down Expand Up @@ -973,9 +1028,9 @@ The links in a feature could be (in this example represented as link headers):
[source]
----
Link: <http://data.example.org/buildings/123.json>; rel="self"; type="application/geo+json"
Link: <http://data.example.org/buildings/123.html>; rel="alternate"; type="text/html"
Link: <http://data.example.org/buildings.json>; rel="collection"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items/123.json>; rel="self"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items/123.html>; rel="alternate"; type="text/html"
Link: <http://data.example.org/collections/buildings/items.json>; rel="collection"; type="application/geo+json"
----
=================

Expand Down
Loading

0 comments on commit af8ffd5

Please sign in to comment.