Momenteel is JSON een populair formaat voor gegevensuitwisseling naast het bekende XML. Om JSON toe te passen in StUF-koppelvlakken zal de StUF-onderlaag uitgebreid c.q. aangepast moeten worden. Hieronder een eerste scenario voor de te volgen stappen:
- Beschrijf in de specificatie van StUF-berichtenstandaard (stuf0302.pdf) dat XML niet meer het enige formaat is van StUF maar dat er ook andere formaten kunnen zijn zoals JSON (maar mogelijk in de toekomst ook JSON-LD, YAML, etc.). Formuleer het op een generieke manier zodat er nieuwe formaten kunnen worden toegevoegd zonder dat er een versieverhoging van de StUF-onderlaag nodig is.
- Voeg een JSON-versie (stuf0302.json ) van het stuf0302.xsd schema toe aan de StUF-onderlaag
- Voeg een appendix toe aan de stuf0302.pdf waarin beschreven wordt hoe de XML- en XSD-voorbeelden in de standaardtekst omgezet kunnen worden naar respectievelijk JSON en JSON Schema formaten.
- Voeg een hoofdstuk toe aan het StUF Best Practices document waarin beschreven wordt hoe je het best JSON Schema’s kunt opstellen op basis van de nieuwe StUF-onderlaag (stuf0302). Eventueel worden de StUF Best Practices opgesplitst in twee documenten: één voor XML en één voor JSON.
- Voeg (eventueel) JSON-versies van de basisschema’s toe aan de generieke halffabricaten zoals StUF-BG, StUF-ZKN en StUF-ZTC. Dus aan de basisschema’s bg0310_ent_basis.xsd, zkn0310_ent_basis.xsd en ztc0310_ent_basis.xsd zullen er ook JSON-equivalenten worden toegevoegd zoals bg0310_ent_basis.json, zkn0310_ent_basis.json en ztc0310_ent_basis.json.
- Voeg (een) nieuwe binding(en) toe aan de bestaande StUF Protocolbindingen (stuf.bindingen.030203.pdf) om JSON-berichten te kunnen transporteren via pure HTTP(S) zonder SOAP-envelop. SOAP is een XML-envelop en daar kun je helaas geen JSON-content in kwijt.
Ad 5. De vraag is of er JSON Schema equivalenten wel perse nodig zijn naast de XSD-basisschema’s van StUF-BG, StUF-ZKN en StUF-ZTC. JSON-berichten worden vaak gebruikt in toepassingen waar schema’s veelal niet nodig zijn. JSON Schema is dan ook nog niet officieel vastgesteld in een internationaal standaardisatieorgaan. De grootte en de hoeveelheid van berichtdefinities in JSON-koppelvlakken is doorgaans dermate klein dat een aantal berichtvoorbeelden met beschrijvende tekst voldoende is. KING zou er dan op toe moeten zien dat de JSON-berichtdefinities in lijn zijn met de onderliggende XSD-definities van de halffabricaten.
Ad 6. Een zuiver HTTP(S) protocol zonder SOAP wordt vaak toegepast in REST-koppelvlakken. Om StUF (beter) geschikt te maken voor REST-toepassingen zal een aparte RFC worden ingediend.
Dit erratum is opgevoerd in de onderhoudsverzoeken als ONV0423.
De lijst met onderhoudsverzoeken vind je op:
gemmaonline.nl/index.php/StUF-Expertgroep#Documenten
In de bijlage van deze post heb ik een notitie toegevoegd waarin een omkeerbare vertaling tussen XML en JSON wordt beschreven. Omkeerbaarheid is belangrijk omdat hiermee JSON-berichten gevalideerd kunnen worden met de bestaande XSD-schema’s voor StUF. Als de vertaling niet omkeerbaar is zouden er aparte JSON schema’s voor de StUF-berichten gedefinieerd moeten worden. Dat zou een behoorlijke extra beheerlast geven, met name het in overeenstemming houden van de XML- en JSON-schema’s. Bovendien is JSON Schema nog niet officieel gestandaardiseerd en minder expressief en uitgekristalliseerd als XML Schema (XSD).
Dit is aanvullend huiswerk voor de aankomende StUF Expertgroep met betrekking op agendapunt 3 (Openstaande RFC's) zoals in de agenda al werd aangekondigd!
Bijlage
Tijdens de StUF Expertgroep van 20 januari 2016 is de vertaling van StUF xml naar JSON voorgelegd.
In de daarop volgende discussie bleek dat de leden heel verschillend dachten over het toevoegen van andere syntaxen zoals JSON aan StUF. Sommigen zagen dat als het loslaten van StUF anderen vondt dat KING daarin nog niet ver genoeg ging. Ook over een nog in te leggen waarin wordt voorgesteld om het mogelijk te maken alleen het contentmodel te gebruiken verschilden de meningen. Enkele leden gaven aan behoefte te hebben aan een totaalschets. Deze is toegezegd.
Tijdens de StUF Expertgroep van 18 mei 2016 is aangegeven dat de StUF Expertgroep dit RFC pas goed kan beoordelen als KING een totaalschets heeft vervaardigd. het RFC is daarop niet verder besproken.
Tijdens de StUF Expertgroep van 21 september 2016 is aangegeven dat REST en JSON steeds meer worden gebruikt en dat we er dus iets mee moeten. We moeten echter wel heel kritisch zijn over waar we dit gaan toepassen.
Er werd gesteld dat in de GEMMA architectuur moet komen te staan wanneer je SOAP gebruikt en waar REST of JSON.
Daarnaast werd aangegeven dat je daarnaast middels de openbare consultatie foutief gebruik kunt voorkomen.
Aangezien die mogelijkheid door enkele aanwezigen als te beperkt werd beoordeelt is er bij KING op aangedrongen haar processen nog eens goed tegen het licht te houden. Met de belofte dat te doen heeft de StUF Expertgroep dit RFC uiteindelijk goed gekeurd.
Tijdens de StUF Expertgroep van 15 februari 2017 is aangegeven dat deze functionaliteit vooralsnog nog niet aan de StUF standaard toegevoegd hoeft te worden. De basis-schema's hebben meer prioriteit.
M.b.t. het actiepunt voor het aanscherpen van het proces voor de openbare consultatie (de StUF Expertgroep zou daarin te weinig invloed hebben) is gesteld dat dit een kwestie is van goed handhaven van het huidige proces. Er hoeft hieraan dus niets meer gedaan te worden. Wel moeten er nog ergens criteria opgenomen te worden aan de hand waarvan bepaald kan worden wanneer er voor SOAP en wanneer er voor REST moet worden gekozen.
Tijdens de StUF Expertroep is nogmaals geconcludeerd dat dit RFC iets is voor de lange baan. Dat betekent niet dat het pas bij StUF 4.0 gaat spelen. Het kan op een later moment immers altijd als een uitbreiding aan StUF 3.02 worden toegevoegd. Ook in het kader van die standaard worden nl. mogelijkheden gezien voor REST en JSON.