coding types: with or without suffix "Code"?

pvdbosch commented 4 years ago

ex.

Gender vs GenderCode
Municipality vs MunicipalityCode
Status vs StatusCode
Region vs RegionCode
CivilState vs CivilStateCode

In vocabularies excel and in Swagger.

Impact on:

clarity: code vs description/label fields
verbosity in JSON

smals-vea commented 4 years ago

I prefer to suffix the name by "Id" or "Code" or "Number" or "Name" to avoid confusing:

"municipalityName" is not the same as "municipalityCode" and we need the both
"region" or "regionName" is not the same as "regionCode"
in Best Address, they use "streetName", "municipalityName", "postName", "postCode", "municipalityCode", "houseNumber", "boxNumber"
in CBE, they use "cbeNumber", "enterpriseNumber", ...

pvdbosch commented 4 years ago

@MarcBruyland will examine difference property/concept/conceptScheme

I'll propose REST design group to use suffix (e.g. change to GenderCode)

MarcBruyland commented 4 years ago

Anomalies detected in our vocabulary document:

pvdbosch commented 4 years ago

CountryNisCode is an alternative for CountryIsoCode, so should be linked to same Concepts I guess.

pvdbosch commented 4 years ago

rename to GenderCode OK for REST design WG. Updated this in https://github.com/belgif/openapi-person/commit/915a802f9375148047a01c8df3d8226fb5270012

ConceptScheme in fedvoc should then be renamed as well.

smals-vea commented 3 years ago

@MarcBruyland ne faut-il pas aussi adapter le concept "Gender" en "GenderCode" ?

@MarcBruyland pourrais-tu harmoniser les labels et/ou définitions entre Concept et ConceptScheme ? exmples: countryNisCode, genderCode, positionGeometryMethod, positionSpecification, function, legalStatus, administrativeStatus, register

@MarcBruyland dans streetNameType, tu parles de "see code list" mais tu n'as pas mis l'hyperlink

@MarcBruyland pour les concepts territory, civilState il faut ajouter les concepSchemes Territory, CivilState

@MarcBruyland id366, supprimer les commentaires

pvdbosch commented 3 years ago

I wonder why we deviate from some other sources, by having all our coding lists (ConceptScheme) also defined as a "Concept" . Should we rather define them as "property" to link them to a Class, than as Concept?

E.g. VL has geslacht (property) which can be defined on a Persoon and has a range of Geslacht (ConceptScheme) while FED has gender (Concept) linked to Person and has range of GenderCode

MarcBruyland commented 3 years ago

Some rules for skos:

what do we have in fedvoc today ? This expresses that gender is a property of Person, its range is a concept and the related conceptscheme is GenderCode. Probably we should replace 'valueInScheme' by 'inScheme'.

MarcBruyland commented 3 years ago

Proposal:

gender -> domain-> Person gender -> range -> _Concept gender -> inScheme-> GenderCode

In sheet Vocabulary, we now have in column Type: Class, Property, ConceptScheme, Concept gender -> Property iso Concept (strictly speaking gender has a type Property and a range Concept)

The way to find out that the value of gender is a code in a Concept, is then to go to sheet Datamodels and look for the predicate range.

pvdbosch commented 3 years ago

@MarcBruyland ,

I agree with make gender a Property, but I think following would be more conform with use of skos in other vocabularies:

0 (unknown) type Concept 1 (male) type Concept 2 (female) type Concept

GenderCode type ConceptScheme 0 inScheme GenderCode 1 inScheme GenderCode 2 inScheme GenderCode

gender type Property gender domain Person gender range GenderCode

MarcBruyland commented 2 years ago

https://www.w3.org/TR/rdf-schema/#ch_range says: The triple P rdfs:range C states that P is an instance of the class rdf:Property, that C is an instance of the class rdfs:Class and that the resources denoted by the objects of triples whose predicate is P are instances of the class C.

If we say "gender range GenderCode", we say that gender is an instance of a ConceptScheme, while in fact it is an instance of a Concept (the value is one of the concepts of the conceptscheme, not the entire conceptscheme).

barthanssens commented 2 years ago

Or just use the Core Person existing http://publications.europa.eu/resource/authority/human-sex ...

fedv:gender rdfs:domain fedv:Person fedv:gender rdfs:range skos:Concept

fedv:GenderCodes a skos:ConceptScheme fedv:male a skos:Concept fedv:male skos:inScheme fedv:GenderCodes

Then use SHACL to check if the class the gender property points to belongs to the GenderCodes conceptscheme (but I assume that is meant by the Excel notation listed above)

pvdbosch commented 2 years ago

We are currently recommending the ISO-5218 codes. I hadn't seen the EU "human sex" concept scheme yet, but I wonder if it is commonly used; haven't seen it in exchanges yet (even European ones), and its descriptions limit it to the social sciences domain:

https://publications.europa.eu/resource/authority/human-sex/FEMALE

The concept FEMALE is used for representing the human sexes in the context of interchange of information in the social sciences domain.

It's also not referenced in the Person Core vocabularies Word doc (https://joinup.ec.europa.eu/collection/semantic-interoperability-community-semic/solution/core-person-vocabulary/release/100 )

@MarcBruyland , @barthanssens , OK I understand now that both "inScheme" and "range" aren't a good fit. It still seems useful to indicate in the Excel which ConceptSchemes are compatible with a specific property. Would that be doable with SHACL (I don't know it very well), or is SHACL always for a specific message or API?

Alternatively, we might define our own relation; like Marc had originally:

valueInScheme It wouldn't need to be necessarily restrictive that only that single scheme may be used; multiple schemes could be linked to a single property, e.g. > nationality valueInScheme CountryNisCode > nationality valueInScheme CountryIsoAlpha2Code

barthanssens commented 2 years ago

IMHO while the the notation in Excel is useful for business, it can be a bit confusing for techies like me :-)

SHACL can definitely be used to validate if a Concept (term) is in a specific ConceptScheme, e.g. the EU Data Portal uses DCAT-AP SHACL rules to validate if the categories are part of a controlled list of "allowed" themes.

SHACL isn't tied to any API, and also not tied to the vocabulary/ontologies being validated: it can be used to validate any set of statements ("dataset" or "message"), and it is possible to use different SHACL rules on the same set of statements (e.g. different applications may have different rules).

Since skos:Concepts are just classes in RDF, and RDF allow instances to have multiple classes, one could also create custom classes and mix them

fedv:gender rdfs:domain fedv:Person fedv:gender rdfs:range skos:Concept

fedv:Gender a rdfs:Class

fedv:GenderCodeScheme a skos:ConceptScheme fedv:male a skos:Concept fedv:male skos:inScheme fedv:GenderCodeScheme fedv:male a fedv:Gender;

Whether that's worth the extra work is debatable... It may have some benefit when applying logic reasoning (OWL), but probably not in our applications...

MarcBruyland commented 2 years ago

Proposal

AS-IS in fedvoc: gender type Concept GenderCode type ConceptScheme datamodel: gender domain Person gender range Concept gender valueInScheme GenderCode

TO-BE in fedvoc: gender type Property rest stays the same

List of data elements with type Concept in fedvoc (standard part): currency addressStatus countryIsoAlpha3Code countryIsoCode countryIsoNum3Code countryNisCode countryWithHistoryIsoCode positionGeometryMethod positionSpecification regionCode streetNameStatus streetNameType endReason function legalForm legalStatus nace2008 organizationType civilState gender householdRelationType

Question do we rename these data elements by systematically adding a suffix Code ?

belgif / fedvoc

coding types: with or without suffix "Code"? #2

Proposal: