Specificatie
Een formaat publiceren is een belofte doen, en een belofte zonder grens is er geen. Deze pagina trekt die grens: wat je moet bouwen, wat je daarna mag zeggen dat je ondersteunt, en wat er gebeurt op elk punt waar je lezer iets tegenkomt dat hij niet kent.
Het punt van de splitsing is dat geen van beide niveaus meegroeit met het aantal slidetypes. Een lezer die negen typecontracten leert, kent negen dingen en is verouderd op de dag dat er een tiende gepubliceerd wordt. Een lezer die zes structuurcontracten leert, kan een type renderen dat nog niet bestond toen hij gebouwd werd.
Niveau 1
De envelop, de zes structure-contracten, en het gedrag bij een type dat je niet herkent.
Leest Deckyard-decks
Elk deck rendert en er valt niets weg. Sommige slides renderen generiek in plaats van zoals ze geschreven zijn, en dat is een degradatie die je zelf hebt aangekondigd, geen storing die de lezer ontdekt.
Niveau 2
Niveau 1, plus de veldcontracten van de negen tier-1-types, plus fallback.
Rendert het Deckyard-core-profiel
Elk deck rendert zoals het geschreven is, op de degradatie na die elk type voor zichzelf declareert. Dit is het realistische doel: een weekend werk, geen catalogus.
Vink aan wat je werkelijk rendert. De zin eronder is degene die je in je eigen documentatie mag zetten, en de getallen erachter zijn geteld op de gepubliceerde registry, niet geschat.
Elk slidetype declareert één structure, en die declaratie is de interop-valuta: ze zegt wat de content bevat, of het aantal iets betekent, en wat een lezer die verder niets van het type weet ermee mag doen.
"content": {
"title": "A deck is a file you own",
"subtitle": "Portable by construction"
}"content": {
"title": "Three horizons",
"items": [
{ "label": "Now", "text": "One pilot" },
{ "label": "Next", "text": "A second reader" },
{ "label": "Later", "text": "An archive" }
]
}minItems === maxItems."content": {
"title": "Effort against impact",
"quadrants": [
{ "label": "Do now", "text": "…" },
{ "label": "Plan", "text": "…" },
{ "label": "Delegate", "text": "…" },
{ "label": "Drop", "text": "…" }
]
}"content": {
"title": "What each layer carries",
"rows": [
{ "layer": "Deck format", "offline": false },
{ "layer": "Deck package", "offline": true }
]
}tabular. Alleen de visuele codering gaat verloren."content": {
"title": "Installs per quarter",
"chartType": "bar",
"chartData": "{\"labels\":[\"Q1\",\"Q2\"], …}"
}"content": {}collection en fixed-collection verschillen alleen in of het aantal betekenis draagt. Precies daarom zijn het twee structuren en niet één: een lijst van zes mag je in twee kolommen herschikken, een vierkwadrantenmatrix mag je niet tot drie terugbrengen. dataset is de enige structuur waarvan de payload niet te controleren is, en het contract zegt dat ook, in plaats van een lezer er zelf een degradatie bij te laten verzinnen.
Negen namen zijn normatief. De overige types die Deckyard shipt, worden gepubliceerd en gedocumenteerd maar versioneren mee met de app, en een type uit een fork draagt de belofte van zijn declarant en niet die van ons. Een tier is een eigenschap van de naam, niet van de definitie: een fork die `title-slide` overschrijft, erft de tier-1-belofte, want dat is wat het kiezen van die naam betekent.
title-slide chapter-title-slide content-slide list-slide quote-slide image-slide image-text-slide table-slide end-slide De keuze is een criterium, geen smaak: dit is de minimale verzameling om een gewone presentatie zonder verlies uit te drukken - titel, sectiebreuk, proza, opsomming, citaat, beeld, beeld-met-tekst, tabel, afsluiting. Alles daarbuiten voegt expressiviteit toe die binnen de negen een aanvaardbare degradatie heeft, en dat is ook waarom er geen grafiektype in zit: een profiel dat een charting-runtime eist, is geen instapdrempel meer.
Dit is de regel die de negen iets waard maakt: elk tier-2-type declareert een fallback naar een tier-1-type. Een funnel valt terug op een lijst, een gallery op beelden, een grafiek op een tabel. Zo rendert een lezer die alleen de negen kent élk Deckyard-deck zonder inhoud te laten vallen.
content-slide 7 degraderen hiernaartoe
video-slide embed-slide countdown-slide likert-slider-slide feedback-slide follow-invite-slide custom-html-slide list-slide 11 degraderen hiernaartoe
kpi-metrics-slide team-cards-slide icon-card-grid-slide poll-slide likert-slide text-blocks-slide process-slide timeline-slide funnel-slide pyramid-slide cycle-slide image-slide 2 degraderen hiernaartoe
logo-wall-slide gallery-slide table-slide 3 degraderen hiernaartoe
chart-slide comparison-slide matrix-slide end-slide 1 degraderen hiernaartoe
payoff-slide De fallback noemt een tier-1-contract, geen één-op-één slidewissel. Een gallery die terugvalt op image-slide betekent "deze inhoud is beeld, render het zoals je beeld rendert", en een lezer mag er meer dan één slide van maken.
Binnen een naam alleen toevoegen. Betekenis wijzigen is een naam wijzigen.
Normatief, en geldig voor elke gepubliceerde naam: een slidetype, een contentsleutel, een envelopsleutel, een enum-waarde. Deckyard migreert zijn eigen opslag vooruit, maar een lezer die wij niet bezitten draait onze migratieketen niet, dus voor alles wat gepubliceerd is, is een migratie geen reparatie. De twee blokken hieronder maken dezelfde wijziging aan hetzelfde type, en maar één van de twee houdt elk ooit geschreven deck geldig.
Mag
"fields": [
{ "key": "title", "required": true },
{ "key": "subtitle", "required": false },
{ "key": "eyebrow", "required": false }
]Mag niet
"fields": [
{ "key": "title", "required": true },
{ "key": "subtitle", "required": false },
{ "key": "eyebrow", "required": true }
]@version: één type heeft één id, en er is geen aliastabel om te leren. De twee oudere spellingen van een core-id - de kale title-slide en de gekwalificeerde core/title-slide - zijn restanten van vóór de convergentie en geen onderdeel van het formaat; een lezer is ze niets verschuldigd en MAG ze als onbekend type behandelen, wat het onbekend-type-contract zonder verlies rendert. Het achtervoegsel @version is een compatibiliteitshint over een definitie, geen ander type, dus eu.deckyard.slide.title@2 MAG niet als onbekend gelden.Dit is wat "er valt niets weg" betekent op het lastigste punt: een type waarvoor je helemaal geen declaratie hebt, uit een fork die je nooit gezien hebt. Het is een vastgelegde rendering, geen foutpad, en het is het laatste redmiddel - een type waarvan je de declaratie wél hebt maar dat je niet geïmplementeerd hebt, gaat via zijn `structure` of zijn gedeclareerde `fallback`.
{
"type": "nl.ciiic.slide.roadmap",
"content": {
"title": "Where this is going",
"intro": "Three horizons, no dates.",
"phases": [
{ "label": "Now", "detail": "One pilot" },
{ "label": "Next", "detail": "A second reader" }
]
},
"notes": "Do not promise dates."
}Elke string in auteursvolgorde, elk array-element als herhaald item, de typenaam op de slide, en de presentatienotitie gehonoreerd omdat het een envelopsleutel is die niet van het type afhangt.
MOET de slide renderen. Weglaten verandert stilzwijgend het aantal slides, de nummering en het betoog dat het deck voert. Een lezer MAG het deck ook niet afwijzen: één onbekend type maakt een deck niet ongeldig.
MOET elke stringwaarde in content als tekst renderen, in de volgorde waarin de sleutels in content staan - een producent schrijft ze in de gedeclareerde veldvolgorde, dus dat is de volgorde van de auteur. Een lezer wiens parser die volgorde niet bewaart, MOET een stabiele volgorde kiezen in plaats van een willekeurige. De lege string betekent niet-ingevuld en MAG worden overgeslagen.
MOET elk element van een array-waarde als een herhaald item renderen, in arrayvolgorde, met regel 2 binnen elk element. Dat is het collection-contract: herschikken mag, herordenen of afkappen niet.
MOET de typenaam tonen, zoals die in type staat, op of naast de slide. Een kijker moet een generieke rendering van een geschreven rendering kunnen onderscheiden; stil mooie uitvoer is precies hoe "wij ondersteunen Deckyard" onwaar wordt zonder dat iemand het merkt.
MOET de globale slidesleutels honoreren die hij al kent - notities, duur, zichtbaarheid, en de toegankelijkheids- en achtergrondsleutels. Die zijn envelopniveau en hun betekenis hangt niet van het type af.
ZOU de slide in het thema van het deck moeten renderen, zodat een onbekend type leest als een gewone slide en niet als kapotte software.
MAG geen inhoud verzinnen. Geen bedachte koppen, geen ingevulde gaten, geen herordening. Minder getrouw renderen dan de auteur schreef is een degradatie; iets renderen dat de auteur niet schreef is een fout.
Een waarde die geen scalair is en ook geen array of object van scalairen - een geneste payload die een lezer niet kan interpreteren - MAG worden weggelaten. Regel 7 gaat voor volledigheid.
De uitputtende tabellen - elk envelopveld, elk manifestveld, elk slidetype met zijn facetten - staan in de documentatie, de helft die de zoekfunctie van de site indexeert. Volledige referentie