JSON format for maps

Maps can be exported and imported as a JSON file. This page describes the format. The export file of an existing map is a reliable template for the structure of the JSON file. Not every exported field and not every setting is taken over on import, though, the tables below describe what is supported.

If you use the AI module in Edumaps, you do not need this format: open the “Map options” menu in the map and choose “Change Content”. There you describe in your own words what the AI should create or change.

Last updated: 7 November 2026, format version 2

1. Structure
2. Smallest useful file
3. Example
4. Data types
5. mapdata
6. Columns
7. Boxes
8. Arrows
9. Text fields
10. Text format
11. Files
12. What is not transferred
13. Limits
14. AI assistant
15. Further information

Structure of the file

A file contains exactly one JSON object with these keys. The import reads every key by its name, the order does not matter. Unknown keys are ignored without a message.

Smallest useful file

Only the title of the map is required. Everything else gets its default on import: an empty Pinboard with the default background, without columns and boxes. The two header keys formatversion and format are optional, the only required content is mapdata with a title. A file should still carry the header.

{
	"formatversion": 2,
	"format": "Edumaps map export. Box content uses the Edumaps text markup (Markdown-like, raw HTML is shown literally). Documentation: https://www.edumaps.de/docs/json",
	"mapdata": {
		"title": "My map"
	}
}

Example map

A map with two columns and three boxes. This file imports without errors.

{
	"formatversion": 2,
	"format": "Edumaps map export. Box content uses the Edumaps text markup (Markdown-like, raw HTML is shown literally). Documentation: https://www.edumaps.de/docs/json",
	"mapdata": {
		"title": "The water cycle",
		"subtitle": null,
		"tags": "geography grade5",
		"mapbg": "i10",
		"mapfont": "0",
		"mapformat": "0",
		"maptype": "0",
		"flags": "0",
		"language": "en",
		"extras": null
	},
	"paths": [
		{
			"title": "Basics",
			"visiblefrom": null,
			"visibleuntil": null,
			"annotation": null,
			"color": null,
			"flags": "0",
			"widthmode": "1",
			"extras": null,
			"boxes": [
				{
					"title": "What is the water cycle?",
					"content": "## In short\n\nWater is always on the move.\n\n- Evaporation\n- Condensation\n- Precipitation",
					"subject": "Geography",
					"booktime": null,
					"booklimit": "0",
					"color": null,
					"flags": "0",
					"ratingmode": "1",
					"position": null,
					"visiblefrom": null,
					"visibleuntil": null,
					"extras": null
				},
				{
					"title": "Read more",
					"content": "**Tip:** For an overview see {the Wikipedia article}{https://en.wikipedia.org/wiki/Water_cycle}.",
					"subject": null,
					"booktime": null,
					"booklimit": "0",
					"color": "#3a86ff",
					"flags": "16",
					"ratingmode": "0",
					"position": null,
					"visiblefrom": null,
					"visibleuntil": null,
					"extras": null
				}
			]
		},
		{
			"title": "Going further",
			"visiblefrom": null,
			"visibleuntil": null,
			"annotation": null,
			"color": null,
			"flags": "0",
			"widthmode": "0",
			"extras": null,
			"boxes": [
				{
					"title": "Rain, snow and hail",
					"content": "How water falls from the clouds is explained in the article {Precipitation}{https://en.wikipedia.org/wiki/Precipitation}.",
					"subject": null,
					"booktime": null,
					"booklimit": "0",
					"color": null,
					"flags": "0",
					"ratingmode": "0",
					"position": null,
					"visiblefrom": null,
					"visibleuntil": null,
					"extras": null
				}
			]
		}
	]
}

Data types

• The file is UTF-8 encoded and has the extension .json.
• The export writes every scalar value as a string or as null (objects and lists keep their JSON type), numbers and flags included (for example "0"). The only exception is formatversion, a JSON number. The import accepts numbers as a string and as a JSON number, "16" and 16 have the same effect.
• A missing field, null and an empty string mean the same: the import uses the default from the tables below.
• The string "0" is a valid text, also as a map title, box title and box content. Only null and "" are empty.
• If a field for text holds a list or an object, the field is skipped and counted in the message after the import. For the title and the annotation of a column the entries of a list are joined with spaces.
• Flags are sums of single values. A box filled with its color (16) and with a hidden title (64) has "80".
• Colors in the color fields are hex strings with a hash: "#RGB", "#RRGGBB" or "#RRGGBBAA". Other values are dropped, arrows then get "#0000ff", text fields "#ffff9c". Colors are stored in lowercase, uppercase input is accepted. Colored text in the box content only knows 3 or 6 digits (see below).
• Texts that are too long are shortened to the given length on import, the message after the import names their number.

Fields of mapdata

An imported map is always unpublished and unlocked. A map password is not part of the format.

Fields of a column (paths)

The values 8 and 16, together with visiblefrom and visibleuntil, correspond to the option “Visibility in map view” in the column editor: whoever only views the map never sees a hidden column, editors still see it in edit mode. The value 512 (“Hide from students in edit mode”) additionally hides the column in edit mode, but only for students.

Files of format version 1 may still carry the old values 64 (wide) and 128 (double width) for the column width, they are still imported. Older files (version 1) have one field showdate instead of visiblefrom and visibleuntil and are still imported: without the value 256 in flags it is taken as visiblefrom, with 256 as visibleuntil.

Example: the column appears on 1 November 2026 at midnight. Before that, viewers only see its title with the note “Appears on …”, not yet its boxes.

"flags": "16",
"visiblefrom": "2026-11-01"

Fields of a box (boxes)

The values 8192, 16384 and 32768, together with visiblefrom and visibleuntil, correspond to the option “Visibility in map view” in the box editor: whoever only views the map never sees a hidden box or its hidden content, editors still see both in edit mode. The value 2097152 (“Hide from students in edit mode”) additionally hides the box in edit mode, but only for students.

Files of format version 1 may still carry the old values 2, 256 and 512 for the rating, they are still imported. Older files (version 1) have one field showdate instead of visiblefrom and visibleuntil and are still imported: without the value 1048576 in flags it is taken as visiblefrom, with 1048576 as visibleuntil.

Further values belong to calendars and bookings (4096, 131072, 524288). Only take them over from an export file. All other values, for example for sales, course progress and the full lock, are removed on import.

The value 32768 only works before the time in visiblefrom. After visibleuntil a box is always hidden completely.

Example: the box is visible until Friday, 18 December 2026, 7 a.m., with the note “Visible until …”. After that it disappears completely for viewers. A date without a time means midnight at the start of that day: with "2026-12-31" the box is already gone on 31 December, if it should stay visible throughout 31 December, write "2027-01-01".

"flags": "0",
"visibleuntil": "2026-12-18 07:00:00"

Arrows (arrows)

Arrows can only be added in the Sticker Wall map format (mapformat 2). Their position refers to the whole map, not to a box or column. On the Pinboard, boxes and columns shift dynamically, an arrow would stay in its old place and point at the wrong content. If arrows or labels are in a file with a different mapformat, they are still imported and shown at their position, but none can be added there and they can shift out of place. More on this in the frequently asked questions.

Text fields (labels)

Like arrows, text fields can only be added in the Sticker Wall map format (mapformat 2), their position refers to the whole map.

Box content: the Edumaps text format (Markdown-like)

The content of a box is plain text in the Edumaps text format (Markdown-like), a format of its own with its own rules. A blank line separates paragraphs, consecutive lines are joined with a line break.

HTML is not executed. Tags such as <p>, <ul> or <a href=...> appear in the box as visible text. Only the Edumaps tags from the table are kept, as a block like <check> and within the text like <small>, written exactly like this (lowercase) and without attributes.

The blocks <check>, <check-yesno>, <poll>, <quiz> and <test…> start with the opening tag on a line of its own and end with the closing tag on a line of its own. There is one blank line before the opening tag and one after the closing tag, none in between. A box holds at most one <quiz> block and at most one <poll…> or <check…> block, because answers are stored by the position of the options. For several quiz questions, use one box per question. If a box holds more, the import rejects the whole map and names every affected box. Not supported are tables in the form | A | B |, headings with ####, embedded videos from other websites (iframe, a YouTube link becomes a preview image) and your own HTML. Video files uploaded to Edumaps, on the other hand, appear as a preview image in the box and play in an overlay after a click.

Files

Every link to an Edumaps file in the JSON file is copied into the importing account on import, regardless of whether the file comes from the same server or from another Edumaps server and of who owns it. The link then points to the copy, and the copy uses storage of that account. There is no option to keep the original links on import. All other links stay links. If a copy fails, the original link remains.

What is not transferred

• Passwords of the map, the columns and the boxes, and all access codes. The imported map gets new codes.
• Publishing, lock and delete protection of the map. The imported map is unpublished and belongs to the importing account.
• Comments, ratings and likes, calendar entries and bookings, shares and folders, the history of changes.
• The field extras of the boxes.
• An export through a read link contains no hidden columns and boxes, no content of protected boxes and no notes with //. Embedded boxes and columns appear in the export as a copy.

Limits on import

• Maximum size of the JSON import file: 2 MB.
• At most 5 JSON imports per minute per account.
• Every import creates a new map and counts toward the map limit of your plan.
• The storage of the account must not be full.
• More than 100 columns: the import is refused.
• At most 500 boxes, 300 arrows and 300 text fields, as in the editor. Anything above is left out, the message after the import names the number.
• Text lengths: see the tables above.

Creating maps with an AI assistant

1. Create a small sample map in Edumaps, with columns and boxes the way you picture them.
2. Export this map as a JSON file.
3. Give the file to the assistant (for example Claude or ChatGPT) as a template, together with this instruction:

Create an Edumaps map as a valid JSON file. Use the attached export file as the template for structure and settings and follow the fields and rules at https://www.edumaps.de/docs/json. Leave out fields that are not documented there.
Rules:
- The file starts with "formatversion": 2 and "format", followed by "mapdata" and "paths". Use only the documented keys, "arrows" and "labels" only if arrows or text fields are wanted, and only with "mapformat": "2" (Sticker Wall).
- Each column goes into "paths", each box into "boxes" of its column.
- Write numbers and flags as strings, for example "flags": "0". Only "formatversion" is the number 2 without quotes.
- Rating of a box with "ratingmode": "0" off, "1" good / medium / bad, "2" yes / maybe / no, "3" option A / B / C. Width of a column with "widthmode": "0" normal, "1" wide, "2" double width.
- Write out all fields of the template, empty ones as null (the import also accepts missing fields).
- Box content in the Edumaps text format (Markdown-like): **bold**, bullet lists with "- ", a blank line between paragraphs, headings with "# ", "## " or "### ".
- No HTML: HTML tags appear in Edumaps as visible text.
- Numbered lists with "-- " at the start of the line. A line that starts with "1." stays plain text.
- Write links as {link text}{https://...}.
- Separate the keywords in "tags" with spaces, no commas, no space inside a keyword.
- If you can create files, offer a UTF-8 file named edumaps-map.json for download, otherwise output the JSON as text. The JSON must be syntactically valid, without explanations.
Content of the map: (describe here what the map should contain)

4. Upload the finished file under “Import Edumaps file”.

Further information

You open the JSON import on the page “Import Edumaps file” or in the sidebar via “Create Map” → “Import” → “Import Edumaps file”. The import requires a login and always creates a new map, it never overwrites an existing one. The export file of a map comes from the export menu of the map.

Export files can contain personal data, for example in box titles, box contents or notes. Check the file before you upload it to an external AI service.

Which other interfaces Edumaps offers is explained in the frequently asked questions.