{"id":19571658,"url":"https://github.com/serlo/lenabi-exchange-format","last_synced_at":"2025-02-26T10:43:10.205Z","repository":{"id":152143589,"uuid":"599491228","full_name":"serlo/lenabi-exchange-format","owner":"serlo","description":"M2.1 Entwurf für die allgemeine Grundstruktur des Aufgaben- und Austauschformats steht und ist in einem Open Source Repository veröffentlicht.","archived":false,"fork":false,"pushed_at":"2023-03-03T20:56:39.000Z","size":4253,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-01-09T03:14:17.952Z","etag":null,"topics":["documentation","poc","serlo"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/serlo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-09T08:51:01.000Z","updated_at":"2023-07-12T15:29:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"0887c13a-3578-474c-b911-a4acf8147a30","html_url":"https://github.com/serlo/lenabi-exchange-format","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serlo%2Flenabi-exchange-format","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serlo%2Flenabi-exchange-format/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serlo%2Flenabi-exchange-format/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serlo%2Flenabi-exchange-format/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serlo","download_url":"https://codeload.github.com/serlo/lenabi-exchange-format/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240840036,"owners_count":19866164,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","poc","serlo"],"created_at":"2024-11-11T06:19:41.448Z","updated_at":"2025-02-26T10:43:10.036Z","avatar_url":"https://github.com/serlo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://github.com/serlo/lenabi-exchange-format/blob/main/assets/serlo.svg?raw=true\" alt=\"Serlo Logo\" title=\"Serlo\" align=\"right\" height=\"75\" /\u003e\n\n# Exchange Format for Serlo Content\n\n## Introduction\n\nWe want to achieve that learning content can be shared and exchanged between\nlearning platforms and that they are not tied to a specific platform. It is\nnecessary to transfer it from one platform to another. For example a teacher\nwant to use a learning material from a content repository like\n[serlo.org](https://de.serlo.org/) in his learning management system or he wants\nto make a backup. To facilitate this sharing, a common exchange format is\nrequired between platforms. This document outlines a draft of Serlo's strategy\nfor making learning content transferable across different systems.\n\n## Overview\n\nInstead of reinventing the wheel we first researched and analyzed current\nsolutions for exchanging interactive educational material. With H5p there is\nalready an existing and widely used format as a foundation which we aim to\nsupport as well.\n\nH5p provides a platform for sharing interactive HTML5 content. With an H5p\ninstance, you can create and display H5P files. H5P packages all necessary data\ninto a single file, which can then be uploaded to another platform. The main\ncomponents of an H5P file are shown in the following image:\n\n![grafik](https://user-images.githubusercontent.com/13507950/217875199-b2b1584e-8d0b-4ee5-9dbd-8893cf168b0d.png)\n\nThe primary content, such as texts and plugins, is stored in a JSON file. The\nformat of the file is defined by the Serlo Editor and has a built-in mechanism\nfor migrations to ensure backward compatibility, as described in our\n[migration algorithm repository](https://github.com/serlo/lenabi-migration-algorithm).\nTherefore we aim to use H5P as a container in which we store the educational\nmaterial itself in the JSON file format of the Serlo editor.\n\nAdditionally, all media is included in the H5P file, making it possible to\nupload it to another platform. To render the content as intended, the code for\ndisplaying the content is also provided.\n\n## Details\n\n### The H5P container format\n\n#### The main idea behind H5P\n\nH5P defines a container format for educational content. It is comparable to a\n[Word document](https://en.wikipedia.org/wiki/Office_Open_XML) since both file\nformats are [ZIP files](\u003chttps://en.wikipedia.org/wiki/ZIP_(file_format)\u003e)\ncontaining the media and the data of the document. However there is a major\ndifference. A word document only contains the data of the document as well as\nthe media files (like images included in the word document):\n\n```\n       ┌────────────────────┐\n       │┌──────┐   ┌───────┐│\nWord = ││ Data │ + │ Media ││\n       │└──────┘   └───────┘│\n       │ZIP-file            │\n       └────────────────────┘\n```\n\nTherefore you need an already installed program on your computer to view and\nedit the document. In comparison H5P ships the code for rendering the\neducational content as JavaScript and CSS files inside the ZIP file:\n\n```\n       ┌───────────────────────────────┐\n       │┌──────┐   ┌───────┐   ┌──────┐│\nH5p =  ││ Data │ + │ Media │ + │ Code ││\n       │└──────┘   └───────┘   └──────┘│\n       │ZIP-file                       │\n       └───────────────────────────────┘\n```\n\nSo you can think of each H5P file as an individual App which displays a\nparticular educational content. This has some advantages:\n\n- Portability: The file itself is enough to install all necessary software on\n  your platform. This way, you don't need to download addition software, but you\n  are able to install the necessary libraries yourself on the platform with the\n  file.\n\n- Consistency: The content is displayed as you have created it, there are no\n  differences across different system.\n\n- Compatibility: Besides the official implementation of H5P for Drupal and\n  Moodle, there are new systems that implement the existing H5P specification.\n  Serlo Content stored in this exchange format can be added to these new systems\n  easily.\n\n#### Specification of H5P\n\nThe\n[H5P file format specification](https://h5p.org/documentation/developers/h5p-specification)\ndescribes a H5P file as a ZIP file with the ending `.h5p`. In case of a Serlo\ncontent the [file tree structure](https://h5p.org/specification) will be:\n\n```\n.\n├── h5p.json               # Meta / package file describing the content and file structure\n│\n├── content                # Directory with content and media files\n│   │\n│   ├── images                # Directory with media files\n│   │   └── explain.png\n│   │\n│   └── content.json          # JSON file describing the content\n│                               in the Serlo Editor content format\n│\n├── Serlo.Editor           # Main used library with source code and CSS\n│   ├── ...\n│   ├── index.js\n│   ├── style.css\n│   ├── library.json\n│   └── semantics.json\n│\n└── FontAwesome            # Additional libraries which are used (optional)\n    ├── ...\n    └── library.json\n```\n\nMeta data about the educational content (for displaying / using them in the H5P\nrepositories) as well as describing how the educational can be technically\nembedded are stored in the `h5p.json` file. It is called the\n[package definition file](https://h5p.org/documentation/developers/json-file-definitions)\nand it will look like:\n\n```json\n{\n  \"title\": \"Example content with the Serlo Editor\",\n  \"language\": \"de\",\n  \"mainLibrary\": \"Serlo.Editor\",\n  \"embedTypes\": [\"div\", \"iframe\"],\n  \"authors\": [\n    {\n      \"name\": \"Julia Sprothen\",\n      \"role\": \"Author\"\n    }\n  ],\n  \"source\": \"https://serlo.org/1656\",\n  \"license\": \"CC BY-SA\",\n  \"licenseVersion\": \"4.0\",\n  \"changes\": [\n    {\n      \"date\": \"02-07-19 11:27:00\",\n      \"author\": \"Julia Sprothen\",\n      \"log\": \"Erstellung eines Beispielinhalts\"\n    }\n  ],\n  \"preloadedDependencies\": [\n    {\n      \"machineName\": \"Serlo.Editor\",\n      \"majorVersion\": \"1\",\n      \"minorVersion\": \"0\"\n    }\n  ]\n}\n```\n\nThe content will be stored in the `content` directory. In case there are\nattached media files they will be stored in `images`. All major image and video\nare allowed (see\n[Allowed File Extensions](https://h5p.org/allowed-file-extensions)).\n\nThe code libraries must specify their name, dependencies, and other meta data in\nthe [Library Definition file](https://h5p.org/library-definition), and if it's a\nrunnable content type, it must also include a\n[Semantics Definition file](https://h5p.org/semantics) that describes the\ncontent's structure. In case of the Serlo editor the library definition will\nlook like\n\n```json\n{\n  \"title\": \"Serlo editor\",\n  \"description\": \"A WYSIWYG editor for educational material\",\n  \"machineName\": \"Serlo.Editor\",\n  \"majorVersion\": 1,\n  \"minorVersion\": 0,\n  \"patchVersion\": 0,\n  \"runnable\": 1,\n  \"author\": \"Serlo Education e.V.\",\n  \"license\": \"Apache License 2.0\",\n  \"coreApi\": {\n    \"majorVersion\": 1,\n    \"minorVersion\": 0\n  },\n  \"preloadedCss\": [{ \"path\": \"styles.css\" }],\n  \"preloadedJs\": [{ \"path\": \"index.js\" }],\n  \"preloadedDependencies\": [\n    {\n      \"machineName\": \"FontAwesome\",\n      \"majorVersion\": 3,\n      \"minorVersion\": 0\n    }\n  ]\n}\n```\n\nRefer to the official documentation for up-to-date information.\n\n### The content format of the Serlo editor\n\nThe educational material itself will be described in the file\n`content/content.json`. The root is an object which contains meta information as\nwell as information about the used version. We have documented this structure in\ndepth in our\n[documentation for the migration algorithm](https://github.com/serlo/lenabi-migration-algorithm):\n\n```json\n{\n  \"type\": \"https://serlo.org/editor\",\n  \"version\": 1,\n  \"content\": {\n    \"plugin\": \"article\",\n    \"state\": {}\n  }\n}\n```\n\nIt content itself is described in the article\n[content format of the Serlo editor](https://github.com/serlo/documentation/wiki/Content-format)\nin the wiki of our Serlo Editor. It represents educational material as nested\nblocks of educational content which we call `plugin`:\n\n![Plugin structure of the content format](https://raw.githubusercontent.com/serlo/documentation/main/images/main-content.png)\n\nThose plugins are stored in a JSON format so that they can be read and used in\nmany languages. The basic structure of a `plugin` is\n\n```JavaScript\n{\n  \"plugin\": \"...\", // name of the plugin\n  \"state\": ... // necessary information to describe the plugin\n}\n```\n\nThe article\n[content format of the Serlo editor](https://github.com/serlo/documentation/wiki/Content-format)\ncontains a detailed description of all plugins together with a description of\ntheir state.\n\n## Prototypes\n\nTo make sure that this approach will work, we have created two prototypes. The\nfirst one is located in [h5p-serlo-poc](https://github.com/serlo/h5p-serlo-poc).\nThis prototype defines a code library for H5P that is build with React and\nTypescript, the same foundation as the rendering of Serlo Content. The prototype\nimplements a simple renderer that takes a JSON input and displays is as react\ncomponent. This shows, that the approach in this document is workable and Serlo\nContent can be exported as `.h5p`-files and opened on a supported platform.\n\nWe can go further than only displaying the content. The second prototype located\nat [h5p-editor-serlo-poc](https://github.com/serlo/h5p-editor-serlo-poc) adds\nanother library that defines an editing widget that is rendered with React and\nTypescript. This way, it would be also possible to include the Serlo Editor into\nthe file and make the file editable. We are still evaluating the possibilities\nhere.\n\n## Limitations\n\nThere are some limitations to this approach that we are still researching. The\nfirst one is that the target platform still needs to install the library once\nand update it regularly. There are some ways to handle this:\n\n- Installation is simple and can be done quickly. We hope that this will\n  encourage platform administrators to install and update our library.\n- There are some major platforms that we have contact with. This way, we can\n  ensure that the library is installed and updated.\n\nOn a more technical basis, bundling all code into the file has great benefits\nfor portability, but it will also increase the file size. However, as a\ntransport format, we expect that the upsides will outweigh the downsides. Since\neach H5P file is basically an App / another website you include via iframe in\nyour website you should only use those files from trusted sources and authors.\n\nEditing the content on the other platform will need an integration of the Serlo\nEditor, which can be accomplished with another library. The technical foundation\nis available, as shown in the prototype. But there is still work needed to\nclearly define the scope of this possibility.\n\n## License\n\n\u003cimg src=\"https://github.com/serlo/lenabi-exchange-format/raw/main/assets/cc-by-sa.svg\" alt=\"Logo CC-BY-SA 4.0 license\" title=\"CC-BY-SA 4.0\" align=\"right\" width=\"150\" /\u003e\n\nThis specification is licensed under the\n[CC-BY-SA 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/). Please\nprovide [Serlo Education e.V.](https://serlo.org) together with the link to this\nrepository as the source attribution.\n\n## Funding\n\n\u003cimg src=\"https://github.com/serlo/lenabi-exchange-format/blob/main/assets/eu.png?raw=true\" alt=\"Logo European Commission\" title=\"European Comission\" align=\"right\" height=\"150\" /\u003e\n\u003cimg src=\"https://github.com/serlo/lenabi-exchange-format/blob/main/assets/bmbf.png?raw=true\" alt=\"Logo BMBF\" title=\"BMBF\" align=\"right\" height=\"150\" /\u003e\n\nThe project covered by this report has been financed by public means granted by\nthe German Ministry for Education and Research under the funding code LENABI2.\nThe responsibility for the content of this publication lies solely with the\nauthor.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserlo%2Flenabi-exchange-format","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserlo%2Flenabi-exchange-format","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserlo%2Flenabi-exchange-format/lists"}