Skip to content
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

Relative vs absolute link edits #953

Merged
merged 7 commits into from
Feb 4, 2021
Merged

Relative vs absolute link edits #953

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a747a87
updated sections on absolute vs relative links for consistency and cl…
cholmes Jan 26, 2021
6aae5b3
Update catalog-spec/catalog-spec.md
cholmes Jan 28, 2021
2f223ae
Validate URLs (IRIs) correctly in JSON Schema
m-mohr Feb 2, 2021
6c7140a
Merge branch 'dev' into rel-abs-edits
cholmes Feb 3, 2021
e487b1f
Merge branch 'dev' into rel-abs-edits
m-mohr Feb 4, 2021
714752b
Update best-practices.md
m-mohr Feb 4, 2021
db9b1a3
Reformatting and remove duplicate content?!
m-mohr Feb 4, 2021
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
6 changes: 3 additions & 3 deletions best-practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,10 +253,10 @@ STAC version. Otherwise some behaviour of functionality may be unpredictable (e.

## Use of links

The main catalog specification allows both relative and absolute links, and says that `self` links are not required, but are
The main STAC specifications allow both relative and absolute links, and says that `self` links are not required, but are
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe The main STAC specifications allow -> The STAC specification allows

What is meant by main? Are there other specifications in play here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll work to clarify this. Catalog, Item and Collection are all technically their own 'spec', designed to potentially use stand alone, so that's all I meant. I was changing it to not seem like it was implying just the 'catalog' spec. But I see how 'main' is confusing.

m-mohr marked this conversation as resolved.
Show resolved Hide resolved
strongly recommended. This is what the spec must say to enable the various use cases, but there is more subtlety for when it
is essential to use different link types. The best practice is to use one of the below
catalog types, applying the link recommendations consistently, instead of just haphazardly applying anything the spec allows.
is essential to use different link types. The best practice is to use one of the below catalog types, applying the link
recommendations consistently, instead of just haphazardly applying relative links in some places and absolute ones in other places.

### Self-contained Catalogs

Expand Down
6 changes: 3 additions & 3 deletions catalog-spec/catalog-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,9 @@ with links.

A more complete list of possible 'rel' types can be seen at the [IANA page of Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml).

Please see the chapter 'relative vs absolute links' in the [Item spec](../item-spec/item-spec.md#relative-vs-absolute-links)
for a discussion on that topic, as well as the [use of links](../best-practices.md#use-of-links) section of the
catalog best practices document.
Currently, the JSON schema for links does not require them to be formatted as URIs, to allow implementors
cholmes marked this conversation as resolved.
Show resolved Hide resolved
to provide relative links. For a full discussion of the situations where each are recommended see
[this section](../best-practices.md#use-of-links) of the STAC best practices.

#### Relation types

Expand Down
4 changes: 3 additions & 1 deletion collection-spec/collection-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,9 @@ This object describes a relationship with another entity. Data providers are adv

A more complete list of possible 'rel' types can be seen at the [IANA page of Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml).

Please see the chapter 'relative vs absolute links' in the [Item spec](../item-spec/item-spec.md#relative-vs-absolute-links) for a discussion on that topic.
Currently, the JSON schema for links does not require them to be formatted as URIs, to allow implementors
to provide relative links. For a full discussion of the situations where each are recommended see
[this section](../best-practices.md#use-of-links) of the STAC best practices.

#### Relation types

Expand Down
8 changes: 3 additions & 5 deletions item-spec/item-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,11 +116,9 @@ It is allowed to add additional fields such as a `title` and `type`.

#### Relative vs Absolute links

Currently, the JSON schema for links does not require them to be formatted as URIs, to allow
implementors to provide relative links. In general, Catalog APIs should aim to provide absolute links
whenever possible. Static Catalogs are potentially more portable if they incorporate only
relative links, so that every link doesn't need to be rewritten when the data is copied. Additional
recommendations for particular `rel` types are given in the `rel` type description.
Currently, the JSON schema for links does not require them to be formatted as URIs, to allow implementors
to provide relative links. For a full discussion of the situations where each are recommended see
[this section](../best-practices.md#use-of-links) of the STAC best practices.

#### Relation types

Expand Down