fix: update readme and fix duplicate type fields on serialization (#608)

Author: gadomski

README.md

@@ -8,13 +8,15 @@
 
 Command Line Interface (CLI) and Rust libraries for the [SpatioTemporal Asset Catalog (STAC)](https://stacspec.org/) specification.
 
-There's a couple Python projects based on **stac-rs** that might be of interest to you, as well:
+## Formats
 
-- [stacrs](https://github.com/gadomski/stacrs) provides a Python API to **stac-rs**, including
-  - Reading and writing [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet)
-  - Migrating to [STAC v1.1](https://github.com/radiantearth/stac-spec/releases/tag/v1.1.0)
-  - [More...](https://www.gadom.ski/posts/stacrs-python-v0-1/)
-- [pgstacrs](https://github.com/stac-utils/pgstacrs) is a Python library for working with [pgstac](https://github.com/stac-utils/pgstac)
+**stac-rs** "speaks" three forms of STAC:
+
+- **JSON**: STAC is derived from [GeoJSON](https://geojson.org/)
+- **Newline-delimited JSON (ndjson)**: One JSON [item](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md) per line, often used for bulk item loading and storage
+- **stac-geoparquet**: A newer [specification](https://github.com/stac-utils/stac-geoparquet) for storing STAC items, and optionally collections
+
+We also have interfaces to other storage backends, e.g. Postgres via [pgstac](https://github.com/stac-utils/pgstac).
 
 ## Command line interface
 
@@ -30,15 +32,38 @@ cargo install stac-cli
 Then:
 
 ```shell
+# Search
 $ stacrs search https://landsatlook.usgs.gov/stac-server \
-    -c landsat-c2l2-sr --intersects \
-    '{"type": "Point", "coordinates": [-105.119, 40.173]}' \
+    --collections landsat-c2l2-sr \
+    --intersects '{"type": "Point", "coordinates": [-105.119, 40.173]}' \
     --sortby='-properties.datetime' \
     --max-items 1000 \
-    -f 'parquet[snappy]' \
     items.parquet
+
+# Translate formats
+$ stacrs translate items.parquet items.ndjson
+$ stacrs translate items.ndjson items.json
+
+# Migrate STAC versions
+$ stacrs translate item-v1.0.json item-v1.1.json --migrate
+
+# Search stac-geoparquet (no API server required)
+$ stac search items.parquet
+
+# Server
+$ stacrs serve items.parquet  # Opens a STAC API server on http://localhost:7822
 ```
 
+## Python
+
+We have Python packages based on **stac-rs** that live in their own repositories:
+
+- [stacrs](https://github.com/gadomski/stacrs) provides a Python API to **stac-rs**, including
+  - Reading and writing [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet)
+  - Migrating to [STAC v1.1](https://github.com/radiantearth/stac-spec/releases/tag/v1.1.0)
+  - [More...](https://www.gadom.ski/posts/stacrs-python-v0-1/)
+- [pgstacrs](https://github.com/stac-utils/pgstacrs) is a Python library for working with [pgstac](https://github.com/stac-utils/pgstac)
+
 ## Crates
 
 This monorepo contains several crates:

crates/api/src/item_collection.rs

@@ -1,18 +1,46 @@
 use crate::{Item, Result};
-use serde::{Deserialize, Serialize};
+use serde::{Deserialize, Deserializer, Serialize};
 use serde_json::{Map, Value};
 use stac::{Href, Link};
 use stac_derive::{Links, SelfHref};
 
+const ITEM_COLLECTION_TYPE: &str = "FeatureCollection";
+
+fn item_collection_type() -> String {
+    ITEM_COLLECTION_TYPE.to_string()
+}
+
+fn deserialize_item_collection_type<'de, D>(
+    deserializer: D,
+) -> std::result::Result<String, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let r#type = String::deserialize(deserializer)?;
+    if r#type != ITEM_COLLECTION_TYPE {
+        Err(serde::de::Error::invalid_value(
+            serde::de::Unexpected::Str(&r#type),
+            &ITEM_COLLECTION_TYPE,
+        ))
+    } else {
+        Ok(r#type)
+    }
+}
+
 /// The return value of the `/items` and `/search` endpoints.
 ///
 /// This might be a [stac::ItemCollection], but if the [fields
 /// extension](https://github.com/stac-api-extensions/fields) is used, it might
 /// not be. Defined by the [itemcollection
 /// fragment](https://github.com/radiantearth/stac-api-spec/blob/main/fragments/itemcollection/README.md).
 #[derive(Debug, Serialize, Deserialize, Default, Links, SelfHref)]
-#[serde(tag = "type", rename = "FeatureCollection")]
 pub struct ItemCollection {
+    #[serde(
+        default = "item_collection_type",
+        deserialize_with = "deserialize_item_collection_type"
+    )]
+    r#type: String,
+
     /// A possibly-empty array of Item objects.
     #[serde(rename = "features")]
     pub items: Vec<Item>,
@@ -104,6 +132,7 @@ impl ItemCollection {
     pub fn new(items: Vec<Item>) -> Result<ItemCollection> {
         let number_returned = items.len();
         Ok(ItemCollection {
+            r#type: item_collection_type(),
             items,
             links: Vec::new(),
             number_matched: None,

crates/api/src/lib.rs

@@ -81,22 +81,20 @@ mod url_builder;
 
 #[cfg(feature = "client")]
 pub use client::{BlockingClient, Client};
-pub use {
-    collections::Collections,
-    conformance::{
-        Conformance, COLLECTIONS_URI, CORE_URI, FEATURES_URI, FILTER_URIS, GEOJSON_URI,
-        ITEM_SEARCH_URI, OGC_API_FEATURES_URI,
-    },
-    error::Error,
-    fields::Fields,
-    filter::Filter,
-    item_collection::{Context, ItemCollection},
-    items::{GetItems, Items},
-    root::Root,
-    search::{GetSearch, Search},
-    sort::{Direction, Sortby},
-    url_builder::UrlBuilder,
+pub use collections::Collections;
+pub use conformance::{
+    Conformance, COLLECTIONS_URI, CORE_URI, FEATURES_URI, FILTER_URIS, GEOJSON_URI,
+    ITEM_SEARCH_URI, OGC_API_FEATURES_URI,
 };
+pub use error::Error;
+pub use fields::Fields;
+pub use filter::Filter;
+pub use item_collection::{Context, ItemCollection};
+pub use items::{GetItems, Items};
+pub use root::Root;
+pub use search::{GetSearch, Search};
+pub use sort::{Direction, Sortby};
+pub use url_builder::UrlBuilder;
 
 /// Crate-specific result type.
 pub type Result<T> = std::result::Result<T, Error>;

crates/cli/README.md

@@ -23,37 +23,45 @@ cargo install stac-cli
 Then:
 
 ```shell
-stacrs --help
+# Search
+$ stacrs search https://landsatlook.usgs.gov/stac-server \
+    --collections landsat-c2l2-sr \
+    --intersects '{"type": "Point", "coordinates": [-105.119, 40.173]}' \
+    --sortby='-properties.datetime' \
+    --max-items 1000 \
+    items.parquet
+
+# Translate formats
+$ stacrs translate items.parquet items.ndjson
+$ stacrs translate items.ndjson items.json
+
+# Migrate STAC versions
+$ stacrs translate item-v1.0.json item-v1.1.json --migrate
+
+# Search stac-geoparquet (no API server required)
+$ stac search items.parquet
+
+# Server
+$ stacrs serve items.parquet  # Opens a STAC API server on http://localhost:7822
 ```
 
 ## Usage
 
 **stacrs** provides the following subcommands:
 
-- `stacrs item`: create STAC items and combine them into item collections
-- `stacrs migrate`: migrate a STAC object to another version
-- `stacrs search`: search STAC APIs (and geoparquet, with the experimental `duckdb` feature)
-- `stacrs serve`: serve a STAC API (optionally, with a [pgstac](https://github.com/stac-utils/pgstac) backend)
-- `stacrs translate`: convert STAC values from one format to another
-- `stacrs validate`: validate STAC items, catalogs, and collections using [json-schema](https://json-schema.org/)
+- `stacrs search`: searches STAC APIs and geoparquet files
+- `stacrs serve`: serves a STAC API
+- `stacrs translate`: converts STAC from one format to another
 
 Use the `--help` flag to see all available options for the CLI and the subcommands:
 
 ## Features
 
-This crate has features:
+This crate has two features:
 
-- `duckdb`: experimental support for querying [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet) files using [DuckDB](https://duckdb.org/)
-- `geoparquet`: read and write [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet) (enabled by default)
 - `pgstac`: enable a [pgstac](https://github.com/stac-utils/pgstac) backend for `stacrs serve` (enabled by default)
 - `python`: create an entrypoint that can be called from Python (used to enable `python -m pip install stacrs-cli`)
 
-If you don't want to use any of the default features:
-
-```shell
-cargo install stac-cli --no-default-features
-```
-
 ## Other info
 
 This crate is part of the [stac-rs](https://github.com/stac-utils/stac-rs) monorepo, see its README for contributing and license information.

crates/cli/src/lib.rs

@@ -1,14 +1,10 @@
 use anyhow::{anyhow, Error, Result};
 use clap::{Parser, Subcommand};
-use stac::geoparquet::Compression;
-use stac::{Collection, Format, Item, Links};
+use stac::{geoparquet::Compression, Collection, Format, Item, Links, Migrate};
 use stac_api::{GetItems, GetSearch, Search};
 use stac_server::Backend;
-use std::collections::HashMap;
-use std::io::Write;
-use std::str::FromStr;
-use tokio::io::AsyncReadExt;
-use tokio::net::TcpListener;
+use std::{collections::HashMap, io::Write, str::FromStr};
+use tokio::{io::AsyncReadExt, net::TcpListener};
 
 /// stacrs: A command-line interface for the SpatioTemporal Asset Catalog (STAC)
 #[derive(Debug, Parser)]
@@ -94,6 +90,20 @@ pub enum Command {
         ///
         /// To write to standard output, pass `-` or don't provide an argument at all.
         outfile: Option<String>,
+
+        /// Migrate this STAC value to another version.
+        ///
+        /// By default, will migrate to the latest supported version. Use `--to`
+        /// to specify a different STAC version.
+        #[arg(long = "migrate", default_value_t = false)]
+        migrate: bool,
+
+        /// Migrate to this STAC version.
+        ///
+        /// If not provided, will migrate to the latest supported version. Will
+        /// only be used if `--migrate` is passed.
+        #[arg(long = "to")]
+        to: Option<String>,
     },
 
     /// Searches a STAC API or stac-geoparquet file.
@@ -202,9 +212,20 @@ impl Stacrs {
             Command::Translate {
                 ref infile,
                 ref outfile,
+                migrate,
+                ref to,
             } => {
-                let value = self.get(infile.as_deref()).await?;
-                self.put(outfile.as_deref(), value).await
+                let mut value = self.get(infile.as_deref()).await?;
+                if migrate {
+                    value = value.migrate(
+                        &to.as_deref()
+                            .map(|s| s.parse().unwrap())
+                            .unwrap_or_default(),
+                    )?;
+                } else if let Some(to) = to {
+                    eprintln!("WARNING: --to was passed ({to}) without --migrate, value will not be migrated");
+                }
+                self.put(outfile.as_deref(), value.into()).await
             }
             Command::Search {
                 ref href,
@@ -263,11 +284,11 @@ impl Stacrs {
                 for href in hrefs {
                     let value = self.get(Some(href.as_str())).await?;
                     match value {
-                        Value::Stac(stac::Value::Collection(collection)) => {
+                        stac::Value::Collection(collection) => {
                             if load_collection_items {
                                 for link in collection.iter_item_links() {
                                     let value = self.get(Some(link.href.as_str())).await?;
-                                    if let Value::Stac(stac::Value::Item(item)) = value {
+                                    if let stac::Value::Item(item) = value {
                                         items.entry(collection.id.clone()).or_default().push(item);
                                     } else {
                                         return Err(anyhow!(
@@ -278,7 +299,7 @@ impl Stacrs {
                             }
                             collections.push(collection);
                         }
-                        Value::Stac(stac::Value::ItemCollection(item_collection)) => {
+                        stac::Value::ItemCollection(item_collection) => {
                             for item in item_collection.items {
                                 if let Some(collection) = item.collection.clone() {
                                     items.entry(collection).or_default().push(item);
@@ -287,7 +308,7 @@ impl Stacrs {
                                 }
                             }
                         }
-                        Value::Stac(stac::Value::Item(item)) => {
+                        stac::Value::Item(item) => {
                             if let Some(collection) = item.collection.clone() {
                                 items.entry(collection).or_default().push(item);
                             } else {
@@ -318,17 +339,17 @@ impl Stacrs {
         }
     }
 
-    async fn get(&self, href: Option<&str>) -> Result<Value> {
+    async fn get(&self, href: Option<&str>) -> Result<stac::Value> {
         let href = href.and_then(|s| if s == "-" { None } else { Some(s) });
         let format = self.input_format(href);
         if let Some(href) = href {
             let value: stac::Value = format.get_opts(href, self.opts()).await?;
-            Ok(value.into())
+            Ok(value)
         } else {
             let mut buf = Vec::new();
             let _ = tokio::io::stdin().read_to_end(&mut buf).await?;
             let value: stac::Value = format.from_bytes(buf)?;
-            Ok(value.into())
+            Ok(value)
         }
     }
 
@@ -471,6 +492,16 @@ mod tests {
             .success();
     }
 
+    #[rstest]
+    fn migrate(mut command: Command) {
+        command
+            .arg("translate")
+            .arg("../../spec-examples/v1.0.0/simple-item.json")
+            .arg("--migrate")
+            .assert()
+            .success();
+    }
+
     #[test]
     fn input_format() {
         let stacrs = Stacrs::parse_from(["stacrs", "translate"]);