Skip to content

Roadmap Plugin

Bundled with iolanta ⩾ 2.1.12

iolanta iolanta-development-roadmap.yamlld --as https://iolanta.tech/roadmap/datatypes/mermaid

graph LR
  Bbae84bb3037d("Tractatus Logico-Philosophicus → LD")
  B0edf7b956318("Discovery MCP discovers LD based on free form text")
  B368c01d14192("Unblock Nanopubs")
  B988d5d3c5240("Inference depends on alphabetical order of its CONSTRUCT queries")
  Bdbc3719a0b3f("HOWTO Make your own facet")
  https___iolanta_tech_Facet("Generate Facets list")
  click https___iolanta_tech_Facet "https://iolanta.tech/Facet/"
  B9665037a78d8("Render a Decision Matrix with Iolanta")
  B071c9be8f1db("Generate this roadmap from LD")
  Bfff5e8989b4e("Render LD from IPFS")
  Bf21d26c7c614("<code>mermaid</code> datatype from roadmap plugin does not resolve nor is documented")
  B804d0b3c994c("First WASM based facet")
  Bd89247cea044("Upper ontology not chosen for <code>roadmap</code>")
  Bb40f83e8cf24("Implement YAML-LD Ontology")
  B90ca643a0ed2("Manage ADRs with Iolanta")
  B2278567e7da9("Armenian pronouns nanopub")
  B7b16b4b4b96f("pyld fails on lexinfo")
  Bf9f7a63858f6("Roadmap <code>Unblocked</code> is a <code>Class</code>")
  B80f2020766e8("<code>$type: Bug</code> does not work; maybe use some other syntax even?")
  Bd75d10abd3fa("Write nanopublications with Iolanta")
  Bae6299a47bc6("Implement a 3D view for the roadmap (because should look cool)")
  https___github_com_Nanopublication_nanopub-py_pull_180("PR 180: Nanopublication/nanopub-py is merged")
  click https___github_com_Nanopublication_nanopub-py_pull_180 "https://github.com/Nanopublication/nanopub-py/pull/180"
  Ba6a5b3b337be("Start jeeves-nanopublications")
  B5d5d954aad6e("Build roadmaps & plans with Iolanta")
  Baa1bc7cbbeb4("Unable to specify if <code>Event</code> had happened")
  B5509ab3b3751("FOAF Title facet only reacts on foaf:Person class")
  B17e2df495f49("Iolanta starts with a blank console")
  Bb5cfa37f5673("SPARQL inference handled by sparqlspace")
  B6151f70f5ab2("sparqlspace has no integration tests")
  B6237e145dbd0("FOAF Title facet only reacts on foaf:Person class")
  B7f6c54146532("Iolanta starts with a blank console")
  Bbe4d7431dc66("SPARQL inference handled by sparqlspace")
  B8cffaa83c000("sparqlspace has no integration tests")
  Bd84618b7f641("pyld fails on lexinfo")
  B0edf7b956318 --> Bd75d10abd3fa
  B7b16b4b4b96f --> B2278567e7da9
  B368c01d14192 --> B2278567e7da9
  B9665037a78d8 --> B90ca643a0ed2
  Bd89247cea044 --> B80f2020766e8
  Bd89247cea044 --> Baa1bc7cbbeb4
  Bd89247cea044 --> Bf9f7a63858f6
  B90ca643a0ed2 --> B5d5d954aad6e
  B071c9be8f1db --> B5d5d954aad6e
  B5d5d954aad6e --> Bae6299a47bc6
  B368c01d14192 --> https___github_com_Nanopublication_nanopub-py_pull_180
  B368c01d14192 --> Ba6a5b3b337be
  B368c01d14192 --> B0edf7b956318
  classDef predicate fill:#1f2233,stroke:transparent,color:#f8fafc,stroke-width:0px;
  classDef hidden fill:transparent,stroke:transparent,color:transparent,stroke-width:0px;
  classDef label fill:transparent,stroke:transparent,color:#e5e7eb,stroke-width:0px;
  classDef nanopubdot fill:#0f172a,stroke:#0f172a,color:transparent,stroke-width:2px;
  classDef transparent fill:transparent,stroke:transparent,color:transparent,stroke-width:0px;
  class 7e8f446d3164,d0a510126a11,936d868d41f4,c8f3391f6f6d,fad8ff6cfa64,5cf1b681b750,df8266c58034,470d7700efd5,e258e7290f29,a15eb121ff9b,934495b48142,3f9119679c2a,308eb0799615 predicate
classDef unblocked fill:#0a5,stroke:#063,stroke-width:2px,color:#fff;
class Bbae84bb3037d unblocked
class B368c01d14192 unblocked
class B988d5d3c5240 unblocked
class Bdbc3719a0b3f unblocked
class https___iolanta_tech_Facet unblocked
class B9665037a78d8 unblocked
class B071c9be8f1db unblocked
class Bfff5e8989b4e unblocked
class Bf21d26c7c614 unblocked
class B804d0b3c994c unblocked
class Bd89247cea044 unblocked
class Bb40f83e8cf24 unblocked
class B7b16b4b4b96f unblocked
class B5509ab3b3751 unblocked
class B17e2df495f49 unblocked
class Bb5cfa37f5673 unblocked
class B6151f70f5ab2 unblocked
iolanta-development-roadmap.yamlld (top 20 lines)
"@context": https://iolanta.tech/roadmap/contexts/v0.1.yamlld

tasks:
  # IPFS rendering
  - $id: _:ipfs
    $: Render LD from IPFS

  # Decision Matrix & ADRs workflow
  - $id: _:render-decision-matrix
    $: Render a Decision Matrix with Iolanta
    blocks:
      - $id: _:manage-adrs
        $: Manage ADRs with Iolanta
        blocks:
          - $id: _:manage-roadmaps
            $: Build roadmaps & plans with Iolanta
            blocks:
              - $id: _:roadmap3d
                $: Implement a 3D view for the roadmap (because should look cool)

# …

Quick Start

To use the Roadmap plugin in your roadmap files, import the context:

"@context": https://iolanta.tech/roadmap/contexts/v0.1.yamlld

This context provides the namespace prefixes and property mappings you need to write roadmap data.

Minimal Example

"@context": https://iolanta.tech/roadmap/contexts/v0.1.yamlld

$included:
  - $id: _:complete-docs
    $type: roadmap:Task
    $: Complete documentation
    blocks:
      - $: Publish release
        $type: roadmap:Task

Nesting Tasks

Tasks can be nested directly under blocks: or is-blocked-by: properties. This creates a more compact and readable structure:

- $type: roadmap:Task
  $: Main task
  blocks:
    - $: Subtask 1
      $type: roadmap:Task
    - $: Subtask 2
      $type: roadmap:Task
      blocks:
        - $: Nested subtask
          $type: roadmap:Task

Identifiers

When you need to reference a roadmap item from another item (using blocks or is-blocked-by), you must give it an identifier using $id. In roadmap files, identifiers should be blank nodes using the _: prefix:

  • ✅ Good: $id: _:implement-auth
  • ❌ Bad: $id: roadmap:task-1 (full URI not needed for local references)

If an item is not referenced anywhere else in your roadmap, you don't need to provide an $id at all. You only need an identifier when: - The item is referenced from elsewhere (e.g., blocks: [_:some-task]) - The item needs to be referenced later in the file

Data Model

The Roadmap plugin uses the following classes and properties:

  • roadmap:Task

    A to-do item or feature
    Subclass of prov:Activity

  • roadmap:Bug

    A known issue
    Subclass of roadmap:Task

  • roadmap:Event

    A scheduled event or milestone
    Subclass of prov:Activity

  • → roadmap:blocks

    Indicates that one item blocks another
    Inverse of roadmap:is-blocked-by, subproperty of prov:wasInformedBy

  • ← roadmap:is-blocked-by

    Indicates that one item is blocked by another
    Inverse of roadmap:blocks, subproperty of prov:wasInformedBy

Relationship to PROV Ontology

The roadmap vocabulary builds on the PROV ontology (prov:Activity, prov:wasInformedBy), allowing roadmap items to be integrated with provenance tracking and activity descriptions.

Rendering

Command Line

Render a roadmap file as a Mermaid diagram:

iolanta path/to/roadmap.yamlld --as https://iolanta.tech/roadmap/datatypes/mermaid

In MkDocs

Use the Iolanta template to render roadmaps in your documentation:

{{ (docs / 'path/to/roadmap.yamlld') | as('https://iolanta.tech/roadmap/datatypes/mermaid') }}

Exporting to Images

Generate PNG or SVG images from your roadmap for use in blogs, documentation, or presentations:

# Generate PNG
iolanta path/to/roadmap.yamlld --as https://iolanta.tech/roadmap/datatypes/mermaid | mmdc -i - -o roadmap.png

# Generate SVG
iolanta path/to/roadmap.yamlld --as https://iolanta.tech/roadmap/datatypes/mermaid | mmdc -i - -o roadmap.svg -b transparent

This requires @mermaid-js/mermaid-cli to be installed. Install it with:

npm install -g @mermaid-js/mermaid-cli

Context Versioning

The roadmap context is versioned to ensure stability. Current version:

  • v0.1: https://iolanta.tech/roadmap/contexts/v0.1.yamlld

When referencing the context, pin to a specific version (e.g., v0.1) for stability.

Future versions will be published at https://iolanta.tech/roadmap/contexts/v<version>.yamlld.