JSON-LD selitettynä
JSON-LD on tavallista JSONia yhdellä ylimääräisellä rivillä, joka kertoo mitä kentät tarkoittavat. Se rivi muuttaa paikallisen kentän nimen maailmanlaajuisesti määritellyksi, joten järjestelmä, joka ei ole koskaan nähnyt tietojasi, pystyy silti päättelemään mistä puhut. Se on ollut W3C-standardi vuodesta 2014, se on tapa jolla hakukoneet lukevat juuri tämän sivun, ja sen varaan on rakennettu W3C:n tietomalli todennettaville valtuustiedoille.
Tavallisen JSONin ongelma
JSON kertoo miten tiedot kirjoitetaan. Se ei kerro mitään siitä mitä ne tarkoittavat. Kenttä nimeltä name voi olla henkilö, yritys tai tuote. Kenttä nimeltä id voi olla asiakasnumero, passin numero tai rivi jonkun tietokannassa. Kaksi järjestelmää voivat molemmat tuottaa täysin kelvollista JSONia ja olla silti eri mieltä sen jokaisesta kentästä.
Käytännössä aukko paikataan sopimuksella. Osapuolet kirjaavat ylös mitä kentät tarkoittavat ja rakentavat ohjelmistonsa sen mukaan. Se toimii yhdessä integraatiossa, käy kalliiksi kymmenessä ja lakkaa toimimasta kokonaan, kun yhdessä maassa myönnetty valtuustieto pitää ymmärtää toisessa maassa olevan todentajan, jolle kukaan ei ole etukäteen puhunut.
Mitä @context tekee
JSON-LD paikkaa aukon dokumentin sisällä. @context yhdistää jokaisen lyhyen kentän nimen maailmanlaajuisesti yksilölliseen tunnisteeseen, tavallisesti URL-osoitteeseen jota hallitsee se joka sanaston määritteli. Kenttä pysyy lyhyenä ja ihmisen luettavana ja muuttuu koneelle yksiselitteiseksi.
Tavallinen JSON
{
"name": "Alex Jansen",
"birthDate": "1994-03-21",
"jobTitle": "Compliance Officer"
}Kelvollista, luettavaa ja merkityksetöntä kaikille, joille ei ole etukäteen kerrottu, mitä kenttien on tarkoitus sisältää.
Samat tiedot JSON-LD-muodossa
{
"@context": "https://schema.org",
"@type": "Person",
"name": "Alex Jansen",
"birthDate": "1994-03-21",
"jobTitle": "Compliance Officer"
}Jokainen kenttä osoittaa nyt julkaistuun määritelmään, joten järjestelmä, joka ei ole koskaan nähnyt tätä dokumenttia, osaa silti lukea sen oikein.
- @context nimeää sanaston, jossa dokumentin jokainen kenttä on määritelty.
- @type kertoo, millaista asiaa dokumentti kuvaa, jotta siitä sanastosta valitaan oikeat määritelmät.
Itse tiedoissa ei muutu mikään. Samat arvot samassa muodossa kantavat nyt osoittimen jokaisen kentän määritelmään. Vastaanottava järjestelmä joka tunnistaa sanaston tietää tarkalleen mitä sille annettiin, ja järjestelmä joka ei tunnista voi silti lukea dokumentin tavallisena JSONina ja jättää loput huomiotta.
Siinä on koko ajatus. Merkitys kulkee dokumentin mukana sen sijaan että se asuisi määrittelyssä, josta osapuolten piti sopia etukäteen.
Missä se näkyy todennettavissa valtuustiedoissa
W3C Verifiable Credentials Data Model 2.0, joka on ollut W3C Recommendation 15. toukokuuta 2025 alkaen, on rakennettu JSON-LD:n varaan. Jokainen valtuustieto alkaa @contextilla, jonka ensimmäinen arvo on yhteinen valtuustietosanasto, joten kaikille valtuustiedoille yhteiset termit, myöntäjä, kohde, voimassaolopäivät ja tilatieto, tarkoittavat kaikkialla samaa.
Kaikki muu tulee toisesta sanastosta. Yliopisto julkaisee sellaisen tutkintotodistusten kentille, kauppakamari yrityksen rekisteröintikentille. Todentaja jota kiinnostavat tutkintotodistukset lataa ensimmäisen, todentaja jota kiinnostavat yritystiedot lataa toisen, eikä kumpaakaan tarvitse muuttaa kun toinen lisää kentän.
Juuri tämä antaa yhden valtuustietomuodon kantaa tietoja joita kukaan ei osannut ennakoida muotoa kirjoitettaessa, ja se on ominaisuus jota avoin ekosysteemi tarvitsee ja suljettu profiili ei.
Linkitetyn datan allekirjoittaminen
Valtuustieto pitää myös allekirjoittaa, ja tietomalli jättää siinä tietoisesti valinnan. Kuoreen käärivä todiste pakkaa koko valtuustiedon allekirjoitussäiliöön kuten JWT:hen. Tavut allekirjoitetaan täsmälleen sellaisina kuin ne ovat, joten mikä tahansa joka järjestää tai muotoilee ne matkalla uudelleen rikkoo allekirjoituksen.
Upotettu Data Integrity -todiste toimii päinvastoin. Dokumentti viedään ensin kanoniseen muotoon, jonka määrittelee RDF Dataset Canonicalization ja joka on ollut W3C Recommendation 21. toukokuuta 2024 alkaen, ja allekirjoitus kattaa sen muodon tavujen sijaan. Koska kanoninen muoto ei riipu avainten järjestyksestä, välilyönneistä tai siitä mitä lyhyitä nimiä @context sattuu käyttämään, allekirjoitus kestää sen että dokumentti kirjoitetaan uudelleen muualla.
Mihin se sopii EUDI Walletissa
Ei sinne minne useimmat olettavat. Architecture and Reference Framework nimeää eurooppalaiselle lompakolle kaksi valtuustietomuotoa, SD-JWT VC:n ja mdocin, eikä kumpikaan ole JSON-LD. Organisaatio joka myöntää tänään EUDI Walletiin ei kohtaa matkalla yhtään @contextia.
Perustelu on toteutettavuus. Molemmilla muodoilla on kiinteä rakenne, yksi allekirjoitusmekanismi eikä yhtään dokumenttia jota todentajan pitäisi hakea ennen kuin se voi tarkistaa mitään. Puhelimessa toimivalle lompakolle ja millisekunneissa vastaavalle todentajalle se on arvokkaampaa kuin avoin sanasto.
JSON-LD ansaitsee paikkansa siellä missä tietojen pitää kulkea niiden määritelleen ekosysteemin ulkopuolelle: tuotepassit ja toimitusketjun tiedot, toimialarajat ylittävät pilotit ja valtuustietotyypit joita mikään keskitetty profiili ei koskaan luettele. Nämä kaksi maailmaa menevät päällekkäin useammin kuin kilpailevat, ja molemmissa toimivat organisaatiot päätyvät yleensä tukemaan kumpaakin.
Se toinen JSON-LD, jota olet jo käyttänyt
Kauan ennen valtuustietoja JSON-LD:stä tuli tapa jolla verkkosivusto kertoo hakukoneelle mistä sivu kertoo. Sen lohko sivun lähdekoodissa, schema.orgin sanastoa käyttäen, tekee sivusta tunnistetun artikkelin, tuotteen, tapahtuman tai organisaation. Tällä sivulla on yksi.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "JSON-LD selitettynä",
"description": "Mitä JSON-LD lisää tavalliseen JSONiin, miten @context antaa jokaiselle kentälle yhden merkityksen ja missä todennettavat valtuustiedot käyttävät sitä.",
"image": "https://www.credenco.com/images/og-default.jpg",
"datePublished": "2026-10-15",
"dateModified": "2026-10-15",
"inLanguage": "fi",
"mainEntityOfPage": "https://www.credenco.com/fi/explained/json-ld",
"author": {
"@type": "Organization",
"name": "Credenco",
"url": "https://www.credenco.com/"
},
"publisher": {
"@type": "Organization",
"name": "Credenco",
"logo": {
"@type": "ImageObject",
"url": "https://www.credenco.com/logo.svg"
}
}
}Se on sama muoto eri sanastolla, ja se on selkein tapa nähdä pointti. Kukaan täällä ei ole sopinut mistään minkään hakukoneen kanssa. @context osoittaa schema.orgiin, hakukone tuntee sanaston jo, ja sivun ymmärtää osapuoli jolle se ei ole koskaan puhunut. Rajan ylittävä valtuustieto tekee täsmälleen saman.
Mitä se maksaa
Kontekstin pitää olla saatavilla. Todentaja joka hakee sen todennushetkellä on lisännyt verkkoriippuvuuden turvallisuuspäätökseen, ja se joka tarjoilee dokumenttia voi muuttaa sitä mitä valtuustieto näyttää sanovan. Todelliset käyttöönotot kiinnittävät hyväksymänsä kontekstit ja toimittavat ne ohjelmiston mukana sen sijaan että hakisivat ne lennosta.
Myös kanonisointi on oikeaa työtä. Dokumentin muuntaminen kanoniseksi tietojoukoksi ennen allekirjoitusta on huomattavasti enemmän koodia kuin tavujen allekirjoittaminen, ja sen virhetilanteet ovat hienovaraisia. Dokumentit ovat lisäksi suurempia, millä alkaa olla väliä QR-koodissa tai NFC-kosketuksessa.
Mikään tästä ei tee JSON-LD:stä väärää valintaa. Se tekee siitä valinnan: maksa avoimista sanastoista siellä missä tietojen pitää elää pidempään kuin sopimuksen joka ne loi, ja jätä ne pois siellä missä kiinteä profiili jo kertoo kaiken mitä osapuolet tarvitsevat.
Mitä tämä tarkoittaa sinulle
Myöntäjä
EUDI Walletiin myöntäminen tarkoittaa SD-JWT VC:tä tai mdocia, eikä JSON-LD tule koskaan vastaan. W3C-ekosysteemiin myöntäminen tekee @contextistasi pitkän aikavälin sitoumuksen: se on kenttiesi julkinen määritelmä, ja sen muuttaminen rikkoo jokaisen todentajan joka välimuisti vanhan.
Todentaja
Päätä mitkä kontekstit hyväksyt ja toimita ne ohjelmistosi mukana. Yhden hakeminen todennuksen aikana tekee etäpalvelimesta osan turvallisuuspäätöstäsi ja sijoittaa verkkokutsun keskelle vasteaikaasi.
Kehittäjä
Lue JSON-LD-dokumentti tavallisena JSONina kun tarvitset vain yhden kentän, ja tartu täyteen prosessoriin vasta siellä missä oikeasti laajennat tai kanonisoit. Suurin osa siitä monimutkaisuudesta jota JSON-LD:lle luetaan on allekirjoituspolussa, ei lukupolussa.
Aiheeseen liittyvät termit
Usein kysytyt kysymykset
Onko JSON-LD yhä vain JSONia?
On. Jokainen JSON-LD-dokumentti on kelvollista JSONia, ja ohjelmisto joka tarvitsee vain yhden kentän voi käsitellä sitä sellaisenaan. Ylimääräinen koneisto tulee mukaan vasta kun dokumentti laajennetaan täyteen muotoonsa tai kanonisoidaan allekirjoitusta varten, mitä suurin osa valtuustietoa lukevasta koodista ei koskaan tee.
Käyttääkö EUDI Wallet JSON-LD:tä?
Ei. Architecture and Reference Framework nimeää valtuustietomuodoiksi SD-JWT VC:n ja mdocin, eikä kumpikaan käytä JSON-LD:tä. Sillä on merkitystä W3C:n todennettavien valtuustietojen ekosysteemeissä, tuotepasseissa ja toimitusketjun tiedoissa, ei eurooppalaisessa lompakossa itsessään.
Lataako todentaja @contextin joka kerta?
Ei pitäisi. Kontekstin hakeminen todennuksen aikana sijoittaa verkkokutsun keskelle turvallisuuspäätöstä ja antaa etäpalvelimelle mahdollisuuden muuttaa sitä, mitä dokumentti näyttää sanovan. Toteutukset kiinnittävät hyväksymänsä kontekstit ja toimittavat ne ohjelmiston mukana, mikä poistaa myös viiveen.
Onko tämä sama JSON-LD, jota hakukoneet lukevat?
Sama muoto eri sanastolla. Verkkosivun rakenteinen data osoittaa @contextinsa schema.orgiin, kun taas valtuustieto osoittaa sen valtuustietosanastoon ja siihen mitä muuta se tarvitsee. Käsittelysäännöt ovat molemmissa tapauksissa identtiset.
Lähteet
Tämä sivu on tiedoksi eikä ole oikeudellista neuvontaa. Sitovat ohjeet löytyvät suoraan W3C:n määrittelyistä.