Skip to content

Commit 3730d5e

Browse files
philvarnerphilvarner
authored
clarify features links wrt to parent link (#371)
1 parent c598e13 commit 3730d5e

File tree

2 files changed

+60
-22
lines changed

2 files changed

+60
-22
lines changed

‎core/README.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -96,11 +96,11 @@ Recommendations for structuring Catalogs hierarchically can be found in
9696

9797
The following Link relations must exist in the Landing Page (root).
9898

99-
| **rel** | **href** | **From** | **Description** |
100-
| -------------- | -------- | --------- | ---------------------------------------------------- |
101-
| `root` | `/` | STAC Core | The root URI |
102-
| `self` | `/` | OAFeat | Self reference, same as root URI |
103-
| `service-desc` | `/api` | OAFeat | The service description in a machine-readable format |
99+
| **rel** | **href** | **From** | **Description** |
100+
| -------------- | -------- | --------------- | ---------------------------------------------------- |
101+
| `root` | `/` | STAC API - Core | The root URI |
102+
| `self` | `/` | OAFeat | Self reference, same as root URI |
103+
| `service-desc` | `/api` | OAFeat | The service description in a machine-readable format |
104104

105105
The path for the `service-desc` endpoint is recommended to be `/api`, but may be another path. Recommended to be
106106
OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML),
@@ -122,10 +122,10 @@ relations form a directed graph that enables traversal from a root catalog or co
122122
If all Items in a Catalog can be accessed by traversing these links, the browseable conformance class
123123
<https://api.stacspec.org/v1.0.0-rc.2/browseable> should be advertised also.
124124

125-
| **rel** | **href** | **From** | **Description** |
126-
| ------- | -------- | --------- | -------------------------------------- |
127-
| `child` | various | STAC Core | The child STAC Catalogs & Collections. |
128-
| `item` | various | STAC Core | The child STAC Items. |
125+
| **rel** | **href** | **From** | **Description** |
126+
| ------- | -------- | --------------- | -------------------------------------- |
127+
| `child` | various | STAC API - Core | The child STAC Catalogs & Collections. |
128+
| `item` | various | STAC API - Core | The child STAC Items. |
129129

130130
While it is valid to have `item` links from the landing page, most STAC API implementations
131131
serve large numbers of features, so they will typically use several layers of intermediate `child` links before

‎ogcapi-features/README.md‎

Lines changed: 51 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@
1010
- [OGC API - Features - Part 1: GeoJSON](#ogc-api---features---part-1-geojson)
1111
- [OGC API - Features - Part 1: OpenAPI 3.0](#ogc-api---features---part-1-openapi-30)
1212
- [Link Relations](#link-relations)
13+
- [Landing Page (/)](#landing-page-)
14+
- [Collections (/collections)](#collections-collections)
15+
- [Collection (/collections/{collectionId})](#collection-collectionscollectionid)
16+
- [Collection Items (/collections/{collectionId}/items)](#collection-items-collectionscollectioniditems)
17+
- [Items (/collections/{collectionId}/items/{itemId})](#items-collectionscollectioniditemsitemid)
1318
- [Endpoints](#endpoints)
1419
- [Item Pagination](#item-pagination)
1520
- [Collection Pagination](#collection-pagination)
@@ -92,7 +97,9 @@ by *STAC API - Core*, the
9297

9398
## Link Relations
9499

95-
This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class.
100+
These conformance classes also requires implementation of the link relations in the [STAC API - Core](../core) conformance class.
101+
102+
### Landing Page (/)
96103

97104
The following Link relations must exist in the Landing Page (root).
98105

@@ -101,31 +108,62 @@ The following Link relations must exist in the Landing Page (root).
101108
| `conformance` | `/conformance` | OAFeat | Conformance URI |
102109
| `data` | `/collections` | OAFeat | List of Collections |
103110

111+
### Collections (/collections)
112+
104113
The following Link relations must exist in the `/collections` endpoint response.
105114

106-
| **rel** | **href** | **From** | **Description** |
107-
| ------- | -------------- | --------- | --------------- |
108-
| `root` | `/` | STAC Core | The root URI |
109-
| `self` | `/collections` | OAFeat | Self reference |
115+
| **rel** | **href** | **From** | **Description** |
116+
| ------- | -------------- | ------------------------------------------- | --------------- |
117+
| `root` | `/` | STAC API - Features, STAC API - Collections | The root URI |
118+
| `self` | `/collections` | OAFeat | Self reference |
119+
120+
### Collection (/collections/{collectionId})
110121

111122
The following Link relations must exist in the Collection object returned from the `/collections/{collectionId}` endpoint.
112123

113-
| **rel** | **href** | **From** | **Description** |
114-
| -------- | ----------------------------- | --------- | ------------------------------------------ |
115-
| `root` | `/` | STAC Core | The root URI |
116-
| `parent` | `/` | OAFeat | Parent reference, usually the root Catalog |
117-
| `self` | `/collections/{collectionId}` | OAFeat | Self reference |
124+
| **rel** | **href** | **From** | **Description** |
125+
| -------- | ----------------------------- | ------------------------------------------- | ------------------------------------------ |
126+
| `root` | `/` | STAC API - Features, STAC API - Collections | The root URI |
127+
| `parent` | `/` | OAFeat | Parent reference, usually the root Catalog |
128+
| `self` | `/collections/{collectionId}` | OAFeat | Self reference |
118129

119130
Additionally, these relations may exist for the `/collections/{collectionId}` endpoint:
120131

121-
| **rel** | **href** | **From** | **Description** |
122-
| ----------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
123-
| `canonical` | various | STAC Core | Provides the preferred paths to get to STAC Collection and Item objects, if they differ from the URL that was used to retrieve the STAC object and thus duplicate other content. This can be useful in federated catalogs that present metadata that has a different location than the source metadata. |
132+
| **rel** | **href** | **From** | **Description** |
133+
| ----------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
134+
| `canonical` | various | STAC API - Core | Provides the preferred paths to get to STAC Collection and Item objects, if they differ from the URL that was used to retrieve the STAC object and thus duplicate other content. This can be useful in federated catalogs that present metadata that has a different location than the source metadata. |
124135

125136
Usually, the `self` link in a Collection must link to the same URL that was used to request
126137
it. However, implementations may choose to have the canonical location of the Collection be
127138
elsewhere. If this is done, it is recommended to include a `rel` of `canonical` to that location.
128139

140+
Note that the `parent` link for a Collection should be point to the parent Catalog (such as the root Catalog, `/`) or Collection
141+
of that Collection, rather than the API sub-path of `/collections`.
142+
143+
### Collection Items (/collections/{collectionId}/items)
144+
145+
The following Link relations must exist in the ItemCollection object returned from the `/collections/{collectionId}/items` endpoint.
146+
147+
| **rel** | **href** | **Media Type** | **From** | **Description** |
148+
| ------------ | ----------------------------------- | -------------------- | ------------------- | -------------------- |
149+
| `root` | `/` | application/json | STAC API - Features | The root URI |
150+
| `self` | `/collections/{collectionId}/items` | application/geo+json | OAFeat | Self reference |
151+
| `collection` | `/collections/{collectionId}` | application/json | OAFeat | Collection reference |
152+
153+
### Items (/collections/{collectionId}/items/{itemId})
154+
155+
The following Link relations must exist in the Item object returned from the `/collections/{collectionId}/items/{itemId}` endpoint.
156+
157+
| **rel** | **href** | **Media Type** | **From** | **Description** |
158+
| -------- | -------------------------------------------- | -------------------- | ------------------- | --------------------------------------------------- |
159+
| `root` | `/` | application/json | STAC API - Features | The root URI |
160+
| `parent` | `/collections/{collectionId}` | application/json | OAFeat | Parent reference, usually the containing Collection |
161+
| `self` | `/collections/{collectionId}/items/{itemId}` | application/geo+json | OAFeat | Self reference |
162+
163+
Note that the `parent` link for an Item should point to the containing Collection
164+
(e.g., `/collections/{collectionId}`), rather than the API sub-path
165+
of `/collections/{collectionId}/items/`.
166+
129167
## Endpoints
130168

131169
This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.

0 commit comments

Comments
 (0)