Skip to content

Clarified that trailing slashes in URIs are significant. #1214

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 31, 2023
Merged

Clarified that trailing slashes in URIs are significant. #1214

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.

- "Strongly recommended" language around `self` links in the item spec. ([#1173](https://github.com/radiantearth/stac-spec/pull/1173))

### Changed

- Clarified that trailing slashes in URIs are significant. ([#1212](https://github.com/radiantearth/stac-spec/discussions/1212))

## [v1.0.0] - 2021-05-25

### Added
Expand Down
15 changes: 14 additions & 1 deletion best-practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
- [Schema.org, JSON-LD, DCAT, microformats, etc](#schemaorg-json-ld-dcat-microformats-etc)
- [Deploying STAC Browser](#deploying-stac-browser)
- [Requester Pays](#requester-pays)
- [Consistent URIs](#consistent-uris)
- **[Item Best Practices](#item-practices)**
- [Field and ID formatting](#item-ids)
- [Searchable Identifiers](#searchable-identifiers)
Expand Down Expand Up @@ -146,6 +147,18 @@ For data providers using STAC with requester pays buckets, there are two main re
allow the data provider to properly charge for access.
STAC-specific tools in turn can look for the cloud-specific protocols and know to use the requestor pays feature for that specific cloud platform.

### Consistent URIs

Links in STAC can be [absolute or relative](#use-of-links).
Relative links must be resolved against the absolute URI given in the link with the relation type `self` (or in some cases `root`).
To resolve relative URIs the base URIs must be precise and consistent: Having or not having a trailing slash is significant.
Without it, the last path component is considered to be a "file" name to be removed to get at the "directory" that is used as the base.
API endpoints usually behave like directories.

**Examples:**
- <https://example.com/folder/catalog.json> is good and <https://example.com/folder/catalog.json/> is problematic as catalog.json is a specific file
- <https://example.com/api/> is good and <https://example.com/api> is problematic as `api` should not be removed when resolving URIs.

## Item Practices

### Item IDs
Expand Down Expand Up @@ -633,7 +646,7 @@ multiple sources to achieve this.

So if you are writing a STAC client it is recommended to start with just supporting these two types of published catalogs. In
turn, if your data is published online publicly or for use on an intranet then following these recommendations will ensure
that a wider range of clients will work with it.
that a wider range of clients will work with it.

### Using Relation Types

Expand Down
2 changes: 1 addition & 1 deletion catalog-spec/catalog-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ with links.

| Field Name | Type | Description |
| ---------- | ------ | ----------- |
| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. |
| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) |
| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter ["Relation types"](#relation-types) for more information. |
| type | string | [Media type](#media-types) of the referenced entity. |
| title | string | A human readable title to be used in rendered displays of the link. |
Expand Down
2 changes: 1 addition & 1 deletion collection-spec/collection-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,7 @@ This object describes a relationship with another entity. Data providers are adv

| Field Name | Type | Description |
| ---------- | ------ | ------------------------------------------------------------ |
| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. |
| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) |
| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "[Relation types](#relation-types)" for more information. |
| type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. |
| title | string | A human readable title to be used in rendered displays of the link. |
Expand Down
4 changes: 2 additions & 2 deletions item-spec/item-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ It is allowed to add additional fields such as a `title` and `type`.

| Field Name | Type | Description |
| ---------- | ------ | ----------- |
| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. |
| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) |
| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "Relation types" for more information. |
| type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. |
| title | string | A human readable title to be used in rendered displays of the link. |
Expand Down Expand Up @@ -234,7 +234,7 @@ or streamed. It is allowed to add additional fields.

| Field Name | Type | Description |
| ----------- | --------- | ----------- |
| href | string | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. |
| href | string | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) |
| title | string | The displayed title for clients and users. |
| description | string | A description of the Asset providing additional details, such as how it was processed or created. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
| type | string | [Media type](#asset-media-type) of the asset. See the [common media types](../best-practices.md#common-media-types-in-stac) in the best practice doc for commonly used asset types. |
Expand Down