Restructuring the repository

[m-mohr]

As the spec and repository grows, things get structured based on historical decisions and don't reflect the current state of the spec well enough. As discussed on Gitter, there are several things that - IMHO - need to be restructured / changed:

Root:

• [x] Rename folder json-spec to item-spec
• [x] Rename folder static-catalog to catalog-spec
• [x] README: Update to reflect current changes (maybe shorten things a bit or put things in separate files)
• [x] Separate Contributing guidelines
• [x] how-to-help: Update to reflect current changes
• [ ] roadmap: Update to reflect current changes (#296)
• [x] Remove package-lock.json (no corresponding package.json available?)

API spec:

• [x] README: Update to reflect current changes
• [ ] Review naming (see below)
• [ ] Separate into api-spec.md and README.md (see Item spec) (#297)

Extensions:

• [x] Move EO extension + examples to a separate folder
• [x] Move Collection extension + examples to a separate folder (wait for #174)
• [x] Move start-end-datetime extension to a separate folder (wait for #221)

I think all extensions should reside in a separate folder. They should consist of at least three files anyway, which is enough to get a separate folder to not clutter the extensions folder.

JSON/Item spec:

• [x] Move sample and sample-full to examples folder
• [x] README: Rework completely to reflect that it is the item spec folder, moving some stuff to the top level (as it applies to all specs).
• [x] Move package.json / package-lock.json to .cirecleci or wherever central validation info should be stored
• [x] Check whether we still need the json-schema/geojson.json
• [x] Kill the NAIP examples (#204)

Static catalog / catalog spec:

• [x] Needs a complete rewrite with the introduction of datasets.
• [x] Make a separate file for static catalog related information and check whether the static-recommendations can be added there.
• [x] Separate into catalog-spec.md and README.md (see Item spec)
• [ ] Review naming (see below)

Dataset Spec:

• [x] Separate into dataset-spec.md and README.md (see Item spec)

General:

• [ ] Format all examples using the same style, e.g. by using https://jsonformatter.org/ (#298)

There are probably things to be added, feel free to add them below.

[matthewhanson]

+1, all looks good to me. I don't have any additional things off-hand, but I think we should probably do such a reorg sooner rather than later.

[cholmes]

Just put this in a review comment on the relevant PR, but worth pulling up here:

I want to review the 'naming' a bit. I fully agree we need to shift the naming, but I'm not sure STAC Catalog and STAC API are the best names. I'm definitely cool to merge this though, as it's a ton of great improvements.

But the 'SpatioTemporal Asset Catalog Catalog Spec' is the expanded version of 'STAC Catalog Spec', which is a bit weird. Also I think this spec should also have the /stac OpenAPI definition in it. Hopefully it's not a huge pain to build from the fragments for a /stac endpoint in this folder. But I'd ideally like to explain what the core 'catalog' is, and then express it in both OpenAPI and JSON Schema versions. And explain the core concept of the catalog here, and explain it can be done with static files or a dynamic server.

Not super set on the exact dividing between folders, but I do think we should introduce 'catalogs' and then from there explain the different implementation options (static (on s3, etc with links) and dynamic (implemented with a server)).

[m-mohr]

Also mentioned by @cholmes in the mentioned PR (#202) for the static-catalog/README.md:

The core spec starts to get pretty long here, and this & the next section don't necessarily add a whole lot. We could follow the stac-item folder a bit more closely, with a -spec.md and a readme. The readme can contain more info like this and the next section, and the -spec.md can be the actual core spec, and we keep that nice and tight.

[cholmes]

Thinking about this more, I think I do like 'item-spec' and 'catalog-spec'. And then I think we should put the /stac openapi doc in the 'catalog-spec', and then rename 'api-spec' to 'search-spec'.

Then we can still talk about 'static catalogs', that are a special case of catalogs that are implemented on S3/GCS/file servers, etc. But it's more just a note on implementation at the end, and we can also note that dynamic servers can organize catalogs how they want, etc.

[m-mohr]

Not sure whether we should really separate the API. I think it is nice to have it in a single rendered API documentation. Gives a better overview - in my opinion. But maybe that splitting it can be compensated by a good and straightforward documentation?

[cholmes]

Yeah, I see the appeal of having API all in one place. But if /stac implements catalog spec then I think we should probably have that openapi document there? Like it feels weird to wait to put any api document up until we talk about 'search'.

Like if we didn't split it up then I think it'd make sense to have spec docs for item, catalog and search, and then a api folder that is the openapi versions of things. Search I guess would just be an overview. And maybe a json schema validator of the search response?

[matthewhanson]

@m-mohr is this issue still valid given that the PR is merged?

[m-mohr]

@matthewhanson Yes, there is a todo list in the first comment/entry, which has some points still open/unchecked.

[matthewhanson]

@m-mohr this is part of the 0.6.0-rc1 milestone, can it be closed?

[cholmes]

I'll open issues on the remaining todos, and close this one once I do.

[cholmes]

Closing this issue, as the remaining open todos are now their own issues in future milestones: #296 #297 and #298

Thanks for all your work on this @m-mohr!