more media type polish

core/README.md

@@ -1,12 +1,16 @@
 # STAC API - Core Specification
 
 - [STAC API - Core Specification](#stac-api---core-specification)
+  - [Summary](#summary)
+  - [Overview](#overview)
   - [Link Relations](#link-relations)
   - [Endpoints](#endpoints)
   - [Example Landing Page for STAC API - Core](#example-landing-page-for-stac-api---core)
   - [Extensions](#extensions)
   - [Structuring Catalog Hierarchies](#structuring-catalog-hierarchies)
 
+## Summary
+
 - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.2/core)),
 - **Conformance URIs:**
   - <https://api.stacspec.org/v1.0.0-rc.2/core>
@@ -15,6 +19,8 @@
 - **Dependencies**: None
   and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas.
 
+## Overview
+
 All STAC API implementations must implement the *STAC API - Core* specification. The conformance class
 <https://api.stacspec.org/v1.0.0-rc.2/core> requires a server to provide a valid
 [STAC Catalog](../stac-spec/catalog-spec/catalog-spec.md) that also includes a `conformsTo`
@@ -143,10 +149,10 @@ This conformance class also requires for the endpoints in the [STAC API - Core](
 
 These endpoints are required, with details provided in this [OpenAPI specification document](openapi.yaml).
 
-| Endpoint | Returns                                        | Description                                                                                                                                                        |
-| -------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `/`      | [Catalog](../stac-spec/catalog-spec/README.md) | Landing page, links to API capabilities                                                                                                                            |
-| `/api`   | any                                            | The service description of the service from the `service-desc` link `rel`. The path is only recommended to be `/api`, and is at the discretion of the implementer. |
+| **Endpoint** | **Media Type** | **Returns**                                        | **Description**                                                                                                                                                        |
+| -------- | ----- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/`      | application/json | [Catalog](../stac-spec/catalog-spec/README.md) | Landing page, links to API capabilities                                                                                                                            |
+| `/api`   | various | any                                            | The service description of the service from the `service-desc` link `rel`. The path is only recommended to be `/api`, and is at the discretion of the implementer. |
 
 The service description endpoint may return any specification format. It is recommended to use OpenAPI 3.0 or 3.1
 with media types `application/vnd.oai.openapi` (YAML), `application/vnd.oai.openapi+json;version=3.0` (3.0 JSON),
@@ -161,22 +167,22 @@ class for OpenAPI 3.1, but may in the future.
 If sub-catalogs are used, it is **recommended** that these use the endpoint `/catalogs/{catalogId}` to avoid conflicting
 with other endpoints from the root.
 
-| Endpoint                | Returns                                        | Description          |
-| ----------------------- | ---------------------------------------------- | -------------------- |
-| `/catalogs/{catalogId}` | [Catalog](../stac-spec/catalog-spec/README.md) | child Catalog object |
+| **Endpoint**                | **Media Type** | **Returns**                                        | **Description**          |
+| ----------------------- | -- | -------------------------------------------- | -------------------- |
+| `/catalogs/{catalogId}` | application/json | [Catalog](../stac-spec/catalog-spec/README.md) | child Catalog object |
 
 ## Example Landing Page for STAC API - Core
 
 This JSON is what would be expected from an API that only implements *STAC API - Core*. It is a valid STAC Catalog
-with additional Links and a `conformsTo` attribute. In practice, 
-most APIs will also implement other conformance classes, and those will be reflected in the `links` and 
-`conformsTo` attribute.  A more typical Landing Page example is in 
+with additional Links and a `conformsTo` attribute. In practice,
+most APIs will also implement other conformance classes, and those will be reflected in the `links` and
+`conformsTo` attribute.  A more typical Landing Page example is in
 the [overview](../overview.md#example-landing-page) document.
 
 This particular catalog provides both the ability to browse down to child Catalog objects through its
 `child` links, and also provides the search endpoint to be able to search across items in its collections. Note
 that some of those links are not required and other servers may provide
-different conformance classes and a different set of links. 
+different conformance classes and a different set of links.
 
 ```json
 {
@@ -282,7 +288,7 @@ per provider (e.g., Sentinel-2), per domain (e.g., cloud data), or per form of d
 
 Going the other direction, collections can be sub-grouped into smaller catalogs. For example, this example
 groups a catalog of Landsat 8 Collection 1 items by path, row, and date (the path/row system is used by this
-product for gridding). 
+product for gridding).
 
 - / (root)
   - /catalogs/landsat_8_c1

item-search/README.md

@@ -15,13 +15,17 @@
   - [Example Landing Page for STAC API - Item Search](#example-landing-page-for-stac-api---item-search)
   - [Extensions](#extensions)
 
+## Summary
+
 - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.2/item-search))
 - **Conformance URIs:**
   - <https://api.stacspec.org/v1.0.0-rc.2/item-search>
 - **[Maturity Classification](../README.md#maturity-classification):** Candidate
 - **Dependencies**: [STAC API - Core](../core)
 - **Examples**: [examples.md](examples.md)
 
+## Overview
+
 The *STAC API - Item Search* specification defines the *STAC API - Item Search*
 conformance class (<https://api.stacspec.org/v1.0.0-rc.2/item-search>), which
 provides the ability to search for STAC [Item](../stac-spec/item-spec/README.md)

item-search/examples.md

@@ -93,6 +93,7 @@ This can be even more effective when using continuation tokens on the server, as
 repeated in the subsequent request:
 
 Response with `200 OK`:
+
 ```json
 {
     "rel": "next",
@@ -104,17 +105,21 @@ Response with `200 OK`:
     }
 }
 ```
+
 The above link tells the client not to merge (default of false) so it is only required to pass the next token in the body.
 
 Request to `POST /search`:
+
 ```json
 {
     "next": "a9f3kfbc98e29a0da23"
 }
 ```
 
 #### POST search using headers
+
 Request to `HTTP POST /search`:
+
 ```json
 {
     "bbox": [-110, 39.5, -105, 40.5],
@@ -124,6 +129,7 @@ Request to `HTTP POST /search`:
 ```
 
 Response with `200 OK`:
+
 ```json
 {
     "type": "FeatureCollection",
@@ -145,6 +151,7 @@ Response with `200 OK`:
 This tells the client to POST to the search endpoint with the header `Search-After` to obtain the next set of results:
 
 Request:
+
 ```
 POST /search
 Search-After: LC81530752019135LGN00

ogcapi-features/README.md

@@ -1,6 +1,8 @@
 # STAC API - Collections and Features Specification
 
 - [STAC API - Collections and Features Specification](#stac-api---collections-and-features-specification)
+  - [Summary](#summary)
+  - [Overview](#overview)
   - [Conformance Classes](#conformance-classes)
     - [STAC API - Features](#stac-api---features)
     - [STAC API - Collections](#stac-api---collections)
@@ -16,6 +18,8 @@
   - [Example Collection Endpoint](#example-collection-endpoint)
   - [Extensions](#extensions)
 
+## Summary
+
 *based on [**OGC API - Features - Part 1: Core**](https://www.ogc.org/standards/ogcapi-features)*
 
 - **OpenAPI specifications:**
@@ -30,6 +34,8 @@
   - [OGC API - Features](https://www.ogc.org/standards/ogcapi-features)
   uses all the OGC API - Features openapi fragments to describe returning STAC Item objects.
 
+## Overview
+
 The *STAC API - Collections and Features* specification extends the
 [OGC API - Features - Part 1: Core](https://docs.opengeospatial.org/is/17-069r3/17-069r3.html)
 (OAFeat) specification. OAFeat
@@ -190,8 +196,8 @@ or `token` and any additional filter parameters if given and required. For examp
     "links": [
         {
             "rel": "next",
+            "type": "application/geo+json",
             "href": "https://stac-api.example.com/collections/my_collection/items?page=2"
-            "type": "application/geo+json"
         }
     ]
 ```
@@ -236,20 +242,21 @@ In our simple example of numerical pages, the response for `page=3` would have a
 `links` array containing these two Links indicating the URLs for the next (page=4) and
 previous (page=2) pages:
 
-```none
-"links": [
-  ...
-  {
-    "rel": "prev",
-    "href": "https://stac-api.example.com/collections?page=2"
-    "type": "application/json"
-  },
-  {
-    "rel": "next",
-    "href": "https://stac-api.example.com/collections?page=4"
-    "type": "application/json"
-  }
-]
+```json
+{
+    "links": [
+    {
+        "rel": "prev",
+        "type": "application/json",
+        "href": "https://stac-api.example.com/collections?page=2"
+    },
+    {
+        "rel": "next",
+        "type": "application/json",
+        "href": "https://stac-api.example.com/collections?page=4"
+    }
+    ]
+}
 ```
 
 In addition to supporting query parameters in the URL value of the `href` field,