New naming rules codes and concept schemes

[pvdbosch]

Align with REST guide for code schemas - https://github.com/belgif/rest-guide/issues/94:

• JSON property names shouldn't include a suffix "Code" or "Id" to refer to an entity. We should apply this to properties in fedvoc as well.
• the OpenAPI types should be suffixed with "Code" or "Id". We could apply this to concept schemes as well, but it's less necessary than for OpenAPI where the labels aren't included in a type, while a ConceptScheme does include them.

Status (*) = old:

with code (~ OpenAPI types)	without code	status
GenderCode(*)	Gender	already OK
HouseholdRelationTypeCode	HouseholdRelationType(*)	still in beta; changed in main branch to Code
CivilStatusTypeCode	CivilStatusType(*)	still in beta; changed in main branch to Code
RegionCode(*)	Region	already OK
CountryNisCode(*)	CountryNis	already OK
CurrencyCode	Currency(*)	updated in 1.1.0; deprecated old name
MunicipalityCode (*)	Municipality	already OK

Property that should be converted to a ConceptScheme: countryWithHistoryIsoCode CountryWithHistoricIsoCode + inSwagger (draft tab)

Properties that can be removed because general "country" property exists, as well as ConceptSchemes:

• countryIsoAlpha3Code
• countryIsoCode
• countryIsoNum3Code
• countryNisCode

[JDMKSZ]

My comment on this during the meeting last Friday: as a ConceptScheme in itself contains (a list of concepts having) a code (notation?) plus a label, I don't think the -Code suffix is necessary/appropriate.

[pvdbosch]

From what I'm reading, I think we're mixing up skos:Concept(Scheme) and skos:notation in FedVoc.

A skos:ConceptScheme is a collection of a set of Concepts. A skos:Concept is a conceptual definition, independent of any notation. A skos:notation is a lexical notation / codification.

An example based on the EU country authority list:

https://publications.europa.eu/resource/authority/country is the ConceptScheme including all countries recognized by the EU http://publications.europa.eu/resource/authority/country/BEL is the Concept of the country Belgium. It has about 30 notations, e.g.:

• <skos:notation rdf:datatype="http://publications.europa.eu/ontology/euvoc#ISO_3166_1_ALPHA_3">BEL</skos:notation>
• <skos:notation rdf:datatype="http://publications.europa.eu/ontology/euvoc#ISO_3166_1_NUM">056</skos:notation>
• <skos:notation rdf:datatype="http://publications.europa.eu/ontology/euvoc#ISO_3166_1_ALPHA_2">BE</skos:notation>

So, applied to FedVoc:

• ConceptScheme - linked to authority defining the collection of concepts, without "Code" suffix:
  • we could define a ConceptScheme "Country" under the belgif namespace for all countries recognized by Belgium (i.e. the StatBel list)
  • we could also refer to https://publications.europa.eu/resource/authority/country for all countries recognized by EU
• there'd be a concept for each country. These can have multilingual labels. These concepts aren't included in FedVoc.
• We could add datatypes for each notation: we can reuse above URIs of EU for the ISO codes, and add one for the NIS codes. These can get the same name as the OpenAPI schemas, with a "Code" suffix.

[pvdbosch]

We'd have following modifications when going through fedvoc to separate concept schemes and notations: skos datatypes modifications.xlsx

(not all comments/definitions updated yet)

update: used Data Type instead of Notation in the excel

[pvdbosch]

a "Code" suffix has been added to all concerned schemas.

This unblocks then graduation of CivilStatusTypeCode and HouseholdRelationTypeCode:

• move them out of beta and release them ( https://github.com/belgif/openapi-person/issues/2 )
• set inOpenApi->yes for CivilStatusType and HouseholdRelationType in fedvoc

[MarcBruyland]

Issue can be closed as decided by the functional workgroup on 2024-04-12.