belgif/thematic

ICEG: Thematic Working Groups

Thematic Working Groups

The group of experts working in a thematic working group has knowledge of existing data models and implementations and is responsible for the development of the domain model.

If you have any comments on specifications, please open an issue from here.

The exercise that is currently ongoing is the exercise around ("Hydrants").

Link to the ICEG review group where you can find the description of the process that is followed to create a standard: https://github.com/belgif/review

Standards overview page: https://github.com/belgif/review/tree/master/OverviewStandards

thematic's Issues

Properties should start with a lowercase character

In some cases properties are mentioned in the textual description starting with a capital instead of with lowercase:
Channel.Description, Evidence.Language, Evidence.Country

What exactly is a "locator" ?

It is not entirely clear, when reading the definitions for "locator designator" and "locator name" - both properties of Address - what is meant by "locator".
Both definitions refer to "locator", but "locator" itself is not defined.
Therefore the definitions of "locator designator" and "locator name" are fuzzy themselves.

Thematic on BEST ?

After finalizing the thematic on URIs, I think it would be a good idea to set up a thematic on BEST addresses.

An example of 3 BEST address identifiers coming from the 3 regions:
"https://data.vlaanderen.be/id/adres/5480782/"
"geodata.wallonie.be/id/Address/1376555/2018-09-17T22:04:09Z"
"BE.BRUSSELS.BRIC.ADM.ADDR/1581470/1"

There is also a need to standardize the URI's for classes and properties of the BEST datamodel.

Service naming convention

(I might have come up with this one a bit earlier...)

In my career I've encountered two distinct service naming strategies (I might have seen others, but these two stuck with me):

1. verb + a noun, usually describing a product, e.g. "issue driving permit"
2. a noun, usually describing a product/business domain, e.g. "driving permits" + a list of business operations, using the former naming convention, e.g. "issue driving permit", "revoke driving permit", "issue international driving permit", "provide driving permit statistics", "determine validity (of) driving permit"..

From a business (architecture) perspective the second naming strategy has always had my preference. Of course, following this strategy has a non trivial impact on the model itself. OTOH, in many cases distinct business operations (of the same service) can be linked to specific life cycle stages (#46)

Classification of Public Services

During the 3rd webinar, the need of a classification of Public Services have been highlighted by the Working Group.
This issue has been created in order to gather the needs of a classification and avoid creating chaotic classifications which are non-interoperable. Any existing classification of Public Services would also be an interesting input.

Reduce superfluous statements

Remove sentences that do not contribute to the specification

Move fragment part

As it is an important part of the spec, it should not be listed as exception, but be a full part of the spec

Consistent nomenclature for classes and properties

Proposal:
Class: camelcase starting with a capital character
property: camelcase starting with a lowercase character

examples found (not exhaustive) where this is not followed:
class Output:
For this entity the following properties are defined: description, Has Legal Resources, identifier, is output, name, responseTime, type.
proposal: hasLegalResources, isOutput

URI - rule 4.1 : first example is confusing

suppose we have id/waterway/schelde
then we change the name (schelde becomes schelde2)

what are we trying to say in the first example ?

(a) we introduce a new URI id/waterway/schelde2 ?
(b) we keep id/waterway/schelde as URI and we change the name through a property like dcterms:title ?

Relax the 303 requirements

Somewhat dogmatic.

An HTTP 303 redirect may not always redirect to a 'doc', so perhaps a "should" instead of "must" is better.

Use case: as "temporarily" solution when organizations/websites are not using linked data, it might be useful to e.g. provide a service to resolve URIs and redirect to e.g. a page on Drupal website for browsers, and redirect linked data clients to a completely different URI (even on another domain) like a triple store provided by the federal/regional service integrator

And a case for not redirecting in e.g. SKOS thesauri / lists, that should be IMHO a choice and not an obligation, since it creates overhead for very little benefit.
E.g "dumb" and rather static list of languages, not worth the effort of a redirect to just serve a few labels that also do not describe the language...

Actually it should not matter whether or not a redirect takes places, LOD clients should be aware that this could be the case and act accordingly

hasContactPoint relationship is superfluous

In order to minimize the model, the relationship "Public Service -> hasContactPoint -> Public Organisation" isn't necessary and coudl be described through the Channel association.

Alignment between the models Public Organizations and Public Services

PublicOrganization in model Public Services:
(1) the textual definition in this model differs from the one in model "Public Organizations" - pls align
(2) the link with Address should be made via Site - see model "Public Organizations"

OrganizationalUnit - Site - EstablishmentUnit

In fedvoc we use the following definitions:

Id	Name	Definition
220	OrganizationalUnit	An Organization such as a department or support unit which is part of some larger Organization and only has full recognition within the context of that Organization. In particular the unit would not be regarded as a legal entity in its own right.
648	Site	An office or other premise at which the organization is located. Many organizations are spread across multiple sites and many sites will host multiple locations. In most cases a Site will be a physical location. However, we don't exclude the possibility of non-physical sites such as a virtual office with an associated post box and phone reception service. Extensions may provide subclasses to denote particular types of site.
721	EstablishmentUnit	(https://economie.fgov.be/en/themes/enterprises/crossroads-bank-enterprises/registration-crossroads-bank) An establishment unit is any place that is geographically identifiable by an address, where at least one activity of the entity is carried out or from which the activity is carried out. Examples of establishment units are: workshops, shops, sales outlets, offices, directorates, headquarters, agencies and branches.

Questions:
(1) Does the definition for EstablishmentUnit given by CBE correspond with OrganizationalUnit ?
(2) Why is OrganizationalUnit a specialization of Organization ?

Remarks regarding Class Output

(1) the property "isOutput" is mentioned twice in the textual description

(2) the name "isOutput" is unclear - proposal to replace it by "provides" (now it reads like Output -> isOutput -> Evidence ; better: Output -> provides -> Evidence)

Appropriate place for properties: Organization or PublicOrganization ?

ImageObject should be linked to Organization instead of PublicOrganization.

Remove table of symbols

Does not provide additional info

Packages

Some services can be bundled. For example, in Flanders we have a child allowance package (“groeipakket” in Dutch). It consist of different services that can be requested together (not all together, but a certain combination depending on the citizen’s situation). Those different services are:

• Basic benefit for every child
• Day care benefit
• School benefit
• Additional benefit for children that have special needs (eg. Children with a handicap)
• Additional benefit for orphans
• …

Note: the general name known by citizens is “groeipakket”, the bundle of products, not the name of services included in the package.
Does the new model supports such a concept?

URI rule 7: Version in a reference

Can we be more explicit in defining what is a version of a resource ?
Why and when do we need it in a URI ?

Remarks regarding Class Evidence

(1) the definition talks about criterion requirement - pls explain the difference with a normal requirement (shouldn't we add the class Criterion to this model ?)

(2) the relation with Dataset is of type parent-child now; shouldn't we align with the relation between PublicService and Dataset and use a normal relation like "isDescribedAt" also for Evidence ?

Use references instead of word list

Word list mentions terms not in the specification, and terms that are already expanded in the spec itself.

Remarks regarding Class PublicService

PublicService:
(1) pls enhance the definition of the recursive relation "relatedTo" ?
(2) the diagram shows a relation "hasRequirement", while the text mentions "has criterion"

Channel purpose qualification and restrictions

Different channels serve different purposes : information, activation of the service, assistance, appeal, ...

• Each channel could serve several purposes
• each purpose can have one or more preferred channels, and one or more "deprecated" channels (ex. you can introduce you tax declaration in paper but you're not encouraged to do so)

Restrictions in channels could not only be depending on time but also on space (geographical areas)

new title

Suggestion for a new title:

• ICEG-standard for URI’s in data

instead of the current title.

motivation
The scoping to the application area (governments in belgium) is maybe not so relevant. Scoping to the applicable entities (data) and the issuing body is maybe more stable and relevant.

Add numbering to headings

Adding numbering to the headers might make the structure more clear when reading the document

add comply statement in management summary.

The management summary indicates that if URIs are used to create persistent identifiers the rules must be followed.
It does not state the inverse.

proposal
In case persistent identifiers are being created and maintained, then these must be in accordance the the rules expressed in this document.

Remarks regarding Class Channel

(1) the name of the relation "hasInput" is not so clear; why not replace it by a relation between Channel and Evidence e.g. "viaChannel"
(2) likewise ChannelPreference could be simplified by a relation between Channel and Evidence e.g. "preferredViaChannel"
(3) missing property in textual description: identifier
(4) cardinality of the relation with PublicOrganization 0-* instead of 0-1

REST guide vs URI standard

When comparing to the REST guide on https://www.gcloud.belgium.be/rest (sources on https://github.com/belgif/rest-guide), I find two possible conflicts with the ICEG URI standard:

1. Identifier of a resource: URIs are often too long to use in practice, e.g. for displaying or saving to a database. That's why a shorter identifier is often used, e.g. ssin, cbeNumber, ...

For REST APIs, it seems a bit overkill to always refer to the full identifier URI (specified in section on REST in URI standard.

In gcloud/belgif REST guide, we only link to the REST URI of a resource and specify the short identifier, e.g.

GET http://rest-reference.test.paas.socialsecurity.be/REST/demo/v1/companies/1

{
   "self": "/companies/1"
   "owner": {
      "ssin": "12345678901",
      "href": "http://example.org/v1/people/12345678901"
   },
   "website": "https://wwww.mycompany.com"
}

(Example taken from the section Links of the REST guide)

2. Retrieving a representation of a resource with "/doc/{concept}/{reference}":
   this is also the purpose of a REST API.
   When to use which solution?

Replace {concept} by {category}

To avoid confusion with concepts and conceptschemes used in vocabularies, we could opt for using the term "category" instead of "concept".

rule 6 > add recommendation

proposal
It is recommended to use meaningful names for the category.

motivation
Since the category is somehow maintained by the domain owner, and it gives a highlevel indication about the real world object that is referred by the identifier, it makes sense to use meaningful names.

Replace Flemish references

Remove / replaces references that are too specific to the Flemish Region with more generic / ICEG references

input from the testing of Public Organization

dears,

following the testing of the model we received the comments below – could you please share your opinion?

• as the document entity seems odd and unclear, it was suggested to remove it
• startDateOfThisData is unclear. We defined it as "The date on which the Organization-related information was provided." Could you please suggest improvements, if any?
• as multiple titles can apply to a Person, it was suggested to make the Person.title unbounded
• it was suggested to add website as part of the contact point entity
• all address attributes, with the exception of full address, should be made optional
• administrative territorial units is still unclear. Could you please suggest ideas for a better definition? Also, as a public organization may govern multiple ATUs, the cardinality should be unbounded
• values that legal form can take should be enumerated in the usage notes

please note that unless an objection is formulated, we will proceed with the changes.

Classification of the Administrative Territorial Unit (ATU)

During the 3rd webinar, the Working Group has expressed the need of a classification of the ATU.
The editor will start by using classification proposed at EU level (see for example here: https://op.europa.eu/fr/web/eu-vocabularies/concept/-/resource?uri=http://publications.europa.eu/resource/authority/atu/BEL_CGG_DEU).
This issue has been created to gather comments and suggestions by the Working Group.

URI - Exceptions

I don't understand very well paragraph 1 of the Exceptions paragraph .
What are we trying to say here ?
Why is it needed in this URI standard document ?

Alignment between the diagram and the textual description of the datamodel

The diagram is not completely in sync with the textual description of the datamodel.

• Organization misses a number of properties like alternative label, authorizations, company number, deregistration, link to database.
• Post misses a property role.

A full check would be appropriate.

base URI pattern

The base pattern

http(s)://{domain}/{type}/{concept}(/{reference})* 

is not explicitly mentioning the fragment case

http(s)://{domain}/{type}/{concept}(/{reference})*(#{fragment})

motivation
Adding the fragment case would make the /ns case not an exception

proposed resolution
All persistent URIs must be formed according the following pattern:

http(s)://{domain}/{type}/{concept}(/{reference})*(#{fragment})

fragment: a local identifier within a namespace. The usage of fragments is restricted to the case described below.

PublicService.LifecycleStatus code feels too limited

Having solely a LifecycleStatus code for a PublicService seems too limited to describe the complete lifecycle of the service (UC2, 4, 6 )

Maybe we need a separate object to accommodate the lifecycle? A certain state in the lifecycle might be governed by different LegalResources than other states of the same PublicService. A certain state might produce different, intermediate outputs than other states, or than the one produced by the PublicService as a whole.

Examples can be found in long-running processes (taking months, sometimes years to complete) with lots of different participants and stakeholders.

Agent "profile" missing

The current Agent class only describes a specific entity (say Mrs X or Company Y).
In order to address UC1 and let end users "find the information", we need to be able to specify generic profiles of agents : students, SMEs, people with disabilites, butchers, ...
This could be adressed by using dct:AgentClass (http://purl.org/dc/terms/AgentClass)

Proposal: relationship between Output and LegalResource

The formal Output of PublicServices is usually governed by one or more LegalResources.

Examples can be given where the LegalResource(s) which govern(s) a certain PublicService is/are different from the LegalResource(s) which govern(s) the associated Output(s)

Add reserved types / auth

On vocab.belgif.be, /auth is used for taxonomies etc, so perhaps 'auth' could be added to the list of types

Might also be a good idea to add 'reserved' types that are used internationally (e.g. page, resource) to avoid conflicting use of additional types

Rule about characters in reference / concepts / types

Should there be a comment / rule about the allowed characters for references, concepts, types

E.g.

• alphanumeric characters (without accents) + a few additional characters (underscore and hyphen)
• so no spaces, no ':', '/', '?', '&', '#' or other characters that may require encoding or could break stuff

OrganizationalUnit as a recursive relation to Organization

Why don't we put a recursive relation to Organization for OrganisationalUnit (hasOrganizationalUnit/organizationalUnitOf) ?
Similar to hasSubOrganization/subOrganizationOf. Drop the child OrganizationalUnit.
Like it is modeled now, only PublicOrganizations can have departments; all Organizations, public or not, can have departments.
We would then have 3 recursive relations for Organization: hasSubOrganization, hasMember and hasOrganizationalUnit.

In the definition of Public Organization it is stated that any organization can have one or more organizational units. I would propose to change the cardinality into zero or more.

Life Events and Business Events too restrictive

Events should be related to generic target users other than citizens (=life events) and companies (=business events).
This does not address events related to other possibile categories of beneficiaries such as NGOs, public actors, schools, etc.

In the charter, clarify the Dependencies

For clarity reasons/dis-ambiguity, the type of dependency, i.e. the type of relationship to e.g. the ISA Core Public Service AP, should be described explicitly.

... this might lead to an additional chapter in the charter for those entries in the list which are not real dependencies, but simply points of inspiration.

From which side should Public Service be described?

In order to address UC1 and UC4, Public Service should be described from the end user's point of view.
A description from the Public Organisation's point of view is seldom appropriate to address those cases where you need to use simple and everyday language and avoid organisation-specific references and vocabulary.
A minimal approach would be to provide several fields for the title of Public Service, one being user-orientend and one being organisation-oriented.

Interfederal standard - pls remove logo of BOSA

In the documentation of the Public organizations and Public services, a logo of BOSA is put on the specification.
As these are intended to become interfederal standards, the logo of BOSA can be removed.

• HTML as a specification - Public services
• HTML as a specification - Public organization

Review remarks on the Public Organization model

Some review remarks on the Public Organization model.

1. Organisation and organization are used interchangeably in an inconsistent way. We'd propose to use US English as standard (as BCSS does) so please use "organization" everywhere.
2. In the diagram, an agent can be a member of an organization, but organization in itself is a member, so please add the ---|> arrow in the opposite direction
3. Please revise the cardinalities in the relations
   a. I think a PublicOrganization can have multiple multiple suborganizations, units and members.
   b. According to the current model, an agent can be member of multiple organizations, but the inverse should be also true (multiple agents can be member of an organization
4. There are properties with the name “identifier” which have type Text and not Identifier. Even Identifier itself has a property “identifier”, which is very confusing. Maybe rename the entity Identifier to BusinessIdentifier?
5. PublicOrganization has the property “identifier”, but it also has inherited a property with the same name from “agent”. The “identifier” in PublicOrganization points to the entity Identifier, but the description says it is an acronym. Maybe “acronym” can be added as a property to the entity “(Business)Identifier”?
6. Since we are in the scope of Belgian PublicOrganizations, I miss the concept of a “CBENumber” (KBO-nummer/numéro BCE), it should be added somewhere to the model. Note that CBENumbers in itself are no longer unique, this concept has changed 2 years ago where now they are only unique in combination with a point in time.

Cost related to an agent

Cost is always related to the public service itself or a channel. In Flanders we have a lot of examples where we want to relate a cost somehow to the local government who provides the service.

For example:

• Public service: Requesting an international driving licence
• The competent authority is a federal agency
• But an international driving licence can be requested and is issued by local governments. We believe that should be modelled as different participations (eg. Role = ‘distributor’) of agents (local governments) in the same public service (international driving license)

Question/potential issue

• Every local government can define their own cost for delivering an international driving license (within a range defined by the competent authority), but in the model cost is only related to the public service itself, or to a channel. Can ‘cost’ somehow be related to a certain local government?

Service variations

Like in many (retail) webshops some public services in Flanders can have different variations. It can be compared to ordering an iPhone 13 (= product) online, where one can choose between different colours (= variations).
An example in Flanders: by ordering service vouchers, civilians can choose between two variations:

• Service vouchers on paper
• Electronic service vouchers
  What’s the best way to model such things? We are thinking of defining something like a product and subproduct where in this case product=service vouchers, and subproducts are:
• Service vouchers on paper
• Electronic service vouchers

Example of a Public Service with Rules and Requirements

Is it possible to give a clear example ?

Remark regarding Class Rule - FRBR ?

The definition talks about "FRBR expressions" - pls clarify