Add Folder conformance class.

[pvretano]

Closes #222

[m-mohr]

What's the actual difference between Catalog/Folder and Collection in OAR? The only required field that the Collection adds is really the title (for which many implementations just use the id). All other fields seem to be aligned (or missing). As most fields in Collections are optional anyway you could simply leave them out if you want to create a "folder" using a Collection, I don't clearly see what OAR adds a Folder for. You can pretty much can not distinguish them... In STAC a Collection requires more fields (license, extent), so has somewhat a reason to exist, but I don't quite get it in OAR. Is the only difference the type (and title) so that you can distinguish them in the API so that they are not listed in /collections?

[pvretano]

29-MAY-2023: The main sticking point right now is the value of the type field for the folder object. Right now that value is fixed to "Folder" but this then introduces a friction point with STAC where the value of type for the analogous object is "Catalog". We discussed this issue in the SWG and could not come to a consensus. The options discussed were: (1) Leave the value as "Folder". This, unfortunately, forces people deploying crawlable catalogues that want to conform to this specification but also leverage STAC tooling to maintain two parallel structures (i.e. an OAPIR folder and a STAC catalog). (2) Change the value of type to "Catalog". This would allow someone deploying an OAPIR-compliant crawlable catalogue to leverage STAC tooling but would be a bit confusing since we use the term "folder" everywhere in this conformance class but the type is "Catalog". I should point out that for this option we would include a note explaining why the conformance class is called "Folder" but the type is "Catalog". (3) Allow either or value. A possibility but introduces more option and thus more opportunities for incompatability.

It would be good if @m-mohr could join the next SWG teleconference to add his thoughts to this dicsussion.

There was also mention of how difficult it would be for STAC tooling to be updated to accept either "Catalog" or "Folder".

There was also discussion about the spelling of the "catalogue" used in the specification. At the moment, with relation to the "value-of-type" issue its a blessing since the two concepts -- OAPIR Catalogue versus STAC Catalog -- are different and so the two different spellings play into that difference. However, the OGC has a rule about using US spelling and so we would, eventually, need to change all references to "catalogue" to "catalog".

@cportele mentioned that if we go with the "catalogue" spelling we should probably have a note in the standard about this.

[m-mohr]

@pvretano On June, 12 I'm attending the OGC API - Tiles sprint remotely and on June, 26 I'm in Kosovo for FOSS4G, so it will be hard for me to join the Record meetings in June.

My long-term vision would be to make STAC a "profile" or "extension" of Records, but for that we need to at least erase all conflicts. The only real conflict I found so far (I'm currently writing a comparison) is the Folder type. There are other differences to look at, but those are less intrusive and don't require duplicating data. I understand that the Catalog terminology is not ideal for Records, but on the other hand it's just a constant value in a JSON document that end-users would ideally never see (due to client software). Due to the broad adoption of STAC, I'd argue OAR1 has a good enough reason to align with STAC here.

[cnreediii]

@m-mohr COncur: Write Records the way the SWG members think it should be and then craft one or more profiles/extensions.

[pvretano]

Closes #260 Closes #264

[pvretano]

07-JUN-2023: It was pointed out at the Records session at the TC that the term "Folder" might imply that duplicate entries are not allowed ... that is things cannot live in two folders simultaneously and thus we should think of a better name. I am not sure I agree with this but I thought I should post the comment for consideration by the group. I found these on the Web:

• https://simple.wikipedia.org/wiki/Folder_(computing)
• https://en.wikipedia.org/wiki/Directory_(computing)#Folder_metaphor

So, my feeling is that the term "Folder" is just fine. However, if others have a different opinion please chime in.

[m-mohr]

I heard that comment from @matthewhanson in the session. It was more an explanation why it's not called folder in STAC, but instead it's called Catalog. Folder sounds file system specific and people may thing that it's always a folder in the file system, which often it is not (think S3 for example). A more generic term is Group, but that's probably too generic. Catalog was a good compromise. But I guess this issue is more in the terminology that is used in the specification and in spoken language. The actual conflict between STAC and Records is not there, it's just in the type field value. I don't think the field value and what Records uses as a phrase to describe the construct don't necessarily need to match. Even if the type is Catalog as in STAC, you can still name the whole construct differently.

[matthewhanson]

@m-mohr captured my thoughts well. I think traditionally Folders are a hierarchical organization method which doesn't allow items stored in multiple locations. This of course gave rise to the use of links which is a way to get around this, although there is often a preferred (original) location. Gmail didn't use the term folder to organize email I think because of this and instead use the term "tags".

However, duplicate items aside, in STAC you could have 5 catalogs that each point to 5 items and all of the catalogs and items could actually be contained within a single folder which I think is the bigger conflict, conceptually with the term "folder".

[cnreediii]

@pvretano I concur with your thinking. Also, WRT "On some operating systems, shortcuts or links can be made from one folder to another to make it appear that one file or folder is contained in two different parent folders." The OGC portal app supports this capability.

[cnreediii]

@m-mohr Well, the Wikipedia definition states, "a folder (also called directory, or catalog) ". Just sayin'

[pvretano]

05-JUL-2023: Originally the Records specification had two objects ... the collection and the record. If you wanted to encode a hierarchy ... as per the clause Collection of catalogue resources ... you simply used intermediate collection objects to link the resources up accordingly. This seems to us a cleaner and more "compatible with STAC" approach then defining a new Folder conformance class. So, @pvretano will (a) discard this folder conformance class and (b) clean up the language is the Collection of catalogue resources clause to be more clear.

[m-mohr]

Do I understand correctly, that you then always use "Collections" for grouping and there are no "Catalogs"/"Folders" at all?

[pvretano]

@m-mohr, yes, that is correct. There are two objects ... one of type "collection" and one of type "record". The collection object can point to records, or other collections or other related resources so using a collection object you can, for example, define a folder-like hierarchy. This what was in records originally before we tried the "add-a-folder-conformance-class" experiment.

[pvretano]

No longer relevant since we decided to overload the record collection object to perform this function.