Ingesting Datasets Into Tilebox

Design and implement repeatable converters for discrete scenes, acquisitions, products, and other records that fit Tilebox's temporal or spatiotemporal catalog model. STAC is the primary and best-documented input, but provider XML/JSON, APIs, buckets, and file trees are supported when their evidence can establish the same canonical semantics.

Operating Contract

Follow these rules for every new ingestor:

1. Check suitability before designing a schema. Tilebox catalog datasets represent discrete records with stable identity, time, and usually geometry. Do not manufacture scene records from chunks or slices of an analysis-ready multidimensional cube.
2. Discover before creating. Inspect representative records, source collections, file layouts, and known variants before proposing fields or Tilebox collections.
3. Produce a clean modern STAC model, not a source mirror. Normalize older STAC and non-STAC inputs to canonical STAC 1.1 and current stable extension semantics before designing Tilebox fields. Replace deprecated properties with their modern equivalents, omit redundant legacy properties when their semantics are preserved elsewhere, and keep raw source paths only in the conversion recipe.
4. Keep only dedicated STAC structures dedicated. Use Geometry for the required spatial field. The only STAC-specific structured dataset fields are Assets, Links, Provider, ProcessingSoftware, Storage, and Authentication. Flatten Item-level extension property groups such as SARProperties, SatelliteProperties, and ProductProperties into typed fields; enums may remain enum-typed. Do not flatten Asset- or Band-scoped metadata, because that would lose its association.
5. Prefer authoritative typed values. For standard STAC extension properties, derive target types from the modern canonical extension JSON Schema, not its README table or only the observed JSON; use legacy schemas only to parse legacy input. Convert source decimal strings that semantically encode integers back to the narrowest correct Tilebox integer type. Do not use JSON strings, google.protobuf.Value, or Struct to bypass uncertain source types unless the canonical field itself is specified as arbitrary JSON.
6. Never guess through ambiguity or silently drop metadata. Stop, show evidence, propose alternatives, and persist the user's decision in the conversion recipe.
7. Keep source normalization in the converter. Every converter validates its source and owns provider-specific parsing and STAC 1.1 normalization, including mapping provider processing-level fields to canonical processing:level values.
8. Create and inspect schemas through the Tilebox CLI. Include schema discovery and creation as explicit workflow steps rather than putting them inside the ingestion program.
9. Validate before bulk ingestion. Query representative samples back from Tilebox and compare their canonical semantics before enabling a full run.

Choose The Relevant References