JSON-LD Specifications¶
The following document provides a specification for the JSON-LD context names used in CowCerts JSON certificates.
All specifications here extend the Blockcerts context specifications ( available in a markdown document)
And Blockcerts extends the Open Badges specifications
Entities¶
These are the extended JSON entities we define to achieve the digital granting of academic certificates. We also define the generic entities so that all the document can be understand within this single specifications document.
Assertion¶
Assertions are representations of an awarded badge, used to share information about a badge belonging to one earner. Assertions are packaged for transmission as JSON objects with a set of mandatory and optional properties. Fields marked in bold letters are mandatory.
Property | Expected type | Description |
---|---|---|
id | IRI |
Uniquely identifies the assertion.
Should be an HTTPS dereferenceable
IRI so verifiers can link to the
assertion. The document behind the IRI
should provide information about the
assertion and its validation. |
type | JSON-LD type | JSON-LD assertion type.
The type is fixed to: Assertion . |
recipient | IdentityObject |
The recipient of the achievement. |
badge | BadgeClass |
Badge document being awarded. |
verification | Verification
Object |
A collection of information allowing an inspector to verify this assertion. |
issuedOn | DateTime |
Timestamp of when the achievement was awarded. ISO 8601 compliant. |
image | ImageObject |
Image representing this achievement. |
recipientProfile | Recipient
Profile |
Blockcerts extension allowing additional recipient details including recipient’s public key to make a strong claim of the ownership over the key. Name must be set if the verifier provided by Blockcerts has to display it. |
signature | MerkleProof2019 |
An extension that allows an issuer to issue an Open Badge on the blockchain and provide proof of inclusion in a blockchain transaction. This uses Merkle Proof Signature Suite 2019. |
displayHtml | Text |
HTML code to display the certificate Will be used in the blockcerts verifier to display the certificate visually. This way the certificate will always be visualized the same way even if the certificate displayer (in this case blockcerts verifier) changes. |
issuedAt | Text |
Place where the assertion was issued (the city for instance) |
officialValidation | Endorsement |
Mandatory field if the BagdeClass
being awarded has an officiality
requirement. This Endorsement has
always a MinistryClaim it its
claim field. |
signatureLines | Array of
SignatureLine |
List of handwritten signatures that must appear in the certificate visualization |
universalIdentifier | Text |
Universal identifier of the assertion.
Allows to identify the assertion
uniquely in the universe.
Contains a UUID string. |
IdentityObject¶
A collection of information about the recipient of a IdentityObject
.
Note
The Open Badges standard does not allow for a recipient to have more than one field (or a document) identifying it. For this reason, we use the government’s tax ID in this identify object and all extra fields will be placed in an additional assertion, referencing this identity object.
To provide optional additional privacy to the recipient, this field will be always hashed.
Property | Expected type | Description |
---|---|---|
identity | IdentityHash |
The hash of student email. |
type | Property IRI |
Fixed Extra fields will be placed in an additional endorsement. |
hashed | Boolean |
Always True . |
salt | Text |
If the recipient is hashed, this should contain the string used to salt the hash. If this value is not provided, it should be assumed that the hash was not salted. This field is mandatory, as opposite to the Open Badges specification. |
IdentityHash¶
A hash string preceded by a dollar sign (“$”) and the algorithm used to generate the hash. The supported algorithms are MD5 and SHA-256, identified by the strings md5 and sha256 respectively.
Hint
For example:
sha256$28d50415252ab6c689a54413da15b083034b66e5
represents the result of calculating a SHA-256 hash on the string “mayze”.
For more information, see how to hash & salt in various languages.
BadgeClass¶
A collection of information about a badge.
Property | Expected type | Description |
---|---|---|
id | Text |
Unique IRI for the BadgeClass. |
type | JSON-LD type | JSON-LD assertion type.
The type is fixed to: BadgeClass . |
name | Text |
Name of the badge defined in the syllabus. |
description | Text |
Description of the knowledge acquired by a recipient of this badge. |
image | ImageObject |
Image representing the badge. |
criteria | @id:Criteria |
URI or embedded criteria document describing how to earn the achievement. |
issuer | Profile |
IRI or document describing the individual, entity, or organization that issued the badge. |
signatureLines | Array of
SignatureLine |
List of visual signatures to display. |
tags | Array of Text |
An array containing tags that |
legalText | Text |
Additional information to the title that refers to its legality (legal text). describes the type of achievement. |
official | Boolean |
True if requires an official
validation. Defaults to False if
field is not present. |
ImageObject¶
Metadata about images that represent Assertions
, BadgeClasses
or
Profile
.
These properties can typically be represented as just the id string of the image, but using a fleshed-out document allows for including captions and other applicable metadata. https://schema.org/ImageObject
Property | Expected type | Description |
---|---|---|
type | JSON-LD type | Type of the image object.
Default is schema:ImageObject . |
id | IRI |
Data URI of the image. |
caption | Text |
Caption of the image, if any. |
Criteria¶
Descriptive metadata about the achievements necessary to be recognized with an
Assertion
of a particular BadgeClass
.
Property | Expected type | Description |
---|---|---|
type | JSON-LD type | Type of the image object.
Fixed: Criteria . |
narrative | Text |
A narrative of what is needed to earn the badge. |
id | IRI |
The URI of a webpage that describes in a
human-readable format the criteria for
the BadgeClass . |
Profile¶
A Profile is a collection of information that describes the entity or organization using Open Badges.
Property | Expected type | Description |
---|---|---|
id | IRI |
Issuer blockchain address IRI, defined in issuerSchema by blockcerts. |
type | JSON-LD type | Fixed: Profile . |
name | Text |
The name of the entity or organization. |
url | IRI |
The homepage or social media profile of the entity, accessible via HTTP. |
telephone | Text |
A phone number for the entity (E.164 format). |
description | Text |
A short description of the issuer, public or private and year of creation |
image | ImageObject |
An image representing the issuer. |
Text |
Contact address for the individual or organization. | |
revocationList | URI |
HTTP URI of the Badge Revocation List
used for marking revocation of signed
badges. The revocation list is
published as a JSON-LD document with
type RevocationList . |
RevocationList¶
List of assertions revoked by the issuer of the degree.
Property | Expected type | Description |
---|---|---|
id | IRI |
The id of the RevocationList. |
type | JSON-LD type | Fixed Profile . |
issuer | IRI: Profile |
The id of the Issuer. |
revokedAssertions | IRI |
A string id identification of a
badge object that has been revoked. And
a string revocationReason indicate
the reason for revocation. |
VerificationObject¶
Defined by verification property of https://w3id.org/openbadges#Assertion, with Blockcerts extensions for verification of badges on a blockchain.
Property | Expected type | Description. |
---|---|---|
type | Array |
Fixed: MerkleProofVerification2017 ,
Extension |
publicKey | Text |
Blockcerts extension: the expected
blockchain address for the signer of
the transaction containing the merkle
proof. In Blockcerts publicKeys are
typically represented with a
<scheme>: prefix. For Bitcoin
transactions, this would be the issuer
public Bitcoin address prefixed with
ecdsa-koblitz-pubkey: . |
MerkleProof2019¶
Extends the Merkle Proof 2017 verification allowing to contain additional information about the assertion: a set of endorsements. They also contain extra information to verify the certificates in other blockchains other than the ones accepted by Blockcerts (for instance, the BlockValley ones).
Some endorsements are completely optional and are signed by their issuers independently so they cannot be included inside the assertion as when signing it the signature would contain the endorsements, which as we said are optional and may appear in the future.
Note
The signature field is the only field in an assertion that is not signed (because it contains the signature itself) therefore is the only place where these endorsements fit. They may be present or not to provide extra information about the assertion, but without them the assertion is valid.
This way we can package all information about the assertion, including its endorsements in a single portable document.
Property | Expected type | Description |
---|---|---|
type | Array |
Composed type of Extension and
MerkleProofVerification2019 . |
merkleRoot | Text |
Batch identifier (SHA256). |
targetHash | Text |
Current document’s SHA256 hash. |
anchors | Array of
Anchor objects |
Array containing a list of anchor
objects that define how the
merkleRoot has been registered in
one or more blockchains. |
proof | Text |
See Merkle Proof 2017 for more. |
endorsements | Array of
Endorsement |
Endorsements containing additional information about the current document. |
Anchor¶
Specifies how the merkleRoot
in a Merkle Proof 2019
signature has been
registered on a blockchain.
Property | Expected type | Description |
---|---|---|
type | JSON-LD type | BTCOpReturn or ETHData defined
in https://chainpoint.org/ . |
sourceId | Text |
Identifier, such as a transaction id, used to locate anchored data. |
chain | Text |
Chain is an optional field introduced by Blockcerts to help during verification. Check Merkle Proof Signature 2017 specifications document to see a list of accepted chains. |
otherChains | Array of
Other chain
objects |
Allows to verify the certificate in other chains other than the accepted by Blockcerts. This way Blockcerts can verify with a chain they consider valid and other verifiers may supply other blockchains to verify this on too. |
Other chain¶
Allows to define another chain where an anchor may be placed other than the accepted by the Blockcerts standard to be used by validators that both understand Blockcerts and Cowcerts standards.
Property | Expected type | Description |
---|---|---|
id | IRI |
Chain id. Should be able to be dereferrenced so the document behind provides more information about the chain and how to connect to it. |
name | Text |
Commonly used name to identify the chain. |
protocol | Text |
Protocol the blockchain uses.
Valid values are ETH for
Ethereum. |
genesis | Text |
Hexadecimal string representing the genesis block hash for the network. |
consortium | IRI |
Consortium where the chain belongs (if any). |
Note
If the id
is urn:example:local
, the verifier of the certificate will
connect against a local development blockchain so that blockchain checks
can be triggered against a dummy blockchain.
In the case of protocol ETH
, checks will be performed against a local
Ethereum node using the web3
JSON-RPC at default port 8545 against the
same host where the verifier is running.
A note will alert the user that the blockchain checks are performed against a dummy blockchain and must not be taken seriously.
Endorsement¶
The endorsement class is very similar to an Assertion
, except that there is
no defined badge property. Instead, a claim property allows endorsers to make
specific claims about other Profiles
, BadgeClasses
, or Assertions
.
Property | Expected type | Description |
---|---|---|
id | Text |
Unique IRI for the endorsement instance. If using hosted verification, this should be the URI where the assertion of endorsement is accessible. |
type | JSON-LD type | Endorsement type;
Fixed: Endorsement . |
claim | RecipientClaim
EDSClaim or
MinistryClaim |
An entity, identified by an id and additional properties that the endorser would like to claim about that entity. Three claim entities have been defined based on the attached information. |
issuer | Profile |
The profile of the endorsement’s issuer. |
issuedOn | DateTime |
Timestamp of when the endorsement
was published (ISO8601 compliant). |
verification | Verification
Object |
Instructions for third parties to verify this endorsement. |
signature | SignatureObject |
An extension that allows an issuer to issue an Open Badge on the blockchain and provide proof of inclusion in a blockchain transaction. This uses Merkle Proof 2017 Signature Suite. |
signatureLines | Array of
SignatureLine |
List of handwritten signatures that must appear in the certificate visualization |
Claims¶
MinistryClaim¶
Appends the information of the assertion’s registry by the Education Ministry.
Property | Expected type | Description |
---|---|---|
type | Array |
Composed type of MinistryClaim
and Extension . |
id | IRI |
Id of the Assertion that endorsement is giving extra info. |
ministrySignature | SignatureLine |
Handwritten signature that gave validity to academic certificates analogically. |
registryCode | Text |
Alphanumeric code that represents the unique identifier of the official title record of the government of Andorra. |
RecipientClaim¶
An extension of the information about the recipient of the assertion. Mainly uses fields from a Person
Property | Expected type | Description |
---|---|---|
type | Array |
Composed type of RecipientClaim
and Extension . |
id | IRI |
Id of the Assertion that endorsement is giving extra info. |
givenName | Text |
The name of the recipient |
familyName | Text |
The surnames of the recipient |
birthplace | Text |
The place where the person was born. |
birthdate | Text |
The date when the person was born. |
nationality | Text |
Nationality of the person ISO 3166-1-
alpha2 . |
nationalId | Text |
The national ID person of their country, e.g. the CIF/NIF in Spain or NPI in Andorra. |
EDSClaim¶
Adds additional information to the Assertion
so it can be a valid European
Diploma Supplement (EDS) .
Language codes must be compatible with BCP47
. Think “en” or “es-MX”.
JSON-LD allows much more expressive combinations of multiple languages in one
document. It is likely that you may be able to produce Badge Objects taking
advantage of these features that will not be understood by some or all
validators or display tools. It is recommended to keep implementations as
simple as possible and communicate with the standards group when you want to
move beyond the example techniques expressed here.
It provides additional information to that included in the official degrees / diplomas and/or transcript, making it more easily understood, especially by employers or institutions outside the issuing country. (explicacio numero)
Property | Expected type | Description |
---|---|---|
type | Array |
Composed type of EDSClaim
and Extension . |
id | IRI |
Id of the Assertion that endorsement is giving extra info. |
mainField | Text |
2.2 Main field(s) of study for the qualification. |
awardingInstitution | Text |
2.3 Name (in original language) and status of awarding institution. |
administeringInstitution | Text |
2.4 Name (in original language) and status of institution administering studies. |
language | Text |
2.5 Language(s) of instruction / examination. |
studiesLevel | Text |
3.1 Level of qualification. |
studiesLength | Text |
3.2 Official length of programme. |
access | Text |
3.3 Access requirements. |
mode | Text |
4.1 Mode of study. |
requirements | Text |
4.2 Programme requirements. |
grades | Array of
EDSSubject
items |
4.3 Programme details. |
gradingScheme | Text |
4.4 Grading scheme. |
qualification | Text |
4.5 Overall classification of the qualification. |
further | Text |
5.1 Access to further study. |
competences | Array of
Text |
5.2 Professional status and competences. |
extraInfo | Array of
Text |
6 Additional information. |
educationSystem | ImageObject |
8 Information on the national higher education system Badge. |
rectorSignature | ImageObject |
7 Certification of the Supplement, image of the rector signature |
managerSignature | ImageObject |
7 Certification of the Supplement, image of the manager signature |
EDSSubject¶
This object includes all the information related to one subject that will be included in the European Diploma Supplement (EDS).
Property | Expected type | Description |
---|---|---|
name | Text |
Name of subject |
choice | Text |
Type of the subject, it could be one of the
following:
OB : Obligatory; OP : Optional;
LL : Free Choice |
semester | Text |
Semester during which the studies were taken |
year | Number |
Year when the subject was taken. |
mobility | Text |
International academic mobility
M if was studied abroad, - if not. |
grade | Text |
Grade (CO : if convalidated)
Otherwise, the grade obtained as a float.
(ie: 8.4 ). Using a dot . as decimal
separator. |
credits | Number |
Amount of ECTS credits the subject took. |