BelgIF OpenAPI common data types

Overzicht

BelgIF-OpenAPI, een set libraries van gemeenschappelijke data types georganiseerd per domein, om een REST API te beschrijven en aldus te hergebruiken in OpenAPI (Swagger)-specificaties

U ontwikkelt een REST-service met identificatiegegevens van de sociale zekerheid (INSZ, ondernemingsnummer, enz.), datums, bedragen, landcodes, gewesten of gemeenten, enz.? Verwijs dan eenvoudigweg naar de BelgIF OpenAPI-schemas in uw OpenAPI-document.

Functionele beschrijving

Een werkgroep, bestaande uit functionelen van FOD BOSA, eHealth, KSZ, FOD Financiën en Smals, heeft de meest gangbare bedrijfsontologieën (Person, Organization, Location, Temporal, Generic...) gestandaardiseerd.

Deze samenwerking resulteerde in

• enerzijds, de publicatie van een terminologielijst van klassen en eigenschappen, met hun URI's, die door de federale overheid als standaardterminologie wordt aanvaard (Belgif vocabularies). Deze terminologie is afkomstig uit drie bronnen: federale overheidsdiensten, Vlaanderen en EU-standaarden. Elk element van de lijst heeft een numerieke identificator (zonder betekenis), een naam (in het Engels, camelCase) en een definitie
• anderzijds, libraries van gemeenschappelijke data types (Belgif OpenAPI schemas) in overeenstemming met de Belgif vocabularies en de Belgif REST guidelines

BelgIF-OpenAPI definieert data types in de volgende domeinen:

• organization-identifier
• employment-identifier
• person-identifier
• person
• location
• time
• money
• problem
• common (common technical data types)

Alle types zijn beschikbaar in de OpenAPI 2.0 (Swagger) en OpenAPI 3.0 formaten.

Er kan vanuit andere OpenAPI-documenten naar de data types worden verwezen:

   “$ref”: “./belgif/person/identifier/v1/person-identifier-v1.yaml#/components/schemas/Ssin”

Technische beschrijving

Veelgebruikte OpenAPI-2.0 en 3.0-gegevenstypes worden onderhouden in de belgif openapi-* GitHub repositories, georganiseerd per domein. Typen met een bèta-status bevinden zich in de broncode, maar maken geen deel uit van de vrijgegeven artefacten. Apache Maven-gebruikers kunnen ze ook downloaden van Maven Central.

Doelpubliek

De libraries BelgIF-OpenAPI common data types kunnen gebruikt worden door iedereen die een REST API ontwikkelt, waarbij de interoperabiliteit tussen alle gebruikte API's wordt verbeterd.

Als u wenst bij te dragen door opmerkingen te formuleren over de standaarden, ze mee vorm te geven of er intern/extern over te communiceren, dan kan u een issue openen op het geschikte project (belgif-openapi, FedVoc, REST guide), of een mail sturen naar fsp@gcloud.belgium.be.

Integratievoorwaarden

De libraries BelgIF-OpenAPI common data types zijn als open source gepubliceerd onder de licentie 2.0 van Apache en gratis te downloaden op GitHub of als Maven-artifacts op Maven Central.

Documentatie

• Federal Service Platform - GCloud service
• Federal vocabulary standaarden
• REST Guidelines
• Bronnen van de REST Guidelines
• Herbruikbare OpenAPI-schema's
• Laat een issue (= opmerking, suggestie, vraag) op de geschikte GitHub belgif-openapi
• Presentatie Federal Data & REST Standardization op YouTube
• Europese standaarden - Kernwoordenlijst
• Interfederale standaarden van het ICEG - review
• Interfederale standaarden van het ICEG - thematic
• Regionale standaarden
• Presentatie (slides) Federal Data & REST Standardization

Contact

Contact: ReuseOperational@smals.be