type values for record collections and "folders"

[m-mohr]

Extracting the discussion from #260:

No, the intention is that they would touch but the problem is that "catalogue" in OAPIR means a "collection or records" so we had a terminology problem and decided to use the term "folder" since it seemed like the function of a "STAC catalogue" was to act like a folder or directory for organizing records to be crawled (hopefully that interpretation is correct) .

A folder is a collection of references to any type of OAPIR resource including records, record collections (i.e. catalogues), other folders. A collection (or record collection or catalogue in OAPIR) strictly references records.

Folder has the following members:

• id, type(=Folder), title, description, keywords, created, updated, language, languages, extent, links.

Record collection had the following members:

• id, type(=Catalogue), title, description, keywords, created, updated, language, languages, extent, links.
• itemType, crs, conformsTo, themes, contacts, licence, right, properties.

Originally "folder" had 4 members: id, type(=Folder), title and links but then we got into a bit of a "it would nice if" game and > started adding more stuff! LOL!

Originally posted by @pvretano in #260 (comment)

Maybe I'm playing devils advocate now, but if the thing is called "Record Collection", why don't you use the type = "Collection"? It would sort out the STAC alignment issues, too. The entities in STAC and Record are very similar, but right now the conflict and as such you need to duplicate those entities. Having the long-term vision that records is the baseline and STAC is an extension/profile of it, I would encourage to think about this alignment once more.

It might be that I'm not seeing the full context and reasons behind it, but currently it looks like there are conflicts for no obvious reason.

[m-mohr]

I'm somewhat confused now. https://github.com/opengeospatial/ogcapi-records/blob/master/core/standard/clause_8_collection.adoc says that the type is actually "Collection" for Record Collections. Above it says that the type is Catalogue (which in STAC is written Catalog, by the way).

[pvretano]

A "collection of records" was callled a "Collection" but in PR #260, it was changed to "Catalogue" since that is what the enitity is really describing ... a catalogue ... and the term "collection" seemed too generic. However, I think you are right ... that change is causing unnecessary conflict and misalignment with STAC so I will change it back.
I tend to use ISO spelling rules which use UK English spelling and so ... catalogue.

[m-mohr]

Fair, but of course Catalogue and Catalog conflict again. Alignment with STAC requires "Catalog".

[pvretano]

OK ... backed out the "type=Collection" -> "type=Catalogue" change. So, a catalogue (aka a collection of records) is indicating using "type": "Collection". I believe this is consistent with STAC.

[m-mohr]

Thanks! Collection aligns very well, but Catalogue != Catalog so there's still a conflict. If there no other implications, we should use "Catalog".

[pvretano]

@m-mohr in the text of the specification I don't think using the "catalogue" spelling is a problem ... right? OAPIR does not currently use "Catalogue" for any member value any more (since I just backed out the change I mentioned above) so I think the only issue right now is what "type" value is used for a "folder".

I realize that STAC uses "Catalogue" for what we are calling a folder but I find that term very confusing used in this context ... that is for an entity that is used as "a flexible structure to link various STAC Items together to be crawled or browsed". I'll raise the issue in the SWG at the next meeting. Perhaps we can still call it a "folder" (rather than a catalogue) but set the type to "Catalogue" for STAC alignment? Just thinking out loud. We'll see what the SWG thinks.

[m-mohr]

The text in the specification can be in any flavour of English, I'm really just looking at the value of the type field itself.

In STAC it's Catalog, so if you want to align, it must be exactly that.

[m-mohr]

I also just realized that the documentation says the type for record collections is "Collections". The plural seems weird to me, shouldn't it be "Collection" as in STAC? See http://docs.ogc.org/DRAFTS/20-004.html#_collections_of_catalogue_resources

Edit: In http://docs.ogc.org/DRAFTS/20-004.html#record-collection-schema it says Collection, so I assume it's a typo.

[pvretano]

07-AUG-2023: OGC requires US spelling so all "catalogue" values should be updated to "catalog". Also as per this comment (#264 (comment)), the type value for collections should be "collection" (singular).

[pvretano]

30-OCT-2023: Folder PR #260 was rejected and all references to "catalogue" have been changed to "catalog" (i.e. US spelling). Closing this issure.