explanation how to use fedvoc spreadsheet

[pvdbosch]

Based on feedback from colleagues at CBSS, it's not really straightforward how to work with the fedvoc Excel as a user e.g. for an author of a new REST API that wants to see if standardized vocabularies exist for his API.

We could add an "How To Use" in some places:

• README.md
• the REST guide
• at the beginning of the first sheet of the Excel

E.g. you should only look in the Standard sheet, you can filter on Ontology, and use the "name" column in APIs, and refer to Draft sheet as fallback.

Sidenote: On https://belgif.be/page/specifications.nl.html , best to rename "Federal Service Platform" to something like "Federal Vocabularies"

[smals-vea]

E.g. You should only look in the "Standard" sheet, you can filter on "Ontology" column, and use the "Name" column in APIs, and refer to "Draft" sheet as fallback. If the vocabulary exists already in a OpenAPI data type file, the "inSwagger" column is on "yes". See than https://github.com/belgif?q=openapi&type=&language=

[smals-vea]

@pvdbosch, faire une proposition de read.me pour la prochaine réunion du 29/10/2021

[pvdbosch]

updated 2021-09-06 based on feedback Smals

Proposition of a text:

When to use?

The FedVoc vocabularies describe semantics in domains commonly used by Belgian government institutions. You can use them during business analysis, when designing the data model of an application or when authoring specifications of an API or webservice (OpenAPI, WSDL/XSD, ...).

How to use?

How to read the FedVoc Excel file:

• Standardized vocabulary entries can be found in the sheet "Standard".
• To find entries more easily, you can filter on domain (column Ontology) or do a full search (Ctrl+F).
• Use the "Draft" sheet to find those that are still a work in progress.
• If you can't find a concept that's commonly used by Belgian government institutions, you may open an issue to request the concept to be added.
• The column Name provides a short name of the vocabulary entry. It should be used as the basis of technical names for the entry, for instance when the item is used in a REST APIs. LabelNL and LabelFR provide translations of this name.
• Columns Definition(NL/FR) specify a, preferably concise, definition of the entry while columns Comment(NL/FR) may provide additional information
• The column inSwagger indicates if the entry has a corresponding OpenAPI data type
• The government institutions tab provides the common names for Belgian Government institutions (code = abbreviation, name = full name, status = Draft/Standard)

More advanced, the "Datamodels" sheet shows the relationships between vocabulary entries. It can be read as: entry SubjectName has a relation of type predicate with entry ObjectName For instance: houseNumber domain BelgianAddress means that instances with the property houseNumber are of type BelgianAddress.

Other tabs contain the source data from which the consolidated tabs with the standardized or draft vocabularies are generated. They are only meant to input the vocabularies into the spreadsheet rather than for reading; their use is explained in the first "Intro" tab.

[smals-vea]

Bedankt Peter Nog Nice to have:

• Explain the "When to use?" and the "Who to use?" before the "How to use?"
• Proposal for "How to use?" : "Standardized vocabulary entries can be found in the sheet "Standard". You can filter on a specific domain (column B Ontology) to find entries more easily or make a full search. Use the "Draft" sheet to find those that are still a work in progress. If you don't find your concept, you can introduce an issue ...."

[pvdbosch]

@smals-vea , I updated the text in my above comment based on your feedback

[smals-vea]

@pvdbosch J'ai reçu la suggestion suivante: "Une courte explication sur les autres onglets existants serait intéressante. A quoi servent-il ?" Kan je ook een voorstel doen ?

[pvdbosch]

@smals-vea , updated proposal above:

• The government institutions tab provides the common names for Belgian Government institutions (code = abbreviation, name = full name, status = Draft/Standard)
• Other tabs contain the source data from which the consolidated tabs with the standardized or draft vocabularies are generated. They are only meant to input the vocabularies into the spreadsheet rather than for reading; their use is explained in the first "Intro" tab.

[smals-vea]

@pvdbosch, après relecture de l'ensemble, je propose quelques arrangements/restructuration du texte final. Wat denk je ?

When to use? The Federal Vocabularies (FedVoc) describe semantics in domains commonly used by Belgian government institutions. You can use them • during business analysis, when designing the data model of an application or • when authoring specifications of an API or webservice (OpenAPI, WSDL/XSD, ...).

If you can't find a concept that's commonly used by Belgian government institutions, you may open an issue to request the concept to be added.

How to use? How to read the FedVoc Excel file: • In the "Standard" sheet, you find the vocabulary entries accepted by the Federal government as standard vocabulary. o The column ‘Ontology’ gives the different domains covered by the vocabulary. To find entries more easily, you can filter on ‘Ontology’ or do a full search (Ctrl+F). o The column ‘Name’ provides a short name of the vocabulary entry. It should be used as the basis of technical names for the entry, for instance when the item is used in a REST APIs. o The columns ‘LabelNL’ and ‘LabelFR’ provide translations of this ‘Name’. o The columns ‘Definition’ (DefinitionNL/DefinitionFR) specify a, preferably concise, definition of the entry o The columns ‘Comment’ (CommentNL/CommentFR) may provide additional information o The column ‘inSwagger’ indicates if the entry has a corresponding OpenAPI data type • In the "Draft" sheet, you find the vocabulary entries that are still a work in progress. • The “Government institutions” sheet provides the common names for Belgian Government institutions (code = abbreviation, name = full name, status = Draft/Standard) • More advanced, the "Datamodels" sheet shows the relationships between vocabulary entries. It can be read as: entry ‘SubjectName’ has a relation of type ‘predicate’ with entry ‘ObjectName’ For instance: ‘houseNumber’ ‘domain’ ‘BelgianAddress’ means that instances with the property ‘houseNumber’ are of type ‘BelgianAddress’. • Other sheets contain the source data from which the consolidated sheets with the standardized or draft vocabularies are generated. They are only meant to input the vocabularies into the spreadsheet rather than for reading; their use is explained in the first "Intro" sheet.

[smals-vea]

@pvdbosch @MarcBruyland , feedback/proposition d'un de mes collègues:

"Mon impression globale est que pour un lecteur (pas un contributeur) qui recherche un terme pour le mettre dans son Swagger, il y a un peu trop de sheets et on s’y perd:

• Il y a celles qui sont directement utiles pour trouver une terme comme par exemple « Standard » et puis peut-être « Vocabulary Adoption » qui donne une liste de tous les termes, standards et encore draft
• Il y en avec des listes de codes
• Il y a des sheets de « travail » (ex VocabularyNL)

Donc, il faudrait peut-être voir les Use Cases. J’en vois au moins 2 :

• Les personnes qui consultent et cherche un terme
• Les personnes qui mettent à jour Pour les personnes qui consultent, on pourrait ne garder que certains sheets et mettre les autres (de travail, liste des codes ..) en « hidden ». Ceux qui mettent à jour (à voir combien) devraient savoir qu’il y a des sheets en hidden.

Je n’ai pas bien compris non plus la partie Datamodels : il y a des termes qui sont composés d’autres termes ? Mais ce n’est pas le plus important je suppose, sauf si on veut vraiment créer des compositions/ Hiérarchies de termes, ce qui n’est pas l’ambition je suppose (ex Address est composée de Street, ..)"

[pvdbosch]

@smals-vea , OK with your final text. I think then that the text sufficiently explains which sheets are only useful for people that consult and search for terms. The tabs meant for editing are only used by WG members (actually Marc only), so I don't think we need to explain them further in the text.

The VocabularyAdoption sheet is also not needed I think for readers; it determines if an entry is presented in the "Standard" and "Draft" sheets.

We could maybe move the DataModels sheet just after the "Draft" one so useful sheets for readers are grouped. This sheet lists relations between terms. I believe the terms used come from RDF and SKOS standards:

• x "domain" y => x is a property of y
• x "range" y => values of property x are of type y
• x "subClassOf" y => class x is a specialization of y
• hasConcept and valueInScheme => not sure what these are? (related to comment https://github.com/belgif/fedvoc/issues/2#issuecomment-891810504)

[smals-vea]

Decisions workgroup on 29/10/2021:

• only the following sheets will be published: intro, standard, draft, datamodel, gov.institutions
• the sheet datamodel will be simplified (only the triples will be kept)
• the intro sheet will be updated with the text proposed below; the same info will be published on github as well

"When to use? The Federal Vocabularies (FedVoc) describe semantics in domains commonly used by Belgian government institutions. You can use them • during business analysis, when designing the data model of an application or • when authoring specifications of an API or webservice (OpenAPI, WSDL/XSD, ...).

If you can't find a concept that's commonly used by Belgian government institutions, you may open an issue to request the concept to be added.

How to use? How to read the FedVoc Excel file: • In the "Standard" sheet, you find the vocabulary entries accepted by the Federal government as standard vocabulary. o The column ‘Ontology’ gives the different domains covered by the vocabulary. To find entries more easily, you can filter on ‘Ontology’ or do a full search (Ctrl+F). o The column ‘Name’ provides a short name of the vocabulary entry. It should be used as the basis of technical names for the entry, for instance when the item is used in a REST APIs. o The columns ‘LabelNL’ and ‘LabelFR’ provide translations of this ‘Name’. o The columns ‘Definition’ (DefinitionNL/DefinitionFR) specify a, preferably concise, definition of the entry o The columns ‘Comment’ (CommentNL/CommentFR) may provide additional information o The column ‘inSwagger’ indicates if the entry has a corresponding OpenAPI data type • In the "Draft" sheet, you find the vocabulary entries that are still a work in progress. • The “Government institutions” sheet provides the common names for Belgian Government institutions (code = abbreviation, name = full name, status = Draft/Standard) • More advanced, the "Datamodels" sheet shows the relationships between vocabulary entries. It can be read as: entry ‘SubjectName’ has a relation of type ‘predicate’ with entry ‘ObjectName’ For instance: ‘houseNumber’ ‘domain’ ‘BelgianAddress’ means that instances with the property ‘houseNumber’ are of type ‘BelgianAddress’.

@pvdbosch @MarcBruyland , are you agree with this final text?

[pvdbosch]

@smals-vea, @MarcBruyland, it could be useful to add some explanation on the different types of relationships in the Datamodels sheet (range, subClassOf, ...) but we didn't get around to discuss some remaining questions about the meaning of some of them (hasConcept, valueInScheme, ...). So we could wait to publish it until these are resolved, or publish the text now and update it later.

[smals-vea]

@MarcBruyland @pvdbosch here you find a proposition for the presentation of the "Intro" tab FedVoc-HowTo-20211105.xlsx

[MarcBruyland]

The intro sheet has been updated.

[pvdbosch]

@MarcBruyland , the Intro sheet still explains the removed Vocabulary* sheets. Shouldn't these be removed from the Intro sheet?