Keuzes

• 1: 00004 Capabilities NL
• 2: 00003 Werkomgeving voor ontwikkeling
• 3: 00001 Basisstructuur
• 4: 00002 Gebruik van Markdown Decision Records in Git

1 - 00004 Capabilities NL

Context en probleemstelling

Gegeven de context van de DR 00001 Basisstructuur waarin we bepalen dat we met capabilities gaan werken volgens de building blocks van OpenDEI, hoe noemen we de capabilities dan in het Nederlands? Nemen we de OpenDEI building blocks letterlijk over? Geven we nog een andere context aan onze capabilities? (Waarmee ook de vertaling naar het Engels anders wordt?)

Beslissingsfactoren

• Context:
  • Doelstellingen Realisatie Interbestuurlijke Datastrategie (IBDS)
  • Doelstellingen Federatief Datastelsel (FDS)
• Decision Records:
  • DR 00001 Basisstructuur
• OpenDEI:

Overwogen opties

• OpenDEI oorspronkelijk
• OpenDEI letterlijke vertaling
• Mike’s vertaling
• Peter’s vertaling
• Capabilities sessies

Besluit

We kiezen voor een zo kort en eenvoudig mogelijke duiding en daarom nemen we voornamelijk Mike’s vertaling over. Daarbij voegen we wel een zin per capability / woord toe om te zorgen voor een juiste en gedeelde ’lading’ van elke capability.

• Governance
  • Bestuurlijk: Bestuurlijke overeenkomsten en juridische constructen
  • Operationeel: Operationele overeenkomsten en afspraken
  • Beheer: Continuïteit en doorontwikkeling van het stelsel
• Interoperabiliteit
  • Modellen: Data- en informatiemodellen en -formaten
  • Dataservices: API’s voor data uitwisseling
  • Traceerbaarheid: Traceerbaarheid en herleidbaarheid
• Datawaarde
  • Metadata: Metadata in brede zin met beschrijvingen, verwijzingen en meer
  • Verantwoording: Verantwoording van datagebruik
  • Publicatie: Publicatie- en marktplaatsdiensten
• Vertrouwen
  • Identiteit: Identiteitsbeheer
  • Toegang: Toegangscontrole en gebruikscontrole
  • Veiligheid: Vertrouwde uitwisseling

Positieve gevolgen

• …

Negatieve Consequences

• …

Pros en Cons van de oplossingen

OpenDEI oorspronkelijk

• Governance

  Business building blocks are artifacts that regulate the business relationships between all roles.

  • Overarching cooperation agreement

    All data space participants need to agree on certain functional, technical, operational and legal aspects. While some agreements are reusable in a generic or sector-specific way (e. g. rule books), others are use-case specific.

  • Operational (e.g. SLA)

    Operational agreements regulate policies that need to be enforced during data space operation. For example, they comprise terms and conditions dealing with the ever-growing importance of compliance with mandatory regulations like GDPR or the 2nd Payment Services Directive (PSD2) in the finance sector.

  • Continuity model

    The Continuity Model describes the processes for the management of changes, versions, and releases for standards and agreements. This also includes the governance body for decision-making and conflict resolution.

• Interoperability

  Data interoperability, covering aspects such as data exchange APIs, data representation formats, as well as provenance and tracebility

  • Data models and formats

    This building block establishes a common format for data model specifications and representation of data in data exchange payloads. Combined with the Data Exchange APIs building block, this ensures full interoperability among participants

  • Data exchange APIs

    This building block facilitates the sharing and exchange of data (i.e., data provision and data consumption/use) between data space participants. An example of a data interoperability building block providing a common data exchange API is the ‘Context Broker’ of the Connecting Europe Facility (CEF)50, which is recommended by the European Commission for sharing right-time data among multiple organisations.

  • Provenance and traceability

    This building block provides the means for tracing and tracking in the process of data provision and data consumption/use. It thereby provides the basis for a number of important functions, from identification of the lineage of data to audit-proof logging of transactions. It also enables implementation of a wide range of tracking use cases at application level, such as tracking of products or material flows in a supply chain.

• Data value

  Data value creation, covering aspects such as publication of data offerings, discovery of such offerings based on metadata, and data access/usage accounting, which are essential to handle data as an economic asset

  • Metadata and Discovery Protocol

    This building block incorporates publishing and discovery mechanisms for data resources and services, making use of common descriptions of resources, services, and participants. Such descriptions can be both domain-agnostic and domain-specific. They should be enabled by semantic-web technologies and include linked-data principles.

  • Data usage accounting

    This building block provides the basis for accounting access to and/or usage of data by different users. This in turn is supportive of important functions for clearing, payment, and billing (including data-sharing transactions without involvement of data marketplaces).

  • Publication and marketplace services

    To support the offering of data resources and services under defined terms and conditions, marketplaces must be established. This building block supports publication of these offerings, management of processes linked to the creation and monitoring of smart contracts (which clearly describe the rights and obligations for data and service usage), and access to data and services.

• Trust

  Data sovereignty, covering aspects such as identity management, trustworthiness of participants, as well as data access and usage control

  • Identity management

    The IM building block allows identification, authentication, and authorisation of stakeholders operating in a data space. It ensures that organisations, individuals, machines, and other actors are provided with acknowledged identities, and that those identities can be authenticated and verified, including additional information provisioning1, to be used by authorisation mechanisms to enable access and usage control. The IM building block can be implemented on the basis of readily available IM platforms that cover parts of the required functionality. Examples of open-source solutions are the KeyCloak infrastructure, the Apache Syncope IM platform, the open-source IM platform of the Shibboleth Consortium, or the FIWARE IM framework. Integration of the IM building block with the eID building block of the Connecting Europe Facility (CEF)55, supporting electronic identification of users across Europe, would be particularly important. Creation of federated and trusted identities in data spaces can be supported by European regulations such as EIDAS.

  • Access and usage control / policies

    This building block guarantees enforcement of data access and usage policies defined as part of the terms and conditions established when data resources or services are published (see ‘Publication and Services Marketplace’ building block below) or negotiated between providers and consumers. A data provider typically implements data access control mechanisms to prevent misuse of resources, while data usage control mechanisms are typically implemented on the data consumer side to prevent misuse of data. In complex data value chains, both mechanisms are combined by prosumers. Access control and usage control rely on identification and authentication.

  • Trusted exchange

    This building block facilitates trusted data exchange among participants, reassuring participants in a data exchange transaction that other participants really are who they claim to be and that they comply with defined rules/agreements. This can be achieved by organisational measures (e.g. certification or verified credentials) or technical measures (e.g. remote attestation).

OpenDEI letterlijke vertaling

(vertaald mbv Google Translate)

• Bestuur

  Governance capabilities zijn artefacten die de zakelijke relaties tussen alle rollen regelen.

  • Overkoepelend samenwerkingsakkoord

    Alle deelnemers aan de dataspace moeten het eens zijn over bepaalde functionele, technische, operationele en juridische aspecten. Hoewel sommige overeenkomsten op een generieke of sectorspecifieke manier herbruikbaar zijn (bijv. Regelboeken), zijn anderen gebruiksspecifiek.

  • Operationeel (bijv. SLA)

    Operationele overeenkomsten reguleren beleid dat moet worden afgedwongen tijdens de dataspace operatie. Ze omvatten bijvoorbeeld voorwaarden die betrekking hebben op het steeds groter wordende belang van naleving van verplichte voorschriften zoals GDPR of de 2e Payment Services Richtlijn (PSD2) in de financiële sector.

  • Continuïteitsmodel

    Het continuïteitsmodel beschrijft de processen voor het beheer van wijzigingen, versies en releases voor normen en overeenkomsten. Dit omvat ook het bestuursorgaan voor besluitvorming en conflictoplossing.

• Interoperabiliteit

  Gegevensinteroperabiliteit, met betrekking tot aspecten zoals gegevensuitwisseling API’s, formaten voor gegevensrepresentatie, evenals herkomst en traceerbaarheid

  • Datamodellen en formaten

    Deze bouwsteen stelt een gemeenschappelijk formaat vast voor specificaties voor gegevensmodel en weergave van gegevens in de payloads van gegevensuitwisseling. Gecombineerd met de Building Builder van de Data Exchange API’s, zorgt dit voor volledige interoperabiliteit bij deelnemers

  • API’s voor gegevensuitwisseling

    Deze bouwsteen vergemakkelijkt het delen en uitwisselen van gegevens (d.w.z. gegevensvoorziening en dataconsumptie/gebruik) tussen gegevensruimte -deelnemers. Een voorbeeld van een bouwsteen voor gegevensinteroperabiliteit die een gemeenschappelijke gegevensuitwisseling API biedt, is de ‘contextmakelaar’ van de Connecting Europe Facility (CEF), die door de Europese Commissie wordt aanbevolen voor het delen van juiste gegevens over meerdere organisaties.

  • Herkomst en traceerbaarheid

    Deze bouwsteen biedt de middelen voor tracering en tracking in het proces van gegevensvoorziening en gegevensverbruik/gebruik. Het biedt daardoor de basis voor een aantal belangrijke functies, van identificatie van de lijn van gegevens tot auditbestendige logboekregistratie van transacties. Het maakt ook de implementatie van een breed scala aan tracking -use cases op applicatieniveau mogelijk, zoals het volgen van producten of materiaalstromen in een supply chain.

• Gegevenswaarde

  Gegevenswaardecreatie, met betrekking tot aspecten zoals publicatie van gegevensaanbiedingen, ontdekking van dergelijke aanbiedingen op basis van metadata en gegevenstoegang/gebruiksboekhouding, die essentieel zijn om gegevens als een economisch asset te verwerken

  • Metagegevens en ontdekkingsprotocol

    Deze bouwsteen omvat publicatie- en ontdekkingsmechanismen voor gegevensbronnen en -services, waarbij gebruik wordt gemaakt van gemeenschappelijke beschrijvingen van bronnen, diensten en deelnemers. Dergelijke beschrijvingen kunnen zowel domein-agnostisch als domeinspecifiek zijn. Ze moeten worden ingeschakeld door semantische-WEB-technologieën en bevatten principes met gekoppelde gegevens.

  • Accounting van gegevensgebruik

    Deze bouwsteen biedt de basis voor boekhoudkundige toegang tot en/of gebruik van gegevens door verschillende gebruikers. Dit ondersteunt op zijn beurt belangrijke functies voor het wissen, betalen en factureren (inclusief transacties voor het delen van gegevens zonder betrokkenheid van gegevensmarktplaatsen).

  • Publicatie- en marktplaatsdiensten

    Ter ondersteuning van het aanbod van gegevensbronnen en -diensten onder gedefinieerde algemene voorwaarden, moeten marktplaatsen worden vastgesteld. Deze bouwsteen ondersteunt de publicatie van deze aanbiedingen, het beheer van processen die gekoppeld zijn aan het maken en monitoren van slimme contracten (die duidelijk de rechten en verplichtingen voor gegevens en servicegebruik beschrijven) en toegang tot gegevens en diensten.

• Vertrouwen

  Gegevenssoevereiniteit, met betrekking tot aspecten zoals identiteitsbeheer, betrouwbaarheid van deelnemers, evenals gegevenstoegang en gebruikscontrole

  • Identiteitsbeheer

    De IM -bouwsteen maakt identificatie, authenticatie en autorisatie mogelijk van belanghebbenden die in een gegevensruimte actief zijn. Het zorgt ervoor dat organisaties, individuen, machines en andere actoren worden voorzien van erkende identiteiten, en dat die identiteiten kunnen worden geauthenticeerd en geverifieerd, inclusief aanvullende informatievoorziening, kunnen worden gebruikt door autorisatiemechanismen om toegang en gebruikscontrole mogelijk te maken. De IM -bouwsteen kan worden geïmplementeerd op basis van direct beschikbare IM-platformen die delen van de vereiste functionaliteit behandelen. Voorbeelden van open-source oplossingen zijn de Keycloak-infrastructuur, het Apache Syncope IM-platform, het open-source IM-platform van het Shibboleth Consortium of het Fiware IM-framework. Integratie van de IM -bouwsteen met de eID-bouwsteen van de Connecting Europe Facility (CEF), ter ondersteuning van elektronische identificatie van gebruikers in heel Europa, zou met name belangrijk zijn. Creatie van federale en vertrouwde identiteiten in gegevensruimtes kan worden ondersteund door Europese voorschriften zoals EIDAS.

  • Toegangs- en gebruikscontrole / beleid

    Deze bouwsteen garandeert de handhaving van gegevenstoegang en gebruiksbeleid gedefinieerd als onderdeel van de algemene voorwaarden die zijn vastgesteld wanneer gegevensbronnen of -diensten worden gepubliceerd (zie hieronder ‘Publication and Services Marketplace’ bouwsteen) of onderhandeld tussen providers en consumenten. Een gegevensaanbieder implementeert doorgaans mechanismen voor gegevenstoegang om misbruik van middelen te voorkomen, terwijl het besturingsmechanismen voor gegevensgebruik meestal aan de gegevens van de gegevens van de gegevens worden geïmplementeerd om misbruik van gegevens te voorkomen. In complexe gegevenswaardeketens worden beide mechanismen gecombineerd door prosumeurs. Toegangscontrole en gebruikscontrole vertrouwen op identificatie en authenticatie.

  • Vertrouwde uitwisseling

    Deze bouwsteen faciliteert de vertrouwde gegevensuitwisseling onder deelnemers, waardoor deelnemers in een gegevensuitwisselingstransactie geruststellen die andere deelnemers echt zijn wie zij beweren te zijn en dat zij voldoen aan gedefinieerde regels/overeenkomsten. Dit kan worden bereikt door organisatorische maatregelen (bijv. Certificering of geverifieerde referenties) of technische maatregelen (bijv. Attesting op afstand).

Mike’s vertaling

• Governance
  • Bestuurlijk
  • Operationeel
  • Organisatie
• Interoperabiliteit
  • Modellen
  • Interoperabiliteit
  • Traceerbaarheid
• Data met waarde
  • Beschrijving
  • Verantwoording
  • Diensten
• Vertrouwen
  • Identiteit
  • Toegang
  • Veiligheid

FDS overwegingen:

• Enkel één woord is wel erg prettig!
• Enkel één woord geeft weinig ’lading’ en verdient wel duidelijke beschrijvingen van wat er dan wel en niet onder valt. Hier ligt het gevaar dat ‘men’ alleen de woorden als uitgangspunt neemt en verschillende lading daar aan geeft. Hoewel een enkel woord eenvoudig lijkt en duidelijkheid lijkt te geven, zou het ook juist tot verwarring kunnen leiden. Dat is slechts een risico zo lang de woorden nog niet goed geladen zijn. Zodra dat wel het geval is, draagt het zeker bij aan een eenvoudig en duidelijk model!
• Interoperabiliteit > Interoperabiliteit … is niet heel duidelijk. Zou de capability niet ‘iets met API’s’ moeten bevatten … alléén ‘API’s’?
• ‘Data met waarde’ is anders dan ‘Data value’. Dat beschrijft meer de waarde van data. De capabilities verwijzen meer naar de bekwaamheden die de data waarde gaan geven en/of duiden. Waarom niet directer vertalen met ‘Data waarde’?
• Data met waarde > Beschrijving verwijst vooral naar de metadata. Is ‘Metadata’ beter dan ‘Beschrijving’?
• Data met waarde > Diensten gaat vooral over de publicatie en het gebruik van die publicatie in een marktplaats, terwijl diensten zelf ook kan duiden op de API’s. Is ‘Publicatie’ beter?

Peter’s vertaling

• Governance
  • Standaard generieke samenwerkovereenkomst
  • Standaard operationele overeenkomst (SLA)
  • Regie op en continuïteit van het stelsel
• Interoperabiliteit
  • Datamodellen en -formaten
  • Datadeel services (API’s)
  • Herkomst en traceerbaarheid
• Waarde van data
  • Protocol voor metadata en zoeken
  • Verantwoording data gebruik
  • Services voor datapublicatie en datamarktplaats
• Vertrouwen
  • Identiteit management
  • Beleid toegang en gebruik
  • Vertrouwd data delen

Capabilities sessies

• Governance
  • [nog consolideren]
• Interoperabiliteit
  • Datamodellen en formaten
  • Data uitwisseling en APIs
  • Herleidbaarheid en traceerbaarheid
  • [extra] Ontwikkelen en beheren meta-data-standaarden
• Data waarde
  • Metadata en discovery
  • Verantwoording datagebruik
  • Publicatie en marktplaats-services
• Vertrouwen
  • Identiteitsbeheer
  • Toegangs- en gebruikerscontrole/beleid
  • Vertrouwd uitwisselen

FDS overwegingen:

Tijdens de capabilities sessies zijn we steeds afgeweken van de OpenDEI building blocks. Dat heeft geleid tot goede discussies en uitwerking van diverse (bijv.) rollen van het federatief datastelsel. Echter … wijkt dat dusdanig af dat het niet meer herkenbaar is naar het oorspronkelijke model van OpenDEI. Aangezien we in DR 00001 Basisstructuur hebben besloten om juist wél dicht bij het OpenDEI model te blijven, moeten we herzien wat we tijdens de sessies bedacht hebben.

Vergelijkingstabel

Links

• DR 00001 Basisstructuur
• doc Raamwerk (voor ontwikkeling in samenwerking)
• doc Capabilities

2 - 00003 Werkomgeving voor ontwikkeling

Context en probleemstelling

Gegeven de context van de Realisatie van de Interbestuurlijke Datastrategie en de aanpak daarvan, dient het programma invulling te geven aan het aanjagen van de ontwikkelingen, verbinding en samenwerking tot stand te brengen en te bevorderen en partijen over ketens heen bij elkaar te brengen. Dat is nogal een ambitie.

Wat is hiervoor nodig? Wat is hier een goede invulling van? Welke voorzieningen dienen er te zijn om dit allemaal tot stand te brengen?

Beslissingsfactoren

• Wettelijk kader:
  • […]
• Context:
  • Doelstellingen Regie op Gegevens
  • Doelstellingen Realisatie Interbestuurlijke Datastrategie (IBDS)
  • Doelstellingen Federatief Datastelsel (FDS)
  • Doelstellingen Common Ground
  • Doelstellingen Data bij de Bron
  • Doelstellingen Digilab
• Decision Records:
  • DR 00001 Basisstructuur
• OpenDEI:
  • Governance
    • Overkoepelende samenwerkingsovereenkomsten

Overwogen opties

• Microsoft 365
• Google Workspace
• The Good Cloud
• Pleio
• Markdown met Git
• GitHub
• GitLab
• NORA Wiki
• Static website

Besluit

In het federatief datastelsel faciliteren wij samenwerking en besluitvorming. Dat is gebaat bij of is zelfs alleen mogelijk door open te werken.

• Wij werken open
• Wij werken community gedreven
• Wij verbinden
• Wij nemen faciliterend initiatief

Om al deze stellingen goed te kunnen ondersteunen, is tooling nodig om samenwerking goed mogelijk te maken. Dat is vooral tooling ter ondersteuning van open communities. Daarom kijken we hiervoor naar de ervaringen van open source werken. Een open source community onderkent vier communicatie vormen / kanalen:

1. Publicatie -> de landingsplaats voor iedereen en formele(re) communicatie van binnen naar buiten en met elkaar
2. Interactie -> Chat & Online video conferencing; korte, vluchtige en toegankelijke communicatie
3. Documenten -> onderwerpen waar samengewerkt wordt in documenten, waar bijdragen voor iedereen geleverd moeten kunnen worden
4. Issue tracking -> vragen, opmerkingen, suggesties, inhoudelijke discussies en vooral de opvolging daarvan

Wij kiezen graag voor best of breed tools, welke dan wél zoveel mogelijk geïntegreerd werken en toegankelijk zijn. Aangezien wij community gedreven zijn en faciliterend initiatief nemen, maken wij de werkomgeving beter, werkend en tot een prettige werkervaring voor zoveel mogelijk mensen. Vanaf het begin zal dat nog niet helemaal zo beschikbaar zijn, maar daar werken we wel actief aan!

Voor Publicatie gebruiken we Pleio én een eigen website:

• realisatieibds.nl is de formele publicatie en communicatie kanaal.
• federatief.datastelsel.nl is de ‘static’ website

Voor de publicatie is het onhandig om twee locaties aan te bieden. Dit is een open punt dat nog opgelost moet worden.

Voor Documenten gebruiken we Markdown met Git en deze beheren we in GitLab. Voor de content van deze website kiezen we voor gitlab.com/datastelsel.nl/federatief/website. Er zullen meer (git) repositories bijkomen en dit is nog open voor contributies.

[nog onder discussie] Voor Chat gebruiken we Mattermost: digilab.overheid.nl/chat/fds. Intern is MS Teams (nog?) veelgebruikt.

Voor Issue tracking hebben we (nog) geen oplossing gekozen.

Positieve gevolgen

• …

Negatieve Consequences

• …

Pros en Cons van de oplossingen

Microsoft 365

// TODO …

Cons:

• Gesloten omgeving
• Gesloten en betaalde tools (Microsoft Office Suite)
• Amerikaanse cloud omgeving
• Microsoft betrokkenheid

Google Workspace

// TODO …

Cons:

• Gesloten omgeving
• Gesloten en betaalde tools (Google Docs)
• Amerikaanse cloud omgeving
• Google betrokkenheid

The Good Cloud

// TODO …

Pros:

• Europese cloud omgeving

Cons:

• Gesloten omgeving
• Gesloten en betaalde tools (Libre Office?)

Pleio

// TODO …

Pros:

• Nederlandse cloud omgeving

Cons:

Markdown met Git

Bij de ontwikkeling van content, het zij op internet, het zij in documenten, is er behoefte aan opmaak. Opmaak in Microsoft Word is specifiek en direct afhankelijk van de tool MS Word. Op internet is de afhankelijkheid naar een tool er niet. Hoogstens van de HTML (+ CSS + JavaScript) standaarden voor visualisatie mogelijkheden.

Om voor de ontwikkeling van content op internet niet afhankelijk te zijn van technische experts die HTML+ kunnen schrijven, wordt er al lang gezocht naar manieren om met ‘pseudo codes’ opmaak aan te geven in platte tekst. Wikitekst, zoals in de NORA Wiki, is daar een voorbeeld van. Het vroegere Wordperfect had daar ook mogelijkheden voor. Voor software documentatie is Markdown de de facto standaard.

Markdown is een vrij eenvoudige specificatie van speciale codes die opmaak betekenis hebben. Door een conversiestap van bron (source) document naar HTML kan een mooie HTML website gepubliceerd worden. Doordat Markdown redelijk gestandaardiseerd is, zijn er vele (😳) tools beschikbaar die een website kunnen genereren. Hier is enorme keuze om een geschikte tool te vinden afhankelijk van de situatie.

Doordat Markdown bestanden platte tekst bestanden zijn, is versiebeheer mbv Git makkelijk, logisch en veel toegepast. Daarom is dit ook een prettige oplossing voor software developers documentatie. Tools als GitHub en GitLab hebben standaard ook ondersteuning voor Markdown incl. presentatie als HTML.

• Goed, omdat Markdown eenvoudige codes gebruikt, zodat ook minder-technische mensen er mee uit de voeten kunnen (zie onze Docs/Markdown)
• Goed, omdat Markdown redelijk gestandaardiseerd is
• Goed, omdat versiebeheer per Markdown bestand zeer mogelijk is mbv Git
• Goed, omdat versiebeheer over een collectie Markdown bestanden ook zeer mogelijk is door de toepassing van Git
• Goed, omdat de brondocumenten in Markdown echt ontkoppeld zijn van de tool voor publicatie in HTML
• Slecht, omdat de brondocumenten op enige afstand kunnen staan door de ontkoppeling met de publicatie tool
• Slecht, omdat het versiebeheer geen onderdeel is van Markdown en extra toegevoegd moet worden. Git is daarvoor zeer geschikt … maar ook zo uitgebreid, dat minder-technische mensen daar moeite mee hebben. Dit verhoogt de barrière voor minder-technische mensen om Markdown (plus Git) te gebruiken
• Vergelijkbaar met Wikitekst, omdat het platte tekst is waarin met codes opmaak wordt geproduceerd

GitHub

// TODO …

Pros:

• Wel primaire oplossing voor de ontwikkeling van open source producten

Cons:

• Zelf geen open source oplossing

GitLab

// TODO …

Pros:

• In de basis zelf een open source oplossing
• GitLab.com is secundaire oplossing voor de ontwikkeling van open source producten
• GitLab is ook zelf te hosten, maar dan is externe user management ons probleem

Cons:

• GitLab is ook zelf te hosten, maar dan is externe user management ons probleem

NORA Wiki

Een wiki is een manier om online content te publiceren én tegelijk dat te beheren met meerdere mensen. Het biedt de mogelijkheid om door content te bladeren, te zoeken en links tussen pagina’s te maken. Een ‘What You See Is What You Get’ (WYSIWYG) editor ondersteunt niet-technische gebruikers. Dit is waar Wikipedia mee ontstaan en groot geworden is.

De Nederlandse Overheids Referentie Architectuur, NORA, maakt gebruik van dezelfde technologie als Wikipedia: Mediawiki. Het doel is vergelijkbaar als met Wikipedia, namelijk dat het beheer van content eenvoudig is en door iedereen gedaan kan worden.

• Goed, omdat gepubliceerde content en het wijzigen van content dicht bij elkaar staan en te vinden zijn
• Goed, omdat niet-technische gebruikers gemakkelijk kunnen bijdragen (na aanmaken van een account, dat zelfstandig gedaan kan worden)
• Slecht, omdat versiebeheer per pagina niet zo duidelijk is
• Slecht, omdat versiebeheer van meerdere en samenhangende pagina’s eigenlijk niet goed ondersteund worden (er zijn wel wat mogelijkheden … maar allemaal suboptimaal)
• Vergelijkbaar met Markdown, omdat het onderliggende formaat waarmee een wiki werkt, ondanks de WYSIWYG editor, gebaseerd is op ‘wikitekst’. Dat is de facto standaard van Mediawiki en lijkt op Markdown. Wikitekst is minder gestandaardiseerd dan Markdown en alleen (in deze vorm) ondersteund door Mediawiki.

Static website

Voor het beschikbaar maken van de static website (zie ook Markdown met Git) is een (host)naam, een URL nodig. Wat zou een goede en toekomstbestendige naam zijn? De volgende alternatieven zijn overwogen.

• datastelsel.nl
  • het doel waar we naartoe werken, het Nederlandse datastelsel (💪)
  • doel klopt, maar daar zijn we nog niet
  • branding is het nog te vroeg voor …
• ontwikkeling.datastelsel.nl
  • de ontwikkeling van het Nederlandse Datastelsel
  • Realisatie IBDS zou dan te vinden moeten zijn onder datastrategie.datastelsel.nl?
  • past bij het einddoel
  • ontwikkeling is geen herkenbare brand op dit moment
• federatief.datastelsel.nl <- keuze
  • de ontwikkeling van het Nederlandse federatief datastelsel
  • Realisatie IBDS zou dan te vinden kunnen zijn onder datastrategie.datastelsel.nl?
  • huidige branding blijft gelijk !!
• ontwikkelingfds.nl
  • de ontwikkeling van FDS, het federatief datastelsel
  • helemaal losstaande URL … kan zowel positief als negatief gezien worden
• overheidsdatastelsel.nl
  • het doel waar we (dan) naartoe werken, is het Nederlandse Overheids datastelsel … maar dat is niet zo. Ja, het is / begint bij overheid, maar het einddoel is weldegelijk overstijgend cq te kunnen verbinden met andere stelsels
• ontwikkeling.overheidsdatastelsel.nl
  • combinatie van bovenstaande … met combinatie van die afwegingen
• datastelsel.overheid.nl
  • het doel waar we naartoe werken, het Nederlandse Overheids datastelsel
  • onder overheid.nl is goed
  • maar het einddoel is niet alleen overheid …
• ontwikkeling.datastelsel.overheid.nl
  • bovenstaande, maar dan de ontwikkeling daarvan datastelsel
• federatiefdatastelsel.realisatieibds.nl
  • FDS als onderdeel van Realisatie IBDS (onder eigen URL)
  • Realisatie IBDS zou dan te vinden moeten zijn onder realisatieibds.nl
  • Tja … wel heel andere en losstaande richting …

Links

• doc Strategie van samenwerken
• doc Raamwerk (voor ontwikkeling in samenwerking)
• doc Werkomgeving

3 - 00001 Basisstructuur

Context en probleemstelling

Als Nederlands federatief datastelsel hebben we de Strategie van samenwerken. Dat betekent dat we verbinding nodig hebben en moeten ondersteunen. Het helpt als daar een herkenbare en eenvoudige structuur aan ten grondslag ligt. Dit wordt ook wel ‘structure follow strategy’ genoemd. Er zijn echter vele architecturen, architectuur frameworks en … fêtes rondom architecturen. Wat is wijs? Wat is herkenbaar? Wat zou grote verschillen kunnen overbruggen? En hoe blijven we buiten of ontwijken we ‘architectuur fêtes’?

Beslissingsfactoren

• Omliggende architecturen
  • NORA
  • Common Ground Architectuur
• Context:
  • Europese Unie en ontwikkelingen
  • Doelstellingen Regie op Gegevens
  • Doelstellingen Realisatie Interbestuurlijke Datastrategie (IBDS)
  • Doelstellingen Federatief Datastelsel (FDS)
  • Doelstellingen Common Ground
  • Doelstellingen Data bij de Bron
  • Doelstellingen Digilab
• Uitgangspunten:
  • Europa volgen
  • Capabilities
  • Architectuur Building Blocks
  • NORA 5 lagen
  • Archimate lagen
  • Basis voor samenwerking

Overwogen opties

• Design Principles for Data Spaces by OpenDEI
• NORA Vijflaagsmodel
• Archimate

Besluit

We kiezen voor een Capabilities model gebaseerd op het OpenDEI building blocks model gecombineerd met een vijf lagen model gebaseerd op de NORA vijf lagen model en Archimate. We kiezen voor een Nederlandse vertaling en eigen bewoordingen. Tegelijk zorgen we ervoor dat de verbinding met de oorspronkelijke modellen heel zichtbaar en herkenbaar blijft.

Het raamwerk / de basisstructuur wordt in het raamwerk voor ontwikkeling in samenwerking verder uitgebreid beschreven.

De basisstructuur is de ‘kapstok’ om alle ontwikkelingen en aspecten van het federatief datastelsel aan ‘op te hangen’. Het biedt een ’landkaart’ om aan te geven waar een bepaalde functionaliteit, functie, techniek zich bevindt. De verbinding naar omliggende zaken is als volgt te zien:

Positieve gevolgen

• De OpenDEI building blocks, bij ons capabilities genoemd, geven herkenbaarheid en verbinding naar Europese ontwikkelingen en initiatieven.
• De capabilities bieden ook verbinding naar capabilities in andere Nederlandse initiatieven, aangezien ook zij ‘capabilities’ gebruiken. Hoe de verschillende capabilities zich tot elkaar verhouden kan nog wel verschillen en/of uitzoekwerk betekenen. Wij denken dat de OpenDEI building blocks bruikbare capabilities zijn.
• De vijf lagen van ons model zijn duidelijk te verbinden met de vijf lagen van NORA en Archimate. Daarmee worden veel verbindingen duidelijk en eenvoudig.
• Verbindingen zijn met deze basisstructuur eenvoudig, duidelijk en herkenbaar. Dat geeft de mogelijkheid om met vele initiatieven om het federatief datastelsel heen te verbinden. Dat sluit aan bij onze Strategie van samenwerken

Negatieve Consequences

• We introduceren een nieuw raamwerk (framework) en dat zal daarom op moment van introductie nergens helemaal mee aansluiten. Dit vergt tijd en werk om verbindingen te maken en per verbinding te onderzoeken en aan te geven hoe relaties precies gemaakt kunnen worden. (We denken wel dat ons model zo herkenbaar en eenvoudig is, dat dit niet echt tot problemen zal leiden)

Pros en Cons van de oplossingen

Design Principles for Data Spaces by OpenDEI

De Position Paper: Design Principles for Data Spaces by the OpenDEI Workforce heeft al veel voorwerk en uitzoekwerk gedaan over datastelsels, oftewel Data Spaces. Dit raamwerk is dan ook al veel gebruikt voor Europees gerelateerde ontwikkelingen en initiatieven. Ook de samenwerking en vergelijk met IDSA en GAIA-X worden hierin benoemd.

Voor het federatief datastelsel is de vergelijking door Geonovum van groot belang en ook hier worden de ‘building blocks’ van OpenDEI gebruikt. In de Geonovum Verkenning Dataspaces wordt het OpenDEI model als ‘conceptueel model’ gebruikt voor de ‘quick-scan (zie H2.4).

Voor de vergelijking van het federatief datastelsel helpt dit model vooral in de verbinding naar Europa en Europese ontwikkelingen en initiatieven. Aangezien dit een belangrijk gebied is voor het federatief datastelsel, is ook dit moment belangrijk.

NORA Vijflaagsmodel

In de NORA, de Nederlandse Overheid Referentie Architectuur, wordt het Vijflaagsmodel beschreven. Dit is de basis van veel overheidsarchitecturen en daarom erg herkenbaar. Tegelijk is het afwijkend van Archimate, welke ook veel gebruikt wordt (ook buiten de overheid).

Archimate

Archimate is een architectuur taal. Een visuele taal met een rijke set aan gegronde en doordachte mogelijkheden. Dit is een veelgebruikte basis voor architecturen, ook als deze ’niet-Archimate’ heten. De rijkheid van Archimate en volledigheid biedt veel mogelijkheden. Tegelijk is dat wellicht de zwakte; er is zoveel mogelijk … dat overzicht verloren gaat aan eigen succes.

Om vanuit het federatief datastelsel wel gemakkelijk verbinding te maken vanuit architecturen die (direct of indirect) gebaseerd zijn op Archimate, hebben wij in de basisstructuur daar duidelijk verbinding en overeenkomst gemaakt in de lagen.

Capabilities

Veel architecturen kennen het woord ‘capability’, ‘bekwaamheid’, iets dat ‘het moet kunnen’. Dit komt voor in zowel TOGAF als in de NORA.

Daarnaast wordt bouwblok (building block) veel gebruikt in architecturen. Soms zijn het synoniemen, soms duidt het op verschillende zaken. Dit is (helaas) niet altijd duidelijk. Dat komt ook doordat het in verschillende architectuur frameworks verschillend gebruikt wordt.

In de basisstructuur / raamwork wordt ‘capability’ vooral op de bovenste laag van het vijflagen model gezien. Dit komt overeen met hoe capabilities in Archimate gebruikt worden.

Links

• doc Strategie van samenwerken
• doc Raamwerk (voor ontwikkeling in samenwerking)
• doc Werkomgeving
• DR 00003 Werkomgeving voor ontwikkeling

4 - 00002 Gebruik van Markdown Decision Records in Git

Context en probleemstelling

In het algemeen zijn er veel termen, woorden, begrippen, principes, concepten die niet eenduidig vastliggen. Om discussies te kunnen beslechten, vast te leggen en (ook) later op terug te kunnen komen en naar te verwijzen, is een methode nodig om dat vast te leggen. Wat is een goede methode? Hoe en waar leggen we dat dan vast?

Overwogen opties

• NORA Wiki
• Markdown in enige vorm
• MADR 2.1.2 with Log4brains patch
• MADR 2.1.2 – The original Markdown Architectural Decision Records
• Michael Nygard&rsquo;s template – The first incarnation of the term “ADR”
• Sustainable Architectural Decisions – The Y-Statements
• Other templates listed at https://github.com/joelparkerhenderson/architecture_decision_record
• Formless – No conventions for file format and structure

Besluit

We maken gebruik van Decision Records volgens onze eigen, in het Nederlands vertaalde template decision-record.md. We hanteren daarbij het gebruik van Markdown aangezien dat (redelijk) mensvriendelijk is en tegelijkertijd machine leesbaar. We maken daarbij gebruik van Git versiebeheer, aangezien dit subliem is en de facto standaard.

Decision records hebben een uniek, oplopend nummer. De volgorde is niet van belang. Het is een nummer uit alleen cijfers en uit vijf karakters: 00000

Decision records doorlopen het door Log4brains bedachte proces:

Decision records hebben de volgende indeling, naar aanleiding en geïnspireerd van de overige overwogen opties.

• Context en probleemstelling
• Beslissingsfactoren
• Overwogen opties
• Besluit
  • Positieve gevolgen
  • Negatieve Consequences
• Pros en Cons van de oplossingen
  • Optie 1
  • Optie 2
• Links (naar andere decision records)

Deze template is als Markdown template beschikbaar in de repository: archetypes/decision-record.md

Het gebruik van Markdown betekent dat de template er ongeveer zo uit zal zien:

## Context en probleemstelling

## Beslissingsfactoren

## Overwogen opties

## Besluit

### Positieve gevolgen

### Negatieve Consequences

## Pros en Cons van de oplossingen

### Optie 1

### Optie 2

## Links

Positieve gevolgen

• Impliciete aannames zouden expliciet gemaakt moeten zijn Ontwerp documentatie is belangrijk voor mensen om besluiten later te kunnen begrijpen. Zie ook A rational design process: How and why to fake it.
• Markdown is klein, compact en eenvoudig en tegelijk rijk aan mogelijkheden
• Bovenstaande structuur is eenvoudig, krachtig en faciliteert gebruik en onderhoud
• Oorspronkelijke basis hiervan, namelijk Markdown Architecture Decision Records (MADR), is een actieve en sterk groeiende methode van vastlegging van besluiten
• Het proces (workflow) is eenvoudig en duidelijk
• Een nieuw decision record heeft status draft, wat de mogelijkheid biedt voor anderen om suggesties te doen en bijdragen te leveren
• Markdown decision records hebben het bestandsformaat NNNNN-decision-naam
• Decision records zijn met hun nummer te refereren … hoewel met naam meer context geeft (en dus beter is / voorkeur heeft)

Pros en Cons van de oplossingen

NORA Wiki

Een wiki is een manier om online content te publiceren én tegelijk dat te beheren met meerdere mensen. Het biedt de mogelijkheid om door content te bladeren, te zoeken en links tussen pagina’s te maken. Een ‘What You See Is What You Get’ (WYSIWYG) editor ondersteunt niet-technische gebruikers. Dit is waar Wikipedia mee ontstaan en groot geworden is.

De Nederlandse Overheids Referentie Architectuur, NORA, maakt gebruik van dezelfde technologie als Wikipedia: Mediawiki. Het doel is vergelijkbaar als met Wikipedia, namelijk dat het beheer van content eenvoudig is en door iedereen gedaan kan worden.

• Goed, omdat gepubliceerde content en het wijzigen van content dicht bij elkaar staan en te vinden zijn
• Goed, omdat niet-technische gebruikers gemakkelijk kunnen bijdragen (na aanmaken van een account, dat zelfstandig gedaan kan worden)
• Slecht, omdat versiebeheer per pagina niet zo duidelijk is
• Slecht, omdat versiebeheer van meerdere en samenhangende pagina’s eigenlijk niet goed ondersteund worden (er zijn wel wat mogelijkheden … maar allemaal suboptimaal)
• Vergelijkbaar met Markdown, omdat het onderliggende formaat waarmee een wiki werkt, ondanks de WYSIWYG editor, gebaseerd is op ‘wikitekst’. Dat is de facto standaard van Mediawiki en lijkt op Markdown. Wikitekst is minder gestandaardiseerd dan Markdown en alleen (in deze vorm) ondersteund door Mediawiki.

Markdown in enige vorm

Bij de ontwikkeling van content, het zij op internet, het zij in documenten, is er behoefte aan opmaak. Opmaak in Microsoft Word is specifiek en direct afhankelijk van de tool MS Word. Op internet is de afhankelijkheid naar een tool er niet. Hoogstens van de HTML (+ CSS + JavaScript) standaarden voor visualisatie mogelijkheden.

Om voor de ontwikkeling van content op internet niet afhankelijk te zijn van technische experts die HTML+ kunnen schrijven, wordt er al lang gezocht naar manieren om met ‘pseudo codes’ opmaak aan te geven in platte tekst. Wikitekst, zoals in de NORA Wiki, is daar een voorbeeld van. Het vroegere Wordperfect had daar ook mogelijkheden voor. Voor software documentatie is Markdown de de facto standaard.

Markdown is een vrij eenvoudige specificatie van speciale codes die opmaak betekenis hebben. Door een conversiestap van bron (source) document naar HTML kan een mooie HTML website gepubliceerd worden. Doordat Markdown redelijk gestandaardiseerd is, zijn er vele (😳) tools beschikbaar die een website kunnen genereren. Hier is enorme keuze om een geschikte tool te vinden afhankelijk van de situatie.

Doordat Markdown bestanden platte tekst bestanden zijn, is versiebeheer mbv Git makkelijk, logisch en veel toegepast. Daarom is dit ook een prettige oplossing voor software developers documentatie. Tools als GitHub en GitLab hebben standaard ook ondersteuning voor Markdown incl. presentatie als HTML.

• Goed, omdat Markdown eenvoudige codes gebruikt, zodat ook minder-technische mensen er mee uit de voeten kunnen
• Goed, omdat Markdown redelijk gestandaardiseerd is
• Goed, omdat versiebeheer per Markdown bestand zeer mogelijk is mbv Git
• Goed, omdat versiebeheer over een collectie Markdown bestanden ook zeer mogelijk is door de toepassing van Git
• Goed, omdat de brondocumenten in Markdown echt ontkoppeld zijn van de tool voor publicatie in HTML
• Slecht, omdat de brondocumenten op enige afstand kunnen staan door de ontkoppeling met de publicatie tool
• Slecht, omdat het versiebeheer geen onderdeel is van Markdown en extra toegevoegd moet worden. Git is daarvoor zeer geschikt … maar ook zo uitgebreid, dat minder-technische mensen daar moeite mee hebben. Dit verhoogt de barrière voor minder-technische mensen om Markdown (plus Git) te gebruiken
• Vergelijkbaar met Wikitekst, omdat het platte tekst is waarin met codes opmaak wordt geproduceerd

Links

• […]